Configure money transfers
The Payouts integration uses a single request to the /v1/payoutsPOST API to create a batch of transactions with one or multiple bank transfers to one or multiple destination accounts. This batch of transactions (payout) is created in a single request, and each transaction in the batch is processed independently.
See below how to integrate Payouts to create transactions, retrieve information about them, schedule them, and cancel them when necessary.
Create a batch (payout) with one or multiple outgoing money transactions from a Mercado Pago account to one or multiple recipients, whether they are other Mercado Pago accounts or external accounts. The payout can contain up to 1000 transactions, created and processed in a single request, provided that the source account has sufficient funds.
To do so, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. to the endpoint /v1/payoutsPOST. Send the parameters following the respective example cURLs and the fields indicated in the tables in the tabs below, according to the desired transaction type.
schedule_date field. For more information, see Schedule transactions.To create a batch of transactions between Mercado Pago accounts, provide the email address associated with each recipient's account and the details of the transfers that will be included in the payout.
curlcurl --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": "MP0197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "MP0197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend.. | Required | - |
X-Idempotency-Key | Header. This feature lets you safely repeat requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical transactions, for example. To ensure that each request is unique, use a unique value in your request header. We suggest using a UUID V4 or random strings. Note that, as of January 1, 2024, sending this parameter is 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 for a test. | true |
external_reference | Body. Reference used to identify the payout. It is generated by the integrator and can be any value that allows the transaction to be tracked, provided that it does not contain special characters ("", [ ], (), @), exceed 50 characters, or duplicate another reference. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed. | Required | MP0197 |
config | Body. Object containing settings for the user performing the transaction. | Optional | - |
config.notification_url | Body. URL where you will receive notifications about events related to the transaction, such as status changes. For more information, see Configure notifications. | Optional | https://link-your-webhook-notification.com |
description | Body. Short description of the complete payout operation, including all transfers sent. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payout for seller commissions |
transactions.type | Body. Transaction type. The only possible value is account (checking account). | Required | account |
transactions.description | Body. Short description of the individual transaction. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payment to seller Beltrano |
transactions.account | Body. Destination account details when transactions.type is account. For this transfer model, provide the e-mail address of the destination Mercado Pago account. | Required when transactions.type=account and must be completed according to the transfer model. | - |
transactions.account.email | Body. E-mail address of the destination Mercado Pago account. | Required when the transfer model is between Mercado Pago accounts. | test@testuser.com |
transactions.amount | Body. Transaction value. | Required | - |
transactions.amount.currency | Body. Currency identifier used in the transaction. | Required | ARS |
transactions.amount.value | Body. Transaction value to be debited from the source checking account. The minimum value is 1 and the maximum is 10000000000. | Required | 100 |
transactions.external_reference | Body. Reference used to identify the transaction. It is generated by the integrator and can be any value that allows the transaction to be tracked, provided that it does not contain special characters ("", [ ], (), @) and does not exceed 50 characters. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed, and the reference must not be duplicated. | Optional | MP0197 |
If the execution is successful, the request returns a status code 202, indicating that the payout was accepted for processing. The following example shows a payout containing two transactions:
json{ "id": "POP01KV681P6SJ38NQHWX3XK162SS", "external_reference": "payout_external_reference", "description": "description_root", "idempotency_key": "021957ca-7271-4f5e-8b8d-70ed87ce1a61", "created_date": "2026-06-15T14:17:36-03:00", "status": "created", "config": { "notification_url": "https://notification_url.com" }, "transactions": [ { "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "amount": { "currency": "ARS", "value": 11 }, "external_reference": "transaction_external_reference_01" }, { "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M", "amount": { "currency": "ARS", "value": 12 }, "external_reference": "transaction_external_reference_02" } ] }
| Attribute | Description |
id | Unique payout identifier, automatically generated. |
external_reference | External reference of the payout, 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 | Payout creation date. |
status | Current payout status. |
config.notification_url | URL where you will receive event notifications related to the payout and its transactions, such as status changes. |
transactions.id | Unique transaction identifier, automatically generated. |
transactions.amount.currency | Identifier of the currency used in the transaction. |
transactions.amount.value | Amount of the transaction. |
transactions.external_reference | External reference of the transaction, generated by the integrator at creation time. |
202 status code confirms that the payout was accepted for processing, but not that all transactions were validated. Validation of the format and length of transactions.external_reference is asynchronous: if the field is invalid, the transaction will be marked with an error during processing. Check the transaction status to identify the error.pending, you can use the requests described below to get more information about a batch or about a specific transaction.Query the status and consolidated summary of a transaction batch (payout). Use this endpoint to check how many transactions completed successfully, how many are pending, or how many resulted in an error.
To do so, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. to the endpoint /v1/payouts/{payout_id}GET, sending the payout ID (payout_id) obtained in the response when creating the batch.
curlcurl --location 'https://api.mercadopago.com/v1/payouts/{payout_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 you want to query, returned in the id field of the response when creating it. | Required | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend.. | 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 for a test. | true |
If the data sent in the call is correct, you will receive a response like the following:
json{ "id": "POP01KV681P6SJ38NQHWX3XK162SS", "status": "completed", "external_reference": "payout_external_reference", "config": { "notification_url": "https://notification_url.com" }, "summary": { "pending": { "items": 0 }, "canceled": { "items": 0 }, "success": { "items": 0 }, "error": { "items": 2 } } }
| Attribute | Description |
id | Unique payout identifier, automatically generated. |
status | Current payout status. |
external_reference | External reference of the payout, generated by the integrator at creation time. |
config.notification_url | URL where notifications of payout-related events will be received, such as status changes. For more information, see Configure notifications. |
summary.pending.items | Number of pending transactions. |
summary.canceled.items | Number of canceled transactions. |
summary.success.items | Number of successfully completed transactions. |
summary.error.items | Number of transactions with error. |
Get information about all transactions in a batch to confirm that they were created correctly by checking their status or verifying the information received in your notifications.
To do so, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. to the endpoint /v1/payouts/{payout_id}/transactionsGET, replacing payout_id with the payout ID obtained in the response when creating the batch.
curlcurl --location 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions?limit=10&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 transactions you want to query, returned in the id field of the response when creating it. | Required | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
limit | Query. Maximum number of transactions to return in the list. Limit of 100 transactions. | Optional | 10 |
offset | Query. Number of transactions to omit from the list. | Optional | 0 |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend.. | 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 for a test. | true |
If the data sent in the call is correct, you will receive a response like the following:
json{ "external_reference": "payout_external_reference", "config": { "notification_url": "https://notification_url.com" }, "paging": { "limit": 50, "offset": 0, "total": 2 }, "transactions": [ { "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_02", "description": "description_transaction_02", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 12 } }, { "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_01", "description": "description_transaction_01", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 11 } } ] }
| Attribute | Description |
external_reference | External reference of the payout, generated by the integrator at creation time. |
config.notification_url | URL where notifications of payout-related events will be received, such as status changes. For more information, see Configure notifications. |
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.amount.currency | Currency identifier used in the transaction. |
transactions.amount.value | Transaction amount. |
Get information about a specific transaction within a batch to confirm that it was created correctly by checking its status or verifying the information received in your notifications.
To do so, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. to the endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET, replacing payout_id with the payout ID and transaction_id with the transaction ID obtained previously.
curlcurl --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 that contains the transaction, returned in the id field of the response when creating it. | Required | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
transaction_id | Path. String. Identifier of the transaction you want to query, returned in the transactions[].id field of the payout creation response. | Required | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend.. | 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 for a test. | true |
If the data sent in the call is correct, you will receive a response like the following:
json{ "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_01", "description": "description_transaction_01", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 11 } }
| 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 | Amount of the transaction. |
Schedule transfers using Scheduler, a feature that automates the execution of scheduled transactions, ensuring that each transfer occurs exactly on the defined date and time, securely, without duplication, and recording every step to facilitate tracking and auditing.
To schedule transfers, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. to the endpoint /v1/payoutsPOST, including the schedule_date field in the body. Also, you'll have to send specific mandatory fields depending on the desired transaction type, which you can check in the tables below.
To schedule transfers between Mercado Pago accounts, provide the payout execution date and time in schedule_date, along with the email address associated with each recipient's account.
curlcurl --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": "MP0197", "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@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "MP0197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend.. | Required | - |
X-Idempotency-Key | Header. This feature lets you safely repeat requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical transactions, for example. To ensure that each request is unique, use a unique value in your request header. We suggest using a UUID V4 or random strings. Note that, as of January 1, 2024, sending this parameter is 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 for a test. | true |
external_reference | Body. Reference used to identify the payout. It is generated by the integrator and can be any value that allows the transaction to be tracked, provided that it does not contain special characters ("", [ ], (), @), exceed 50 characters, or duplicate another reference. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed. | Required | MP0197 |
config | Body. Object containing settings for the user performing the transaction. | Optional | - |
config.notification_url | Body. URL where you will receive notifications about events related to the transaction, such as status changes. For more information, see Configure notifications. | Optional | https://link-your-webhook-notification.com |
schedule_date | Body. Payout execution date. The value must be in the future and in the standard ISO 8601 UTC-0 format ("YYYY-MM-DDTHH:MM:SS"), without a time zone. The time zone is automatically inferred based on the country of the request. See more information in Schedule transactions. | Optional | 2026-12-31T14:30:00 |
description | Body. Short description of the complete payout operation, including all transfers sent. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payout for seller commissions |
transactions.type | Body. Transaction type. The only possible value is account (checking account). | Required | account |
transactions.description | Body. Short description of the individual transaction. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payment to seller Beltrano |
transactions.account | Body. Destination account details when transactions.type is account. For this transfer model, provide the e-mail address of the destination Mercado Pago account. | Required when transactions.type=account and must be completed according to the transfer model. | - |
transactions.account.email | Body. E-mail address of the destination Mercado Pago account. | Required when the transfer model is between Mercado Pago accounts. | test@testuser.com |
transactions.amount | Body. Transaction value. | Required | - |
transactions.amount.currency | Body. Currency identifier used in the transaction. | Required | ARS |
transactions.amount.value | Body. Transaction value to be debited from the source checking account. The minimum value is 1 and the maximum is 10000000000. | Required | 100 |
transactions.external_reference | Body. Reference used to identify the transaction. It is generated by the integrator and can be any value that allows the transaction to be tracked, provided that it does not contain special characters ("", [ ], (), @) and does not exceed 50 characters. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed, and the reference must not be duplicated. | Optional | MP0197 |
If the execution is successful, the request returns a status code 202, indicating that the payout was accepted for processing.
202 status code confirms that the payout was accepted for processing, but not that all transactions were validated. Validation of the format and length of transactions.external_reference is asynchronous: if the field is invalid, the transaction will be marked with an error during processing. Check the transaction status to identify the error.pending, you can use the requests described above to get more information about a batch or about a specific transaction.Cancel a scheduled transaction to interrupt an incorrect or unwanted transfer operation before financial settlement. This procedure is irreversible and preserves operational integrity and traceability for auditing.
status=pending or status=in_process can be canceled.To cancel a transaction, send a request 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}/cancelPUT, using the payout ID (payout_id) and the transaction ID (transaction_id).
curlcurl --location --request PUT 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions/{transaction_id}/cancel' \ --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 '{ "comments": "delete because the payment was canceled", "deleted_by": "user_123" }'
| Field | Description | Required | Example |
payout_id | Path. String. Identifier of the payout that contains the transaction you want to cancel, returned in the id field of its creation response. | Required | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
transaction_id | Path. String. Identifier of the transaction you want to cancel, returned in the transactions[].id field of the payout creation response. | 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-Idempotency-Key | Header. This feature lets you safely repeat requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical transactions, for example. To ensure that each request is unique, use a unique value in your request header. We suggest using a UUID V4 or random strings. Note that, as of January 1, 2024, sending this parameter is 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 indicating whether the integrator will send the signature. It must be false for the test environment and true for the production environment. | 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 for a test. | true |
comments | Body. String. Clear and objective reason for the cancellation (avoid including sensitive personal information). This field supports history and auditing. | Optional | delete because the payment was canceled |
deleted_by | Body. String. Unique identification of who performed the cancellation (user, system, etc.). This field supports history and auditing. | Optional | user_123 |
If the execution is successful, you will receive as response a status code 204, indicating that the transaction was canceled.