Process payments (via Advanced Payments API)
With the Advanced Payments API, payments are processed using the payer_token obtained in the agreement, debiting the amount directly from the buyer's wallet. Before processing payments, you must have completed the agreement flow and obtained the payer_token. If you have not done so yet, see the Configure agreements section.
To process a payment, send a request to the endpoint /v1/advanced_paymentsPOST, including your test Access TokenPrivate key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the buyer's payment token.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/advanced_payments' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "wallet_payment": { "transaction_amount": 550, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payer": { "token": "PAYER_TOKEN", "type_token": "wallet-tokens" }, "capture": true }'
See the table below for descriptions of the parameters that are mandatory in the request and those that, although optional, have some important particularity that should be highlighted.
| Parameter | Type | Description | Requirement |
X-Idempotency-Key | Header | Idempotency key. This key ensures that each request is processed only once, avoiding the creation of two identical payments. Use a unique value in the request header, such as a UUID V4 or a random string. | Required |
Authorization | Header | Refers to your test Access TokenPrivate key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`.. | Required |
X-Meli-Session-Id | Header | Identifier of the buyer's device at the time of purchase, used to improve security and increase the payment approval rate. | Optional |
wallet_payment.transaction_amount | Body. Number | Payment amount. | Required |
wallet_payment.description | Body. String | Brief description of the payment. | Optional |
wallet_payment.external_reference | Body. String | Custom seller reference, used to correlate a Mercado Pago payment with an internal order. | Optional |
wallet_payment.statement_descriptor | Body. String | Text that appears on the buyer's statement along with the amount and date of the charge. Accepts a maximum of 50 alphanumeric characters. | Optional |
payer.token | Body. String | Payment token (payer_token) obtained in the agreement flow, used to charge the buyer's wallet. | Required |
payer.type_token | Body. String | Type of the token. For Wallet Connect payments, the value must be wallet-tokens. | Required |
capture | Body. Boolean | Indicates whether the payment should be captured immediately. In two-step payments, send false to reserve the amount and capture it later by sending true in a separate request. | Optional |
binary_mode | Body. Boolean | When enabled, the payment can only be approved or rejected. Otherwise, the payment may remain pending. | Optional |
If the request is successful, the response will return status 201 with the created payment.
json{ "id": 10267812, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ], "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" } }
Among the returned parameters, we have those indicated in the table below.
| Parameter | Type | Description |
id | Number | Unique identifier of the created payment. Use it to query, capture or refund the payment. |
payments.status | String | Returns the payment status. The possible values are approved, in_process and rejected. |
payments.status_detail | String | Details the reason for the payment status. For approved payments, it returns accredited. |
payments.transaction_amount | Number | Amount charged to the buyer. |
payments array may be rejected depending on the state of the buyer's account, even when the request returns 201. Always check the status of each payment before confirming the purchase to the buyer.The query allows you to obtain the updated data of a payment made through the Advanced Payments API, including its status.
To perform the query, send a request to the endpoint /v1/advanced_payments/{advanced_payment_id}GET, including your test Access TokenPrivate key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the advanced_payment_id obtained in the response to its creation.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/advanced_payments/{{ADVANCED_PAYMENT_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Parameter | Type | Description | Requirement |
advanced_payment_id | Path. Number | Unique identifier of the payment you want to query, obtained in the response to its creation. | Required |
Authorization | Header | Refers to your test Access TokenPrivate key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`.. | Required |
If the request is successful, the response will return status 200 with the updated payment data.
json{ "id": 10267812, "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ] }