Sugerir alterações
Ajude-nos a melhorar a documentação
Você viu informações equivocadas, gostaria que explicássemos algo a mais ou que melhorássemos nossos manuais? Deixe suas sugestões no GitHub.

Notificações IPN

Pré-requisitos

O IPN (Instant Payment Notification) é uma notificação enviada de um servidor a outro mediante uma chamada HTTP POST para informar sobre suas transações.

Para receber notificações de eventos na sua plataforma, você pode configurar previamente uma notification_url à qual Mercado Pago tiver acesso.

Eventos

Notificamos eventos relacionados aos seus pedidos (merchant_orders), estornos recebidos (chargebacks) ou pagamentos recebidos (payment).

A merchant_order é uma entidade que pode conter tanto pagamentos como envios. Você terá que consultar os dados dos pedidos notificados.

Sempre que ocorrer um evento relacionado a algum dos recursos mencionados, enviaremos uma notificação utilizando HTTP POST para a URL especificada.

Se a aplicação não estiver disponível ou demorar para responder, o Mercado Pago irá fazer tentativas de notificação nos seguintes intervalos:

  1. Tentativa após 5 minutos.
  2. Tentativa após 45 minutos.
  3. Tentativa após 6 horas.
  4. Tentativa após 2 dias.
  5. Tentativa após 4 dias.

O Mercado Pago informará essa URL quando um recurso for criado ou quando houver atualização do status dos pagamentos ou pedidos, com dois parâmetros:

Campo Descrição
topic Identifica do que se trata o recurso. Pode ser payment, chargebacks ou merchant_order
id É um identificador único do recurso notificado.

Exemplo: Se configurar a URL: https://www.yoursite.com/notifications, você receberá as notificações de pagamento desta maneira: https://www.yoursite.com/notifications?topic=payment&id=123456789.

O que devo fazer ao receber uma notificação?

Quando receber uma notificação na sua plataforma, o Mercado Pago espera uma resposta para validar que a recebeu corretamente. Para isso, você deve retornar um HTTP STATUS 200 (OK) ou 201 (CREATED).

Lembre-se que esta comunicação é feita exclusivamente entre os servidores do Mercado Pago e o seu servidor, de modo que não haverá um usuário físico vendo nenhum tipo de resultado.

Depois disso, você poderá obter a informação completa do recurso notificado acessando a API correspondente em https://api.mercadopago.com/:

Tipo URL Documentação
payment /v1/payments/[ID]?access_token=[ACCESS_TOKEN] ver documentação
chargebacks /v1/chargebacks/[ID]?access_token=[ACCESS_TOKEN] -
merchant_orders /merchant_orders/[ID]?access_token=[ACCESS_TOKEN] ver documentação

Notificações para pagamentos presenciais

Se você estiver integrando pagamentos presenciais, recomendamos utilizar notificações IPN de topic merchant_order. Para isso, lembre das seguintes regras:

  1. O campo status da merchant_order permanecerá em opened quando ainda não tiver pagamentos associados, ou tiver pagamentos recusados ou aprovados por um valor menor ao total da ordem.
  2. O campo status da merchant_order será closed quando a soma dos pagamentos aprovados for igual ou superior ao total da ordem.

Dentro da ordem, no objeto payments, você vai encontrar todos os pagamentos dela. É importante obter a ID dos pagamentos com status = approved para poder realizar restituições.

ATENÇÃO

Quando o status da merchant_order for closed, certifique-se de que a soma dos pagamentos com status approved seja igual ou maior ao total da ordem.

Implemente o receptor de notificações usando o seguinte código como exemplo:

Php

<?php
    MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

    $merchant_order = null;

    switch($_GET["topic"]) {
        case "payment":
            $payment = MercadoPago\Payment::find_by_id($_GET["id"]);
            // Get the payment and the corresponding merchant_order reported by the IPN.
            $merchant_order = MercadoPago\MerchantOrder::find_by_id($payment->order->id);
            break;
        case "merchant_order":
            $merchant_order = MercadoPago\MerchantOrder::find_by_id($_GET["id"]);
            break;
    }

    $paid_amount = 0;
    foreach ($merchant_order->payments as $payment) {   
        if ($payment['status'] == 'approved'){
            $paid_amount += $payment['transaction_amount'];
        }
    }

    // If the payment's transaction amount is equal (or bigger) than the merchant_order's amount you can release your items
    if($paid_amount >= $merchant_order->total_amount){
        if (count($merchant_order->shipments)>0) { // The merchant_order has shipments
            if($merchant_order->shipments[0]->status == "ready_to_ship") {
                print_r("Totally paid. Print the label and release your item.");
            }
        } else { // The merchant_order don't has any shipments
            print_r("Totally paid. Release your item.");
        }
    } else {
        print_r("Not paid yet. Do not release your item.");
    }

?>

Para obter seu ACCESS_TOKEN, verifique a seção de Credenciais

Pesquisa da ordem

Si estas integrando pagos presenciales, se debe implementar como método de contingencia, la búsqueda de la orden utilizando el external_reference de la misma como criterio de búsqueda.

Se você estiver integrando pagamentos presenciais, é necessário aplicar como método de contingência a pesquisa da ordem utilizando o seu external_reference como critério de pesquisa.

Curl

curl -X GET https://api.mercadopago.com/merchant_orders?external_reference=$EXTERNAL_REFERENCE&access_token=$ACCESS_TOKEN -d

Mais informações na Referência de API.

A pesquisa pode ser realizada por external_reference de duas formas:

Formas Descrição
Manual O ponto de venda deve incluir um botão para realizar a pesquisa.
Automática Após um tempo razoável sem ter recebido qualquer notificação, é iniciada uma pesquisa da ordem a cada um intervalo de, por exemplo, 5 segundos.

Por cada escaneamento do QR é gerada uma merchant_order diferente. Lembre que caso o cliente faça mais de um escaneamento, uma ordem ficará em open por tempo indefinido. Para encerrar a transação, a merchant_order deve ter status = closed.

Caso a pesquisa seja realizada após o escaneamento do QR, vão se obter todos os dados referidos à ordem:

Json

{
  "id": 1126664483,
  "status": "closed",
  "payments": [
     {
      "id": 4996721469,
      "transaction_amount": 4,
      "status": "rejected",
      [...],
    },
     {
      "id": 4996721476,
      "transaction_amount": 4,
      "status": "approved",
      [...], }, 

Caso contrário, se o QR no qual a ordem foi publicada ainda não foi escaneado, a resposta será:

Json

{
   "elements": null,
   "next_offset": 0,
   "total": 0
 }
ATENÇÃO

Mercado Pago requer a integração de pagamentos presenciais que tiverem aplicada a notificação (IPN) como método principal para a homologação. A pesquisa de ordem por external_reference deverá ser somente utilizada como contingência no caso eventual de não se receberem notificações.

Sua pesquisa não retorna resultados.

Check the spelling of search terms or test with other keywords.