Configure return URLs
Server-Side
Return URLs define where the buyer is redirected after completing the payment on the Mercado Pago checkout. Configure them in the config.online object of the order creation request to handle each transaction result independently in your system, whether the payment is approved, rejected, or pending.
Send a POST to the Create orderAPI endpoint with the success_url, failure_url, pending_url, and auto_return attributes within the config.online object, along with the other payment parameters. Each URL corresponds to a possible transaction outcome, all three being optional. Configure only the ones relevant to your business flow. For more details about the complete request, see Create and configure a payment order.
auto_return controls the automatic redirect after payment. Set "approved" to redirect only on approved payments or "all" for any outcome. In both cases, include success_url in the same request.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"
}
}
}'The table below describes each attribute in the config.online object used to configure the return URLs and the automatic redirect behavior.
| Attribute | Type | Description | Example | Required |
config.online.success_url | String | Return URL when the payment is approved. The buyer is automatically redirected here once the payment is completed. | "https://www.your-site.com/success" | Optional |
config.online.failure_url | String | Return URL when the payment is rejected or canceled. | "https://www.your-site.com/failure" | Optional |
config.online.pending_url | String | Return URL when the payment is pending. | "https://www.your-site.com/pending" | Optional |
config.online.auto_return | String | Controls the automatic redirect behavior after payment. Use "approved" to redirect the buyer to success_url only when the payment is approved. Use "all" to redirect the buyer on any payment outcome. | "approved" | Optional |
When the buyer completes the payment in the Mercado Pago environment, they are automatically redirected to the configured return URL. In that redirect, Mercado Pago appends parameters to the URL with information about the transaction. Your server receives them through a GET request and should use them to confirm the payment result and update the order status in your system.
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: en-US,en;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
The table below describes each parameter received on redirect.
| Parameter | Description |
collection_id | ID of the charge in Mercado Pago. Contains the same value as payment_id. |
collection_status | Status of the charge. Mirrors the value of the status field. |
payment_id | ID of the payment in Mercado Pago. |
status | Payment status. Returns approved for an approved payment, rejected for a rejected one, or pending for a pending payment. |
external_reference | Reference of the order in your system, defined at the time of creation. |
payment_type | Type of payment method used. For example, credit_card or ticket. |
order_id | ID of the order returned after its creation. |
merchant_order_id | Unique ID of the payment order created in Mercado Pago. |
preference_id | ID of the preference associated with the order, generated internally by the Orders API. |
site_id | Identifier of the seller's account country in Mercado Pago. For example, MLB for Brazil. |
processing_mode | Transaction processing mode. |
merchant_account_id | ID of the seller account in the marketplace context. Returns null when not applicable. |
Payments with pending status
Some payment methods require the buyer to complete the transaction outside of Checkout Pro. In these cases, Mercado Pago redirects the buyer to the URL configured in config.online.pending_url, with the payment awaiting confirmation.
Checkout Pro generates a voucher that the buyer presents at a physical establishment to complete the boleto bancário payment. With Pix, the payment awaits confirmation of the bank transfer.
Until confirmation arrives, the transaction remains open.
Once the payment is confirmed, Mercado Pago updates the order status and sends a notification to your server. Set up payment notifications so your server receives these updates and reflects the new transaction status in your database.
The next step is to add the SDK to the frontend to render the payment button and initialize the checkout. Go to Add the SDK to the frontend and initialize the checkout to continue the integration.