Configurar URLs de retorno
Server-Side
Las URLs de retorno definen a dónde se redirige al comprador al completar el pago en el checkout de Mercado Pago. Configúralas en el objeto config.online de la solicitud de creación de la order para gestionar cada resultado de la transacción de forma independiente en tu sistema, ya sea el pago aprobado, rechazado o pendiente.
Envía un POST al endpoint Crear orderAPI con los atributos success_url, failure_url, pending_url y auto_return dentro del objeto config.online, además de los demás parámetros de pago. Cada URL corresponde a un posible resultado de la transacción, siendo las tres opcionales. Configura solo las que sean relevantes para el flujo de tu negocio. Para más detalles sobre la solicitud completa, consulta Crear y configurar una order de pago.
auto_return controla el redireccionamiento automático después del pago. Configura "approved" para redirigir solo en pagos aprobados o "all" para cualquier resultado. En ambos casos, incluye success_url en la misma solicitud.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"
}
}
}'La siguiente tabla describe cada atributo del objeto config.online utilizado para configurar las URLs de retorno y el comportamiento del redireccionamiento automático.
| Atributo | Tipo | Descripción | Ejemplo | Obligatorio |
config.online.success_url | String | URL de retorno cuando el pago es aprobado. El comprador es redirigido automáticamente a esta URL una vez completado el pago. | "https://www.your-site.com/success" | Opcional |
config.online.failure_url | String | URL de retorno cuando el pago es rechazado o cancelado. | "https://www.your-site.com/failure" | Opcional |
config.online.pending_url | String | URL de retorno cuando el pago está pendiente. | "https://www.your-site.com/pending" | Opcional |
config.online.auto_return | String | Controla el comportamiento del redireccionamiento automático después del pago. Usa "approved" para redirigir al comprador a success_url solo cuando el pago es aprobado. Usa "all" para redirigir al comprador en cualquier resultado del pago. | "approved" | Opcional |
Cuando el comprador completa el pago en el ambiente de Mercado Pago, es redirigido automáticamente a la URL de retorno configurada. En ese redireccionamiento, Mercado Pago anexa parámetros a la URL con información sobre la transacción. Tu servidor los recibe mediante una solicitud GET y debe utilizarlos para confirmar el resultado del pago y actualizar el estado de la order en tu 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: es-419,es;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
La siguiente tabla describe cada parámetro recibido en el redireccionamiento.
| Parámetro | Descripción |
collection_id | ID del cobro en Mercado Pago. Contiene el mismo valor que payment_id. |
collection_status | Estado del cobro. Refleja el valor del campo status. |
payment_id | ID del pago en Mercado Pago. |
status | Estado del pago. Retorna approved para pago aprobado, rejected para rechazado o pending para pendiente. |
external_reference | Referencia de la order en tu sistema, definida en el momento de la creación. |
payment_type | Tipo de medio de pago utilizado. Por ejemplo, credit_card o ticket. |
order_id | ID de la order devuelto tras su creación. |
merchant_order_id | ID único de la order de pago creada en Mercado Pago. |
preference_id | ID de la preferencia asociada a la order, generada internamente por la API de Orders. |
site_id | Identificador del país de la cuenta del vendedor en Mercado Pago. Por ejemplo, MLB para Brasil. |
processing_mode | Modo de procesamiento de la transacción. |
merchant_account_id | ID de la cuenta del seller en el contexto de marketplace. Retorna nulo cuando no aplica. |
Pagos con estado pendiente
Algunos medios de pago requieren que el comprador complete la transacción fuera de Checkout Pro. En estos casos, Mercado Pago redirige al comprador a la URL configurada en config.online.pending_url, con el pago en espera de confirmación.
Checkout Pro genera un comprobante que el comprador presenta en un establecimiento físico para completar el pago del boleto bancário. Con el Pix, el pago queda a la espera de la confirmación de la transferencia bancaria.
Mientras no llegue la confirmación, la transacción permanece abierta.
Cuando el pago sea confirmado, Mercado Pago actualiza el estado de la order y envía una notificación a tu servidor. Configura las notificaciones de pago para que tu servidor reciba estas actualizaciones y refleje el nuevo estado de la transacción en tu base de datos.
El próximo paso es agregar el SDK al frontend para renderizar el botón de pago e inicializar el checkout. Accede a Agregar el SDK al frontend e inicializar el checkout para continuar la integración.