Configurar URLs de retorno
A URL de retorno e o endereco para o qual o comprador e redirecionado apos completar o pagamento, seja ele bem-sucedido, falho ou pendente. Esta URL deve ser uma pagina web controlavel, como um servidor com dominio nomeado (DNS).
Com a Orders API, as URLs de retorno sao configuradas diretamente no corpo da solicitacao de criacao da Order, dentro do objeto checkout_pro. Voce pode configurar ate tres URLs de retorno diferentes, correspondendo aos cenarios de pagamento bem-sucedido, falho ou pendente, e o comportamento de redirecionamento automatico.
Definir URLs de retorno
Para configurar as URLs de retorno, inclua os atributos back_urls e auto_return dentro do objeto checkout_pro ao criar a Order por meio de uma solicitacao POST para o endpoint /v1/orders.
A seguir, compartilhamos um exemplo de como incluir as URLs de retorno na criacao da Order.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: UNIQUE_KEY' \ -d '{ "type": "online", "total_amount": "1000.00", "external_reference": "order_pro_123", "payer": { "email": "buyer@email.com" }, "transactions": { "payments": [ { "amount": "1000.00" } ] }, "checkout_pro": { "back_urls": { "success": "https://www.seu-site.com/success", "failure": "https://www.seu-site.com/failure", "pending": "https://www.seu-site.com/pending" }, "auto_return": "approved" } }'
| Atributo | Descricao |
auto_return | Os compradores sao redirecionados automaticamente ao site quando o pagamento e aprovado. O valor padrao e approved. O tempo de redirecionamento sera de ate 40 segundos e nao podera ser personalizado. Por padrao, tambem sera exibido um botao de "Voltar ao site". |
back_urls | URL de retorno ao site. Os cenarios possiveis sao: success: URL de retorno quando o pagamento e aprovado.pending: URL de retorno quando o pagamento esta pendente.failure: URL de retorno quando o pagamento e rejeitado. |
Resposta das URLs de retorno
As back_urls fornecem varios parametros uteis por meio de uma solicitacao GET. A seguir, apresentamos um exemplo de resposta, acompanhado de uma explicacao detalhada dos parametros incluidos nela.
curl
GET /success?payment_id=123456789&status=approved&external_reference=order_pro_123&order_id=987654321 HTTP/1.1 Host: www.seu-site.com
| Parametro | Descricao |
payment_id | ID (identificador) do pagamento do Mercado Pago. |
status | Status do pagamento. Por exemplo: approved para um pagamento aprovado ou pending para um pagamento pendente. |
external_reference | Referencia para sincronizacao com seu sistema de pagamentos. |
order_id | ID (identificador) da Order criada no Mercado Pago. |
Resposta para meios de pagamento offline
Os meios de pagamento offline permitem que o comprador selecione um metodo que exija a utilizacao de um ponto de pagamento fisico para concluir a transacao. Nesse fluxo, o Mercado Pago gera um comprovante que o comprador deve apresentar no estabelecimento para realizar o pagamento. Apos essa etapa, o comprador sera redirecionado para a URL definida no atributo back_urls como pending.
Nesse momento, o pagamento estara em estado pendente, ja que o comprador ainda precisa efetuar o pagamento presencialmente no estabelecimento indicado.
Para pagamentos com o estado pending, sugerimos redirecionar o comprador para o seu site e fornecer orientacoes claras sobre como concluir o pagamento.
Assim que o pagamento for realizado no ponto fisico com o comprovante gerado, o Mercado Pago sera notificado, e o estado do pagamento sera atualizado. Recomendamos que voce configure as notificacoes de pagamento para que seu servidor receba essas atualizacoes e atualize o estado do pedido na sua base de dados.