Configurar URLs de retorno
Server-Side
As URLs de retorno definem para onde o comprador é redirecionado ao concluir o pagamento no checkout do Mercado Pago. Configure-as no objeto config.online da requisição de criação da order para tratar cada resultado da transação de forma independente no seu sistema, seja o pagamento aprovado, rejeitado ou pendente.
Envie um POST ao endpoint Criar orderAPI com os atributos success_url, failure_url, pending_url e auto_return dentro do objeto config.online, além dos demais parâmetros de pagamento. Cada URL corresponde a um resultado possível da transação, sendo as três opcionais. Configure apenas as que forem relevantes para o fluxo do seu negócio. Para mais detalhes sobre a requisição completa, consulte Criar e configurar uma order de pagamento.
auto_return controla o redirecionamento automático após o pagamento. Configure "approved" para redirecionar somente em pagamentos aprovados ou "all" para qualquer resultado. Em ambos os casos, inclua success_url na mesma requisição.curl -X POST \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
-H 'X-Idempotency-Key: UNIQUE_KEY' \
'https://api.mercadopago.com/v1/orders' \
-d '{
"type": "online",
"processing_mode": "manual",
"total_amount": "1000.00",
"external_reference": "order_pro_123",
"payer": {
"email": "buyer@email.com"
},
"config": {
"notification_url": "https://www.your-site.com/webhooks",
"online": {
"success_url": "https://www.your-site.com/success",
"failure_url": "https://www.your-site.com/failure",
"pending_url": "https://www.your-site.com/pending",
"auto_return": "approved"
}
}
}'Veja na tabela abaixo a descrição de cada atributo do objeto config.online utilizado para configurar as URLs de retorno e o comportamento do redirecionamento automático.
| Atributo | Tipo | Descrição | Exemplo | Obrigatoriedade |
config.online.success_url | String | URL de retorno quando o pagamento é aprovado. O comprador é redirecionado automaticamente para essa URL assim que o pagamento é concluído. | "https://www.your-site.com/success" | Opcional |
config.online.failure_url | String | URL de retorno quando o pagamento é rejeitado ou cancelado. | "https://www.your-site.com/failure" | Opcional |
config.online.pending_url | String | URL de retorno quando o pagamento está pendente. | "https://www.your-site.com/pending" | Opcional |
config.online.auto_return | String | Controla o comportamento do redirecionamento automático após o pagamento. Use "approved" para redirecionar o comprador para success_url apenas quando o pagamento é aprovado. Use "all" para redirecionar o comprador em qualquer resultado do pagamento. | "approved" | Opcional |
Quando o comprador conclui o pagamento no ambiente do Mercado Pago, ele é redirecionado automaticamente para a URL de retorno configurada. Nesse redirecionamento, o Mercado Pago anexa parâmetros à URL com informações sobre a transação. Seu servidor os recebe por meio de uma requisição GET e deve utilizá-los para confirmar o resultado do pagamento e atualizar o status da order no seu sistema.
http
GET /success?collection_id=106400160592&collection_status=approved&payment_id=106400160592&status=approved&external_reference=order_pro_123&payment_type=credit_card&merchant_order_id=29900492508&preference_id=724484980-ecb2c41d-ee0e-4cf4-9950-8ef2f07d3d82&site_id=MLB&processing_mode=aggregator&merchant_account_id=null HTTP/1.1 Host: www.your-site.com Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7 Accept-Encoding: gzip, deflate, br, zstd Accept-Language: pt-BR,pt;q=0.9 Connection: keep-alive Referer: https://www.mercadopago.com/checkout/v1/payment/redirect/505f641c-cf04-4407-a7ad-8ca471419ee5/congrats/approved/?preference-id=724484980-ecb2c41d-ee0e-4cf4-9950-8ef2f07d3d82&router-request-id=0edb64e3-d853-447a-bb95-4f810cbed7f7&p=f2e3a023dd16ac953e65c4ace82bb3ab Sec-Ch-Ua: "Chromium";v="134", "Not:A-Brand";v="24", "Google Chrome";v="134" Sec-Ch-Ua-Mobile: ?0 Sec-Ch-Ua-Platform: "macOS" Sec-Fetch-Dest: document Sec-Fetch-Mode: navigate Sec-Fetch-Site: cross-site Sec-Fetch-User: ?1 Upgrade-Insecure-Requests: 1
Veja na tabela abaixo a descrição de cada parâmetro recebido no redirecionamento.
| Parâmetro | Descrição |
collection_id | ID da cobrança no Mercado Pago. Contém o mesmo valor que payment_id. |
collection_status | Status da cobrança. Espelha o valor do campo status. |
payment_id | ID do pagamento no Mercado Pago. |
status | Status do pagamento. Retorna approved para pagamento aprovado, rejected para rejeitado ou pending para pendente. |
external_reference | Referência da order no seu sistema, definida no momento da criação. |
payment_type | Tipo de meio de pagamento utilizado. Por exemplo, credit_card ou ticket. |
order_id | ID da order retornado após a sua criação. |
merchant_order_id | ID único da order de pagamento criada no Mercado Pago. |
preference_id | ID da preferência associada à order, gerada internamente pela API de Orders. |
site_id | Identificador do país da conta do vendedor no Mercado Pago. Por exemplo, MLB para Brasil. |
processing_mode | Modo de processamento da transação. |
merchant_account_id | ID da conta do seller no contexto de marketplace. Retorna nulo quando não se aplica. |
Pagamentos com status pendente
Alguns meios de pagamento exigem que o comprador conclua a transação fora do Checkout Pro. Nesses casos, o Mercado Pago redireciona o comprador para a URL configurada em config.online.pending_url, com o pagamento aguardando confirmação.
Enquanto a confirmação não chegar, a transação permanece em aberto.
Assim que o pagamento for confirmado, o Mercado Pago atualiza o status da order e envia uma notificação ao seu servidor. Configure as notificações de pagamento para que seu servidor receba essas atualizações e reflita o novo estado da transação na sua base de dados.
O próximo passo é adicionar o SDK ao frontend para renderizar o botão de pagamento e inicializar o checkout. Acesse Adicionar o SDK ao frontend e inicializar o checkout para continuar a integração.