Configure agreements
An agreement is the authorization granted by the buyer that allows the seller to debit payments directly from their Mercado Pago wallet, without requiring a login for each transaction. It is the first step of the Wallet Connect integration and is mandatory before processing any payment.
The flow consists of three stages: creating the agreement, obtaining the buyer's approval, and generating the payment token. Once completed, you will have the payer_token, a credential that authorizes the charges described in the Process payments section.
Creating the agreement generates the authorization link that must be presented to the buyer so they can grant the seller access to their Mercado Pago wallet. Two flows are available: Standard, in which the buyer completes the authorization in the browser, and Sniffing, which attempts to open the authorization directly in the Mercado Pago app on mobile devices. Compare the options below and choose the one that best suits your integration.
In the standard flow, the buyer authorizes access to their Mercado Pago wallet in the browser and may need to log in manually.
To create an agreement without redirecting the buyer to the Mercado Pago app, send a POST to the endpoint /v2/wallet_connect/agreementsAPI, including your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the parameters indicated below.
curlcurl -X POST \ 'https://api.mercadopago.com/v2/wallet_connect/agreements' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "return_uri": "https://www.mercadopago.com/", "external_flow_id": "{{EXTERNAL_FLOW_ID}}", "external_user": { "id": "usertest", "description": "Test account" }, "agreement_data": { "validation_amount": 3.14, "description": "Test agreement" } }'
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 |
Authorization | Header | Refers to your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`.. | Required |
return_uri | Body. String | URI to which the buyer will be redirected upon completing the agreement flow. This is the address where you will receive the authorization result as query parameters. The maximum limit is 2048 characters and the value sent must match a URI previously registered for the application. | Required |
external_flow_id | Body. String | Seller's internal identifier for the current flow state. Use it to correlate the agreement result with the purchase session in your system. The maximum limit is 64 characters. | Required |
external_user.id | Body. String | Seller's unique identifier for the buyer. The maximum limit is 256 characters and the value must not contain sensitive data. | Required |
external_user.description | Body. String | Label for the buyer in the seller's system, such as their name. The maximum limit is 256 characters. | Optional |
agreement_data.validation_amount | Body. Number | Reference amount for the agreement. If the buyer's account balance is insufficient to cover this amount, a card will be required as a secondary payment method during the authorization. We recommend sending a value close to the average ticket of your charges. | Optional |
agreement_data.description | Body. String | Description of the actions the buyer is about to authorize, displayed during the approval flow. The maximum limit is 256 characters. | Optional |
If the request is successful, the response will return status 201 with the identifier of the created agreement and the authorization URI to be presented to the buyer.
json{ "agreement_id": "22abcd1235ed497f945f755fcaba3c6c", "agreement_uri": "{{wc_agreement_uri_example}}" }
Among the returned parameters, we have those indicated in the table below.
| Parameter | Type | Description |
agreement_id | String | Unique identifier of the created agreement. Store it, as it is required to generate the payment token and to query or cancel the agreement. |
agreement_uri | String | URI to which the buyer must be redirected in order to authorize access to their wallet. See the Obtain buyer approval stage to learn how to use it. |
After creating the agreement, redirect the buyer to the agreement_uri returned in the response. At that URL, the buyer grants authorization for the seller to use their Mercado Pago wallet as a payment method.
When the flow ends, Mercado Pago redirects the buyer to the return_uri provided at creation, adding the operation result as query parameters.
- If the authorization is granted, the
return_uriwill be called in the format below.
plain`{return_uri}?agreement_id={agreement_id}&code={code}&flow=agreement&external_flow_id={external_flow_id}&code_type=validation_code`
- If the buyer rejects or cancels the authorization, the
return_uriwill be called in the format below, without thecodeparameter and with theerrorparameter.
plain`{return_uri}?agreement_id={agreement_id}&flow=agreement&external_flow_id={external_flow_id}&error={error}`
See the table below for descriptions of the returned parameters.
| Parameter | Type | Description |
agreement_id | String | Unique identifier of the authorized agreement. |
code | String | Authorization code used to generate the payment token. It is a 32-character lowercase alphanumeric code with a limited validity window. |
flow | String | Identifies the flow that originated the redirect. Always returns the fixed value agreement. |
external_flow_id | String | Seller's internal identifier, returned as sent when creating the agreement. |
code_type | String | Indicates the type of code returned. Always returns the fixed value validation_code. |
error | String | Reason why the agreement was not completed. Returns the fixed value access_denied, which indicates that the buyer rejected or cancelled the authorization. |
The payment token (payer_token) is the credential that represents the buyer's authorization and allows the seller to execute charges from their wallet. This is the last stage of the agreement flow.
The code parameter required to generate it can be obtained in two ways: as a query parameter in the return_uri (recommended) or from the agreement confirmation webhook.
To generate the token, send a POST to the endpoint /v2/wallet_connect/agreements/{agreement_id}/payer_tokenAPI, including your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`., the agreement_id obtained at its creation, and the authorization code.
curlcurl -X POST \ 'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}/payer_token' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "code": "{{AUTHORIZATION_CODE}}" }'
See the table below for descriptions of the parameters that must be sent in this request.
| Parameter | Type | Description | Requirement |
Authorization | Header | Refers to your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`.. | Required |
agreement_id | Path. String | Unique identifier of the agreement, obtained in the response to its creation. | Required |
code | Body. String | Authorization code generated during the agreement flow. It must be a 32-character lowercase alphanumeric string and can be used only once, within its validity window. | Required |
If the request is successful, the response will return status 201 with the payment token associated with the agreement.
json{ "payer_token": "abcdef1e23f4567d8e9123eb6591ff68df74c57930551ed980239f4538a7e530" }
| Parameter | Type | Description |
payer_token | String | Token that represents the buyer's authorization for the seller to process payments from their wallet. It must be sent in the transactions.payments.payment_method.token field for each charge. |
payer_token securely, as it will be used for all payments from this buyer while the agreement remains active. The same code cannot be reused to generate a new token: if the agreement is cancelled, the entire authorization flow must be repeated.Cancelling revokes the authorization granted by the buyer and invalidates the associated payer_token, preventing new charges from their wallet.
To cancel an agreement, send a DELETE to the endpoint /v2/wallet_connect/agreements/{agreement_id}API without sending the body in the request. Make sure to include your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the agreement_id of the agreement you want to cancel.
curlcurl -X DELETE \ 'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Parameter | Type | Description | Requirement |
Authorization | Header | Refers to your test Access TokenPrivate key used in the backend to authenticate the requests. In Wallet Connect, the Access Token and the Public Key are provided by the team responsible for creating your application, both test and production. You can also view them in Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`.. | Required |
agreement_id | Path. String | Unique identifier of the agreement you want to cancel. | Required |
If the request is successful, the response will return status 200 with no response body, indicating that the agreement was cancelled and that the associated payer_token is no longer valid.