Configurar transferencias de dinero
La integración de Payouts se realiza mediante la ejecución de una única llamada a la API /v1/payouts para múltiples transacciones a varias cuentas de destino. Esto significa que la transacción se crea y procesa en una sola solicitud y, si la ejecución es exitosa, el dinero estará disponible para ser retirado en la cuenta de destino, sin necesidad de realizar pasos adicionales.
Ve a continuación cómo configurar la integración de múltiples transacciones para varias cuentas de destino.
Para integrar Payouts con destino a cuentas bancarias o entre cuentas Mercado Pago, debes enviar un POST con tu Access Token en el header Authorization y tu clave de idempotencia en el header X-Idempotency-Key al endpoint /v1/payouts. Debes enviar los parámetros correspondientes siguiendo las indicaciones de la tabla a continuación.
- Transferencias entre cuentas Mercado Pago:
El ejemplo abajo crea un payout en el entorno de Test, ya que el Header de X-Test-Token tiene el valor de true, o sea, el envío del X-signature es opcional, así que si quiere probar su envío basta cambiar el X-Enforce-Signature para 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" } ] }'
- Transferencias para otros bancos a partir del 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" } ] }'
| Campo | Descripción | Requerido | Ejemplo |
X-Idempotency-Key | Header. Esta función permite repetir solicitudes de forma segura, sin el riesgo de realizar la misma acción más de una vez por engano. Esto es útil para evitar errores, como la creación de dos transacciones idénticas, por ejemplo. Para garantizar que cada solicitud sea única, es importante usar un valor exclusivo en el header de su solicitud. Sugerimos el uso de un UUID V4 o strings aleatorias. Es importante resaltar que, a partir de 01/01/24, el envío de este parámetro pasará a ser obligatorio en todas las solicitudes. | Requerido | 0d5020ed-1af6-469c-ae06-c3bec19954bb |
X-signature | Header. Firma de la solicitud con el body cifrado en base 64 con las claves pública y privada del integrador. | Requerido solo en el ambiente de producción. | - |
X-Enforce-Signature | Header. Booleano para indicar si el integrador enviará o no la firma. Debe ser false para ambiente de prueba o true para ambiente productivo, que es cuando es obligatorio el envío de la firma. | Requerido solo en el ambiente de producción. | false |
X-Test-Token | Header. Booleano para indicar si la solicitud será de prueba (true) o no (false). Debes usarlo para que la solicitud se realice en el entorno de prueba. Al usar este header, puedes configurar X-Enforce-Signature como true y usar X-Signature para probar la validación del body cifrado. | Obligatorio como true cuando se trate de una prueba. | false |
external_reference | Body. Referencia para identificar el payout. Es generada por el integrador y puede ser cualquier valor que permita el rastreo de la salida de dinero, desde que no posea caracteres especiales ("", [ ], (), @) y no exceda 7 caracteres. Son permitidos números (1234), letras (abcde), guiones (-) y guiones bajos (_), y no puede ser duplicada. | Requerido | MP0001 |
description | Body. Texto corto de descripción de la operación del payout completo, con todas las transferencias enviadas. Límite de 100 caracteres contabilizando el espacio entre las palabras. | Opcional | "Payout for seller commissions" |
transactions.type | Body. Tipo de cuenta de destino. El único valor posible es account (cuentas bancarias). | Requerido | account |
transactions.description | Body. Texto corto de descripción de la operación. | Opcional | "Payment to seller Beltrano" |
transactions.account | Body. Detalles de la cuenta de destino, que puede ser un e-mail para transferencias entre cuentas Mercado Pago o detalles de una cuenta bancaria (titular, account_number y bank_id) para transferencias a bancos externos. | Requerido y llenar de acuerdo con el modelo de transferencia. | - |
transactions.account.email | Body. Dirección de e-mail asociada a la cuenta Mercado Pago. Este campo es obligatorio y exclusivo para transferencias entre cuentas Mercado Pago. Cuando este campo es utilizado, no es necesario proporcionar los campos holder, number, bank_id, owner_value y owner_type. Hay un límite de hasta 100 transacciones con e-mail por payout. | Requerido cuando el modelo de transferencia es entre cuentas Mercado Pago. | test_user_ar@testuser.com |
transactions.account.holder | Body. Nombre y apellido del titular de la cuenta de destino. Requerido para transferencias para cuentas fuera del Mercado Pago. | Requerido cuando el modelo de transferencia es entre cuentas Mercado Pago para fuera. | María González |
transactions.account.account_number | Body. Número único que representa cada cuenta bancaria. En este caso, debes enviar el número único de la cuenta de destino. | Requerido | 0000003100025957669623 |
transactions.account.bank_id | Body. Número identificador del banco al que pertenece la cuenta corriente de destino. El valor por defecto es de 3 dígitos. | Requerido | 015 |
transactions.account.owner_value | Body. Número de identificación del titular de la cuenta corriente de destino. Requerido para transferencias para cuentas fuera del Mercado Pago. | Requerido | 95871050 |
transactions.account.owner_type | Body. Tipo de documento de identificación. | Requerido | DNI |
transactions.amount | Body. Valor de la transacción, que será retirado de la cuenta. | Requerido | - |
transactions.amount.currency | Body. Identificador de la moneda utilizada en la transacción. | Requerido | ARS |
transactions.amount.value | Body. Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 0 y el máximo es 10000000000. | Requerido | 100 |
transactions.external_reference | Body. Referencia para identificar la transacción. Es generada por el integrador y puede ser cualquier valor que permita el rastreo de la transacción, desde que no posea caracteres especiales ("", [ ], (), @) y no exceda 64 caracteres. Son permitidos números (1234), letras (abcde), guiones (-) y guiones bajos (_), y no puede ser duplicada. | Opcional | tx_ext_ref_123 |
Si la ejecución fue exitosa, recibirás como respuesta un status code 200, indicando que la transacción fue aceptada, como en el ejemplo a continuación.
pending, debes ejecutar la llamada para Obtener lista de transacciónes o Obtener información sobre una transacción para verificar su actualización.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" } }
Puedes obtener información sobre todas las transacciones de un payout. Esto puede ser útil para confirmar que estas fueron creadas correctamente, consultando su status o verificando la información recibida en tus notificaciones.
Para hacerlo, envía un GET con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{id}/transactionsAPI, reemplazando id por el ID del payout obtenido en la respuesta al crear el lote.
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'
Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:
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 } } ] }
| Atributo | Descripción |
paging.limit | Número máximo de transacciones retornadas de acuerdo con el valor definido en el parámetro limit de la solicitud. |
paging.offset | Número de transacciones retornadas de acuerdo con el valor definido en el parámetro offset de la solicitud. |
paging.total | Número total de transacciones realizadas en el payout. |
id | Identificador único de la transacción, generado automáticamente. |
created_date | Fecha de creación de la transacción. |
last_update_date | Fecha de actualización del status de la transacción. |
external_reference | Referencia externa de la transacción, generada por el integrador en la hora de la creación. |
status | Status actual de la transacción. |
status_detail | Información detallada del status de la transacción. |
amount.currency | Identificador de la moneda utilizada en la transacción. |
amount.value | Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 0 y el máximo es 10000000000. |
También podrás obtener información sobre una transacción específica dentro de un payout. Esto puede ser útil para confirmar que esta fue creada correctamente, consultando su status o verificando la información recibida en tus notificaciones.
Para hacerlo, envía un GET con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}API, reemplazando payout_id por el ID del payout y transaction_id por el ID de la transacción obtenidos previamente.
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'
Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:
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 } }
| Atributo | Descripción |
id | Identificador único de la transacción, generado automáticamente. |
created_date | Fecha de creación de la transacción. |
last_update_date | Fecha de actualización del status de la transacción. |
external_reference | Referencia externa de la transacción, generada por el integrador en la hora de la creación. |
status | Status actual de la transacción. |
status_detail | Información detallada del status de la transacción. |
amount.currency | Identificador de la moneda utilizada en la transacción. |
amount.value | Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 0 y el máximo es 10000000000. |
También podrás programar una transferencia utilizando el recurso de Scheduler, en que se automatiza la ejecución de las transferencias programadas, garantizando que cada transferencia ocurra exactamente en la fecha y hora definidas, de forma segura y sin duplicaciones, registrando todos los pasos para facilitar el acompañamiento y la auditoría.
Para programar una transferencia, envía un POST con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payoutsAPI incluyendo el campo schedule_date en el 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": "0003", "owner_value": "95871050", "owner_type": "DNI" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "test_mp-bank-mla" } ] }'
| Campo | Descripción | Requerido | Ejemplo |
schedule_date | Body. Fecha agendada para ejecución del payout. El valor debe estar en el futuro y en el formato estándar ISO 8601 ("YYYY-MM-DDTHH:MM:SS o "YYYY-MM-DDTHH:MM:SS.000±HH:MM" para timezones específicos). | Opcional | 2025-12-25T10:00:00 o 2026-12-31T09:37:52.000-04:00 |
status es pending, debes ejecutar la solicitud para Obtener información sobre una transacción para verificar su actualización.Podrás cancelar una transacción agendada utilizando el ID de referencia obtenido en la respuesta a su creación. El cancelamiento está destinado a permitir la interrupción de operaciones de transferencias incorrectas o no deseadas antes de la conclusión financiera, siendo irreversible visando preservar la integridad operacional y garantizar el rastreo completo para auditoría.
pending e in_process) pueden ser canceladas. Además, el cancelamiento solo puede ser hecho si hay un agendamiento previo. Es decir, no es posible cancelar transacciones que no hayan sido agendadas.Para cancelar una transacción, envía un PUT con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}/cancelAPI, reemplazando payout_id por el ID del payout y transaction_id por el ID de la transacción.
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" }'
| Campo | Descripción | Requerido | Ejemplo |
X-Enforce-Signature | Header. Booleano para indicar si el integrador enviará o no la firma. Debe ser false para ambiente de prueba y true para ambiente productivo. | Requerido | false |
X-signature | Header. Firma de la solicitud con el body cifrado en base 64 con las claves pública y privada del integrador. Es obligatorio solo en el ambiente de producción. | Requerido solo en el ambiente de producción | - |
X-Test-Token | Header. Booleano para indicar si la solicitud será de prueba o no. Siempre obligatorio como true cuando se trata de una solicitud de prueba. Cuando el Access Token no comienza con TEST, este header debe ser usado para que la llamada sea hecha en el ambiente de prueba. Al utilizar este header, es posible usar el "X-Enforce-Signature" como true y usar el "X-signature" para probar la validación del body cifrado. | Requerido como true cuando se trata de una solicitud de prueba | true |
comments | Body. String. Justificación clara y objetiva para el cancelamiento (evitar incluir información personal sensible). Este campo es fundamental para histórico y auditoría. | Requerido | "delete because the payment was canceled" |
deleted_by | Body. String. Identificación única de quien realizó el cancelamiento (usuario, sistema, etc). Este campo es fundamental para histórico y auditoría. | Requerido | user_123 |
payout_id | Path. String. Identificador del payout que deseas consultar la transacción, retornado en la respuesta a su creación dentro del campo id. | Requerido | 123456 |
transaction_id | Path. String. Identificador de la transacción que deseas consultar, retornado en la respuesta a su creación dentro del campo id. | Requerido | 67890 |
Si la ejecución fue exitosa, recibirás como respuesta un status code 204, indicando que la transacción fue cancelada.