This endpoint allows you to create a batch ("payout") with one or multiple money-out transactions from a Mercado Pago account to one or multiple Mercado Pago accounts. The source account must have sufficient funds. A payout can contain up to 1000 transactions, which are created and submitted for processing in a single request. On success, the request returns status 202.
POST
REQUIRED
REQUIRED
CONDITIONALLY REQUIRED
body in base 64 with the public and private keys of the integrator. It is required only in a productive environment.CONDITIONALLY REQUIRED
boolean indicating whether the integrator will send the signature. It must be false for test environments, and true for production environments, when the signature is mandatory.REQUIRED
-), underscores (_), and spaces; do not use punctuation.YYYY-MM-DDTHH:MM:SS), without timezone. The timezone is automaticaobject containing payout settings, such as the URL that receives transaction status notifications.400Bad request. The parameters sent are not valid.
invalid_payout_id
Invalid data was sent in the request body. The payout was not found. Try sending the request again, validating all fields.
invalid_transaction_id
Invalid data was sent in the request body. The transaction was not found. Try sending the request again, validating all fields.
invalid_signature
Invalid data was sent in the request body. Check if the secret was generated correctly and is registered with Mercado Pago. Also check if the body you are sending is the one that was encrypted.
idempotency_key_required
Invalid data was sent in the request body. The idempotency key (idempotency_key) is missing. Try sending the request again, validating all fields.
invalid_account
The `account` object was sent without the email required to identify the destination Mercado Pago account. Provide the recipient account email in `email`.
401Error. Access Token not authorized.
invalid_token
The value sent as Access Token is incorrect. Please check and try again with the correct value.
403Forbidden. You don't have permissions to access this resource.
forbidden
No permission to access the resource.
404Error. Payout not found.
not_found
Payout not found. Please check if you provided the correct payout ID.
500Internal server error.
internal_server_error
An unexpected error occurred on the server. Try the request again.
502Bad gateway. Integration failure with an external service.
bad_gateway
An error occurred in the integration with an external service. Try the request again.
curl -X POST \
'https://api.mercadopago.com/v1/payouts'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-H 'X-Idempotency-Key: 20e73f88-e4ef-4a60-ad3b-fe882b79bc1d' \
-H 'X-signature: true' \
-H 'X-enforce-signature: false' \
-H 'X-test-token: false' \
-d '{
"external_reference": "MP0197",
"description": "Payout for seller commissions",
"schedule_date": "2026-12-31T10:00:00",
"config": {
"notification_url": "https://link-your-webhook-notification.com"
},
"transactions": [
{
"external_reference": "MP0197",
"type": "account",
"account": {
"email": "test@testuser.com"
},
"amount": {
"currency": "COP",
"value": 50
},
"description": "Payment to seller Beltrano"
}
]
}'{
"id": "POP01KKYN1QY2SS1MKAY4KP6SSRCT",
"external_reference": "MP0197",
"idempotency_key": "0d5020ed-1af6-469c-ae06-c3bec19954bb",
"created_date": "2024-01-15T10:30:00Z",
"status": "created",
"schedule_date": "2026-12-31T10:00:00",
"description": "Payout for seller commissions",
"config": {
"notification_url": "https://link-your-webhook-notification.com"
},
"transactions": [
{
"id": "TOP01KV681P6SJ38NQHWX3SF2WM22",
"amount": {
"currency": "COP",
"value": "50.0"
},
"external_reference": "MP0197"
}
]
}