AI resources
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 transfers to one or multiple destination accounts, either by bank transfer or via Pix. This batch of transactions (payout) is created in a single request, and each transaction in the batch is processed independently.
Transfers can be made to checking and savings accounts. In addition, for transfers via Pix, the recipient must have a registered Pix key available to receive the transactions.
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 via bank transfer or Pix 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 corresponding parameters following the respective example cURLs and the instructions in the tables in the tabs below, according to the desired transaction type.
To run the batch on a future date, you can schedule the transactions using the
schedule_date field. For more information, see Schedule transactions.To create a batch of Pix transactions, provide each recipient's Pix key 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 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-enforce-signature: false' \ --header 'X-test-token: true' \ --header 'X-signature: true' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "MP0197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "transactions": [ { "description": "Payment to seller Beltrano", "type": "pix", "pix": { "type": "CPF", "chave": "111.444.777-35" }, "amount": { "currency": "BRL", "value": 10 }, "external_reference": "MP0197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. 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. To ensure that each request is unique, use a unique value in your request header. We suggest using a UUID V4 or random strings. | 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 or true for the production environment. | Required only in the production environment. | false |
X-test-token | Header. Boolean indicating whether the request will be a test (true) or not (false). | 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, letters, hyphens, and underscores are allowed. | Required | 000197 |
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. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payout for seller commissions |
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.type | Body. Transaction type. Use account for transfers between Mercado Pago accounts or to external accounts (whether checking or savings accounts), and pix for Pix transfers. | Required | pix |
transactions.pix | Body. Details of the recipient's Pix key. This key must be registered and available to receive transactions. | Required when transactions.type=pix. | - |
transactions.pix.type | Body. Pix key type. Possible values are EMAIL, PHONE, CPF, CNPJ, or PIX_CODE (random key, also known as EVP). | Required when transactions.type=pix. | CPF |
transactions.pix.chave | Body. Pix key value, in the format corresponding to the type defined in transactions.pix.type. | Required when transactions.type=pix. | 111.444.777-35 |
transactions.amount.currency | Body. Currency used in the transaction. | Required | BRL |
transactions.amount.value | Body. Transaction value to be debited from the source account. Minimum 1, maximum 10000000000. | Required | 10 |
transactions.external_reference | Body. Reference used to identify the transaction, generated by the integrator. Accepts up to 50 characters, using only letters, numbers, hyphens (-), and underscores (_). | Optional | MP0197 |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, consult possible errors for more information.
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": "BRL", "value": 11 }, "external_reference": "transaction_external_reference_01" }, { "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M", "amount": { "currency": "BRL", "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. |
The
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.Keep in mind that this response may take a few minutes and that, if its status is
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 get a complete list of all transactions in a batch or get information about a single transaction, see Get transaction list and Get transaction information, respectively.
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. |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, see possible errors for more information.
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 query a single transaction instead of the complete list, see Get transaction information.
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": "BRL", "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": "BRL", "value": 11 } } ] }
For more information about the returned statuses, see Transaction status.
| 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. |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, see possible errors for more information.
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 get information about a complete batch of transactions, see Get batch information.
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:
If the data sent in the request is correct, the response looks 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": "BRL", "value": 11 } }
For more information about the returned statuses, see Transaction status.
| 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. |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, see possible errors for more information.
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.
It is important that transactions are scheduled for a future date/time, outside of weekends or holidays and that, in addition to ensuring that there is available balance at the defined date/time, the transaction is aligned with the financial institution's operational windows.
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 Pix transfers, provide the payout execution date and time in schedule_date, along with each recipient's Pix key.
curlcurl --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 'X-signature: true' \ --header 'Content-Type: application/json' \ --data '{ "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": [ { "description": "Payment to seller Beltrano", "type": "pix", "pix": { "type": "CPF", "chave": "111.444.777-35" }, "amount": { "currency": "BRL", "value": 10 }, "external_reference": "MP0197" } ] }'
| Field | Description | Required | Example |
Authorization | Header. 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. To ensure that each request is unique, use a unique value in your request header. We suggest using a UUID V4 or random strings. | 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 or true for the production environment. | Required only in the production environment. | false |
X-test-token | Header. Boolean indicating whether the request will be a test (true) or not (false). | 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, letters, hyphens, and underscores are allowed. | Required | 000197 |
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. Use only letters, numbers, hyphens (-), underscores (_), and spaces; do not use punctuation. | Optional | Payout for seller commissions |
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.type | Body. Transaction type. Use account for transfers between Mercado Pago accounts or to external accounts (whether checking or savings accounts), and pix for Pix transfers. | Required | pix |
transactions.pix | Body. Details of the recipient's Pix key. This key must be registered and available to receive transactions. | Required when transactions.type=pix. | - |
transactions.pix.type | Body. Pix key type. Possible values are EMAIL, PHONE, CPF, CNPJ, or PIX_CODE (random key, also known as EVP). | Required when transactions.type=pix. | CPF |
transactions.pix.chave | Body. Pix key value, in the format corresponding to the type defined in transactions.pix.type. | Required when transactions.type=pix. | 111.444.777-35 |
transactions.amount.currency | Body. Currency used in the transaction. | Required | BRL |
transactions.amount.value | Body. Transaction value to be debited from the source account. Minimum 1, maximum 10000000000. | Required | 10 |
transactions.external_reference | Body. Reference used to identify the transaction, generated by the integrator. Accepts up to 50 characters, using only letters, numbers, hyphens (-), and underscores (_). | Optional | MP0197 |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, consult possible errors for more information.
If the execution is successful, the request returns a status code 202, indicating that the payout was accepted for processing.
The
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.Keep in mind that this response may take a few minutes and that, if its status is
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.
Only previously scheduled, unprocessed transactions with either
status=pending or status=in_process can be canceled.Submit the cancellation request at least 12 hours before the scheduled execution date and time.
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 |
To see in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. Also, if you receive an error when sending the request, consult our possible errors for more information.
If the execution is successful, you will receive as response a status code 204, indicating that the transaction was canceled.
Always review the current status of the transaction before trying to cancel it again. See Get transaction information to confirm that the cancellation was applied correctly.