Configure money transfers
The integration of Payouts is carried out by making a single call to the /v1/payouts API for multiple transactions 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 configure the integration of multiple transactions to several destination accounts.
To integrate Payouts with destination to bank accounts or between Mercado Pago accounts, you must send a POST with your Access Token in the header Authorization and your idempotency key in the header X-Idempotency-Key to the endpoint /v1/payouts. You must send the corresponding parameters following the indications in the table below.
- Transfers between Mercado Pago accounts:
The example below creates a payout in the Test environment, since the X-Test-Token Header has a value of true, meaning the X-signature sending is optional, so if you want to test its sending, just change X-Enforce-Signature to true.
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: false' \ --data-raw '{ "config": { "notification_url": "https://webhook.site/d774cfea-67b7-4423-9dab-87c839ab4a0e" }, "external_reference": "global_111", "schedule_date": "2026-11-13T15:00:00", "description": "description_root", "transactions": [ { "type": "account", "account": { "email": "test_user_2471579826595803489@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "description": "description_transaction", "external_reference": "test_mp-mp-webhook_schedule" } ] }'
- Transfers to other banks from Mercado Pago
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: false' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "global_111", "description": "description_root", "transactions": [ { "type": "account", "account": { "holder": "test user", "number": "0000003100025957669623", "bank_id": "015", "owner_value": "95871050", "owner_type": "DNI" }, "amount": { "currency": "ARS", "value": 123 }, "external_reference": "test_mp-bank-mla", "description": "description_transaction" } ] }'
| Field | Description | Required | Example |
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. | 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. | false |
external_reference | Body. Reference to identify the payout. It is generated by the integrator and can be any value that allows tracking the money withdrawal, as long as it does not have special characters ("", [ ], (), @) and does not exceed 7 characters. Numbers (1234), letters (abcde), hyphens (-) and underscores (_) are allowed, and it cannot be duplicated. | Required | MP0001 |
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" |
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 address associated with the Mercado Pago account. This field is required and exclusive for transfers between Mercado Pago accounts. When this field is used, it is not necessary to provide the fields holder, number, bank_id, owner_value and owner_type. There is a limit of up to 100 transactions with e-mail per payout. | Required when the transfer model is between Mercado Pago accounts. | test_user_ar@testuser.com |
transactions.account.holder | Body. First and last name of the holder of the destination account. Required for transfers to accounts outside Mercado Pago. | Required when the transfer model is from Mercado Pago accounts to outside. | María González |
transactions.account.account_number | Body. Unique number that represents each bank account. In this case, you must send the unique number of the destination account. | Required | 0000003100025957669623 |
transactions.account.bank_id | Body. Identification number of the bank to which the destination checking account belongs. The default value is 3 digits and always will be the first 3 numbers of the CLABE. | Required | 015 |
transactions.account.owner_value | Body. Identification number of the holder of the destination checking account. Required for transfers to accounts outside Mercado Pago. | Required | 95871050 |
transactions.account.owner_type | Body. Identification document type. | Required | DNI |
transactions.amount | Body. Transaction value, which will be withdrawn from the account. | Required | - |
transactions.amount.currency | Body. Currency identifier used in the transaction. | Required | ARS |
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 and can be any value that allows tracking the transaction, as long as it does not have special characters ("", [ ], (), @) and does not exceed 64 characters. Numbers (1234), letters (abcde), hyphens (-) and underscores (_) are allowed, and it cannot be duplicated. | Optional | tx_ext_ref_123 |
If the execution is successful, you will receive as response a status code 200, indicating that the transaction was accepted, as in the example below.
pending, you must execute the request to Get list of transactions or Get information about a transaction to verify its update.json
{ "id": "23917", "idempotency_key": "1764622137", "created_date": "2025-12-01T15:48:57.581+00:00", "status": "created", "schedule_date": "2026-11-13T15:00:00", "description": "description_root", "config": { "notification_url": "https://your-webhook-endpoint.com/notifications" } }
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/9290/transactions?limit=100&offset=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Test-Token: true'
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": "676739", "created_date": "2025-08-25T13:04:31.000+00:00", "last_update_date": "2025-08-25T13:04:33.000+00:00", "external_reference": "test_mp-mp-mla", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 1000 } } ] }
| Attribute | Description |
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. |
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. |
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 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/9290/transactions/676739' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Test-Token: true'
If the data sent in the call is correct, you will receive a response like the following:
json
{ "id": "676739", "created_date": "2025-08-25T13:04:31.000+00:00", "last_update_date": "2025-08-25T13:04:33.000+00:00", "external_reference": "test_mp-mp-mla", "status": "success", "status_detail": "accredited", "type": "mp-user", "amount": { "currency": "ARS", "value": 1000 } }
| Attribute | Description |
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. |
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 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: true' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "global_111", "config": { "notification_url": "https://your-webhook-endpoint.com/notifications" }, "schedule_date":"2025-11-28T00:00:00", "transactions": [ { "type": "account", "account": { "holder": "test user", "number": "0000003100025957669623", "bank_id": "015", "owner_value": "95871050", "owner_type": "DNI" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "test_mp-bank-mla" } ] }'
| Field | Description | Required | Example |
schedule_date | Body. Scheduled date for payout execution. The value must be in the future and in standard ISO 8601 format ("YYYY-MM-DDTHH:MM:SS" or "YYYY-MM-DDTHH:MM:SS.000±HH:MM" for specific timezones). | Optional | 2025-12-25T10:00:00 or 2026-12-31T09:37:52.000-04:00 |
status is pending, you must execute the request to 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/123456/transactions/67890/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 |
X-Enforce-Signature | Header. Boolean to indicate whether the integrator will send the signature or not. Must be false for test environment and true for production environment. | Required | false |
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-Test-Token | Header. Boolean to indicate whether the request will be a test or not. Always required as true when it is a test request. When the Access Token does not start with TEST, this header must be used so that the call is made in the test environment. When using this header, it is possible to use "X-Enforce-Signature" as true and use "X-signature" to test the validation of the encrypted body. | Required as true when it is a test request | 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 |
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 | 123456 |
transaction_id | Path. String. Identifier of the transaction you want to query, returned in the response to its creation within the id field. | Required | 67890 |
If the execution is successful, you will receive as response a status code 204, indicating that the transaction was canceled.