Configure return URLs
The return URL is the address to which the buyer is redirected after completing the payment, whether successful, failed, or pending. This URL should be a webpage that you control, such as a server with a named domain (DNS).
With the Orders API, return URLs are configured directly in the Order creation request body, within the checkout_pro object. You can configure up to three different return URLs, corresponding to success, failure, or pending payment scenarios, as well as the automatic redirection behavior.
Define return URLs
To configure return URLs, include the back_urls and auto_return attributes within the checkout_pro object when creating the Order through a POST request to the /v1/orders endpoint.
Below, we share an example of how to include return URLs in the Order creation.
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.your-site.com/success", "failure": "https://www.your-site.com/failure", "pending": "https://www.your-site.com/pending" }, "auto_return": "approved" } }'
| Attribute | Description |
auto_return | Buyers are automatically redirected to the site when the payment is approved. The default value is approved. The redirection time will be up to 40 seconds and cannot be customized. By default, a "Return to site" button will also be displayed. |
back_urls | Return URL to the site. The possible scenarios are: success: Return URL when the payment is approved.pending: Return URL when the payment is pending.failure: Return URL when the payment is rejected. |
Return URLs response
The back_urls will return some useful parameters through a GET request. Below, we share an example of what a response will look like and the details of the parameters you may find in it.
curl
GET /success?payment_id=123456789&status=approved&external_reference=order_pro_123&order_id=987654321 HTTP/1.1 Host: www.your-site.com
| Parameter | Description |
payment_id | ID (identifier) of the Mercado Pago payment. |
status | Payment status. For example: approved for an approved payment or pending for a pending payment. |
external_reference | Reference that you can synchronize with your payment system. |
order_id | ID (identifier) of the Order generated in Mercado Pago. |
Response for offline payment methods
Offline payment methods are those where the buyer chooses a method that requires them to use a physical payment point to complete the purchase process. In this payment flow, Mercado Pago will generate a voucher that the buyer needs to make the payment at the corresponding establishment, and will redirect the buyer to the URL you specified in the back_urls attribute as pending.
At this point, the payment is in a pending state because the buyer still needs to go to a physical establishment and pay.
To provide more information to the buyer, we recommend that for pending payment statuses, you redirect the buyer to your website and share clear information on how to complete the payment.
Once the buyer goes to the corresponding establishment and makes the cash payment with the generated voucher, Mercado Pago is notified and the payment status will change. We recommend that you configure payment notifications so that your server can process this notification and update the order status in your database.