Configure money transfers
The integration of Payouts is carried out by making a single call to the /v1/payouts API to configure single transactions (to a single destination account) or multiple (to several destination accounts). This means that the transaction is created and processed in a single request, and if the execution is successful, the money will be available to be withdrawn to the destination account, with no need for additional steps.
See below how to integrate Payouts to perform the transactions and also how to get information about them, schedule them and, if necessary, cancel them.
To configure transactions with destination to bank accounts or between Mercado Pago accounts, you must send a POST with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/payoutsAPI. You must send the corresponding parameters following the indications in the table below.
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-enforce-signature: false' \ --header 'X-test-token: true' \ --header 'X-signature: true' \ --data-raw '{ "external_reference": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T14:30:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago, that must be used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials.. | Required | - |
X-Idempotency-Key | Header. This function allows you to safely repeat requests without the risk of performing the same action more than once by mistake. This is useful to avoid errors, such as creating two identical transactions, for example. To ensure that each request is unique, it is important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. It is important to note that, as of 01/01/24, sending this parameter will become mandatory in all requests. | Required | 0d5020ed-1af6-469c-ae06-c3bec19954bb |
X-signature | Header. Request signature with the body encrypted in base64 using the integrator's public and private keys. It is required only in the production environment. | Required only in the production environment. | - |
X-enforce-signature | Header. Boolean to indicate whether the integrator will send the signature or not. Must be false for test environment or true for production environment, which is when sending the signature is mandatory. | Required only in the production environment. | false |
X-test-token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-enforce-signature to true and use X-signature to test validation of the encrypted body. | Required as true when it is a test. | true |
external_reference | Body. Reference used to identify the payout. It is generated by the integrator and can be any numeric value (1234) that allows tracking the transaction, as long as it does not exceed 7 characters and is not duplicated. You cannot use special characters (" ", [ ], ( ), @), letters (abcde), hyphens (-), or underscores (_). | Required | 000197 |
config | Body. Object containing user configurations for the transaction. | Optional | - |
config.notification_url | Body. URL where you will receive event notifications related to the transaction, such as status changes. | Optional | https://link-your-webhook-notification.com |
description | Body. Short description text of the complete payout operation, with all sent transfers. Limit of 100 characters counting the space between words. | Optional | "Payout for seller commissions" |
schedule_date | Body. Payout execution date. The value must be in the future and in standard ISO 8601 UTC-0 format ("YYYY-MM-DDTHH:MM:SS"), without timezone. The timezone is automatically inferred based on the country of the request. See more information in Schedule transactions | Optional | 2026-12-31T14:30:00 |
transactions.type | Body. Destination account type. The only possible value is account (bank accounts) | Required | account |
transactions.description | Body. Short description text of the operation. | Optional | "Payment to seller Beltrano" |
transactions.account | Body. Details of the destination account, which can be an e-mail for transfers between Mercado Pago accounts or details of a bank account (holder, account_number and bank_id) for transfers to external banks. | Required and fill according to the transfer model. | - |
transactions.account.email | Body. E-mail of the destination Mercado Pago account. | Required for transfers between Mercado Pago accounts. | test_user_mx@testuser.com |
transactions.amount | Body. Transaction value, which will be withdrawn from the account. | Required | - |
transactions.amount.currency | Body. Currency identifier used in the transaction. | Required | MXN |
transactions.amount.value | Body. Transaction value that will be debited from the origin checking account. The minimum value is 0 and the maximum is 10000000000. | Required | 100 |
transactions.external_reference | Body. Reference to identify the transaction. It is generated by the integrator to allow tracking of the cash-out and can be any numeric value (1234), as long as it does not exceed 7 characters. You cannot use special characters (" ", [ ], ( ), @), letters (abcde), hyphens (-), or underscores (_), and it must not be duplicated. | Required | 000156 |
If the execution is successful, you will receive as response a status code 202, indicating that the transaction was accepted, as in the example below.
json
{ "id": "POP01KM145R903TZ06BWK6204DGG1", "external_reference": "000197", "description": "Payout for seller commissions", "idempotency_key": "1773859430", "created_date": "2026-03-18T14:43:50-04:00", "status": "created", "schedule_date": "2026-12-31T14:30:00", "config": { "notification_url": "https://link-your-webhook-notification.com" } }
| Attribute | Description |
id | Unique transaction identifier, automatically generated. |
external_reference | External reference of the transaction, generated by the integrator when creating it. |
description | Description text of the complete payout operation, with all sent transfers. |
idempotency_key | Idempotency key to avoid duplicates. |
created_date | Transaction creation date. |
status | Current transaction status. |
schedule_date | Payout execution date. The value will be in the future and in standard ISO 8601 UTC-0 format ("YYYY-MM-DDTHH:MM:SS"). |
config.notification_url | URL where you will receive event notifications related to the transaction, such as status changes. |
pending, you must execute the call to get list of transactions or get information about a transaction to verify its update.You can get information about all transactions in a payout. This can be useful to confirm that these were created correctly, by checking their status or verifying the information received in your notifications.
To do so, send a GET with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/payouts/{id}/transactionsAPI, replacing id with the payout ID obtained in the response when creating the batch.
curl
curl --location 'https://api.mercadopago.com/v1/payouts/{{payout_id}}/transactions?limit=100&offset=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Field | Description | Required | Example |
payout_id | Path. String. Identifier of the payout whose transaction you want to query, returned in the response to its creation within the id field. | Required | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials.. | Required | - |
X-test-token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-enforce-signature to true and use X-signature to test validation of the encrypted body. | Required as true when it is a test. | true |
limit | Query. Maximum number of transactions to return in the list. Limit of 100 transactions. | Optional | 10 |
offset | Query. Number of transactions to skip in the list. | Optional | 0 |
If the data sent in the call is correct, you will receive a response like the following:
json
{ "paging": { "limit": 100, "offset": 0, "total": 1 }, "transactions": [ { "id": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "value": 1000 } } ] }
| paging.limit | Maximum number of transactions returned according to the value defined in the limit parameter of the request. |
| paging.offset | Number of transactions returned according to the value defined in the offset parameter of the request. |
| paging.total | Total number of transactions performed in the payout. |
| transactions.id | Unique transaction identifier, automatically generated. |
| transactions.created_date | Transaction creation date. |
| transactions.last_update_date | Date of update of the transaction status. |
| transactions.external_reference | External reference of the transaction, generated by the integrator when creating it. |
| transactions.status | Current transaction status. |
| transactions.status_detail | Detailed information about the transaction status. |
| transactions.type | Transaction type. The value will always be "TRANSACTION" for bank transfers via Payouts. |
| transactions.amount.currency | Currency identifier used in the transaction. |
| transactions.amount.value | Transaction value that will be debited from the origin checking account. The minimum value is 0 and the maximum is 10000000000. |
You will also be able to get information about a specific transaction within a payout. This can be useful to confirm that it was created correctly, by checking its status or verifying the information received in your notifications.
To do so, send a GET with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/payouts/{{payout_id}}/transactions/{{transaction_id}}API, replacing payout_id with the payout ID and transaction_id with the transaction ID obtained previously.
curl
curl --location 'https://api.mercadopago.com/v1/payouts/{{payout_id}}/transactions/{{transaction_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Field | Description | Required | Example |
payout_id | Path. String. Identifier of the payout whose transaction you want to query, returned in the response to its creation within the id field. | Required | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
transaction_id | Path. String. Identifier of the transaction you want to query, returned in the response to its creation within the id field. | Required | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials.. | Required | - |
X-test-token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-enforce-signature to true and use X-signature to test validation of the encrypted body. | Required as true when it is a test. | true |
If the data sent in the call is correct, you will receive a response like the following:
json
{ "id": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "value": 1000 } }
| id | Unique transaction identifier, automatically generated. |
| created_date | Transaction creation date. |
| last_update_date | Date of update of the transaction status. |
| external_reference | External reference of the transaction, generated by the integrator when creating it. |
| status | Current transaction status. |
| status_detail | Detailed information about the transaction status. |
| transactions.type | Transaction type. The value will always be "TRANSACTION" for bank transfers via Payouts. |
| amount.currency | Currency identifier used in the transaction. |
| amount.value | Transaction value that will be debited from the origin checking account. The minimum value is 0 and the maximum is 10000000000. |
You will also be able to schedule a transfer using the Scheduler feature, which automates the execution of scheduled payments, ensuring that each payment occurs exactly on the defined date and time, safely and without duplications, recording all steps to facilitate tracking and auditing.
To schedule a payment, send a POST with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/payoutsAPI including the schedule_date field in the body.
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-enforce-signature: false' \ --header 'X-test-token: true' \ --header 'X-signature: true' \ --data-raw '{ "external_reference": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T14:30:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials.. | Required | - |
X-Idempotency-Key | Header. This function allows you to safely repeat requests without the risk of performing the same action more than once by mistake. This is useful to avoid errors, such as creating two identical transactions, for example. To ensure that each request is unique, it is important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. It is important to note that, as of 01/01/24, sending this parameter will become mandatory in all requests. | Required | 0d5020ed-1af6-469c-ae06-c3bec19954bb |
X-enforce-signature | Header. Boolean to indicate whether the integrator will send the signature or not. Must be false for test environment or true for production environment, which is when sending the signature is mandatory. | Required only in the production environment. | false |
X-test-token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-enforce-signature to true and use X-signature to test validation of the encrypted body. | Required as true when it is a test. | true |
external_reference | Body. Reference used to identify the payout. It is generated by the integrator and can be any numeric value (1234) that allows tracking the transaction, as long as it does not exceed 7 characters and is not duplicated. You cannot use special characters (" ", [ ], ( ), @), letters (abcde), hyphens (-), or underscores (_). | Required | 000197 |
schedule_date | Body. Payout execution date. The value must be in the future and in standard ISO 8601 UTC-0 format ("YYYY-MM-DDTHH:MM:SS"), without timezone. The timezone is automatically inferred based on the country of the request. | Optional | 2026-12-31T14:30:00 |
config | Body. Object containing user configurations for the transaction. | Optional | - |
config.notification_url | Body. URL where you will receive event notifications related to the transaction, such as status changes. | Optional | https://link-your-webhook-notification.com |
transactions.type | Body. Destination account type. The only possible value is account (bank accounts) | Required | account |
transactions.description | Body. Short description text of the operation. | Optional | "Payment to seller Beltrano" |
transactions.account | Body. Details of the destination account, which can be an e-mail for transfers between Mercado Pago accounts or details of a bank account (holder, account_number and bank_id) for transfers to external banks. | Required and fill according to the transfer model. | - |
transactions.account.email | Body. E-mail of the destination Mercado Pago account. | Required for transfers between Mercado Pago accounts. | test_user_mx@testuser.com |
transactions.amount | Body. Transaction value, which will be withdrawn from the account. | Required | - |
transactions.amount.currency | Body. Currency identifier used in the transaction. | Required | MXN |
transactions.amount.value | Body. Transaction value that will be debited from the origin checking account. The minimum value is 0 and the maximum is 10000000000. | Required | 100 |
transactions.external_reference | Body. Reference to identify the transaction. It is generated by the integrator to allow tracking of the cash-out and can be any numeric value (1234), as long as it does not exceed 7 characters. You cannot use special characters (" ", [ ], ( ), @), letters (abcde), hyphens (-), or underscores (_), and it must not be duplicated. | Required | 000156 |
If the execution is successful, you will receive as response a status code 202, indicating that the transaction was accepted.
pending, you must execute the call to Get list of transactions or Get information about a transaction to verify its update.You will be able to cancel a scheduled transaction using the reference ID obtained in the response to its creation. Cancellation is intended to allow the interruption of incorrect or unwanted payment operations before financial completion, being irreversible to preserve operational integrity and ensure complete tracking for auditing.
pending and in_process) can be canceled. In addition, cancellation can only be done if there is a previous scheduling. That is, it is not possible to cancel transactions that have not been scheduled.To cancel a transaction, send a PUT with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/payouts/{{payout_id}}/transactions/{{transaction_id}}/cancelAPI, replacing payout_id with the payout ID and transaction_id with the transaction ID.
curl
curl --location --request PUT 'https://api.mercadopago.com/v1/payouts/{{payout_id}}/transactions/{{transaction_id}}/cancel' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true' \ --header 'X-enforce-signature: false' \ --data '{ "comments": "delete because the payment was canceled", "deleted_by": "user_123" }'
| Field | Description | Required | Example |
payout_id | Path. String. Identifier of the payout you want to query the transaction, returned in the response to its creation within the id field. | Required | POP01KKCFKH9J2C8TQSQZM4R3Z22C |
transaction_id | Path. String. Identifier of the transaction you want to query, returned in the response to its creation within the id field. | Required | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials.. | Required | - |
X-enforce-signature | Header. Boolean to indicate whether the integrator will send the signature or not. Must be false for test environment or true for production environment, which is when sending the signature is mandatory. | Required only in the production environment. | false |
X-test-token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-enforce-signature to true and use X-signature to test validation of the encrypted body. | Required as true when it is a test. | true |
comments | Body. String. Clear and objective justification for the cancellation (avoid including sensitive personal information). This field is fundamental for history and auditing. | Required | "delete because the payment was canceled" |
deleted_by | Body. String. Unique identification of who performed the cancellation (user, system, etc). This field is fundamental for history and auditing. | Required | user_123 |
If the execution is successful, you will receive as response a status code 204, indicating that the transaction was canceled.