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 configurar transacciones únicas (para una sola cuenta de destino) o múltiples (para 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 integrar Payouts para realizar las transacciones y también cómo obtener información sobre ellas, programarlas y, si es necesario, cancelarlas.
Para configurar transacciones con destino a cuentas bancarias o entre cuentas Mercado Pago, debes enviar 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 /developers/pt/reference/online-payments/payouts/multiple-transactions/create-bank-transaction/postAPI. Debes enviar los parámetros correspondientes siguiendo las indicaciones de la tabla a continuación.
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: true' \ --header 'X-signature: true' \ --data-raw '{ "external_reference": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T10:00:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Campo | Descripción | Requerido | Ejemplo |
Authorization | Header. Hace referencia a tu clave privada, el Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Pruebas > Credenciales de prueba.. | Requerido | - |
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 salientar 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. Es obligatorio solo en el ambiente de producción. | 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. | true |
external_reference | Body. Referencia para identificar el payout. La genera el integrador y puede ser cualquier valor numérico (1234) que permita el rastreo de la transacción, siempre que no exceda 7 caracteres y no esté duplicada. No puedes usar caracteres especiales (" ", [ ], ( ), @), letras (abcde), guiones (-) ni guiones bajos (_). | Obligatorio | 000197 |
config | Body. Objeto que contiene configuraciones del usuario que realiza la transacción. | Opcional | - |
config.notification_url | Body. URL donde recibirás las notificaciones de eventos relacionados a la transacción, como cambios de status. | Opcional | https://link-your-webhook-notification.com |
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" |
schedule_date | Body. Fecha de ejecución del payout. El valor debe estar en el futuro y en el formato estándar ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"), sin huso horario. El huso horario se infiere automáticamente según el país de la solicitud. Vea más información en Programar transacciones | Opcional | 2026-12-31T10:00:00 |
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. Correo electrónico de la cuenta Mercado Pago de destino. | Requerido para transferencias entre cuentas Mercado Pago. | test_user_mx@testuser.com |
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 | MXN |
transactions.amount.value | Body. Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 1 y el máximo es 10000000000. | Requerido | 100 |
transactions.external_reference | Body. Referencia para identificar la transacción. Es generada por el integrador para permitir el rastreo de la salida de dinero y puede ser cualquier valor numérico (1234), desde que no exceda 7 caracteres. No puedes usar caracteres especiales (" ", [ ], ( ), @), letras (abcde), guiones (-) ni guiones bajos (_), y no puede estar duplicada. | Obligatorio | 000156 |
Si la ejecución fue exitosa, recibirás como respuesta un status code 202, indicando que la transacción fue aceptada, como en el ejemplo a continuación.
json
{ "id": "POP01KM145R903TZ06BWK6204DGG1", "external_reference": "000197", "description": "Payout for seller commissions", "idempotency_key": "1773859430", "created_date": "2026-03-18T14:43:50-04:00", "status": "created", "schedule_date": "2026-12-31T10:00:00", "config": { "notification_url": "https://link-your-webhook-notification.com" } }
| Atributo | Descripción |
id | Identificador único de la transacción, generado automáticamente. |
external_reference | Referencia externa de la transacción, generada por el integrador en la hora de la creación. |
description | Texto de descripción de la operación del payout completo, con todas las transferencias enviadas. |
idempotency_key | Clave de idempotencia para evitar duplicados. |
created_date | Fecha de creación de la transacción. |
status | Status actual de la transacción. |
schedule_date | Fecha de ejecución del payout. El valor estará en el futuro y en el formato estándar ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"). |
config.notification_url | URL donde recibirás las notificaciones de eventos relacionados a la transacción, como cambios de status. |
pending, debes ejecutar la llamada para obtener lista de transacciones o obtener información sobre una transacción para verificar su actualización.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/{{payout_id}}/transactions?limit=10&offset=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Campo | Descripción | Requerido | Ejemplo |
payout_id | Path. String. Identificador del payout cuya transacción deseas consultar, retornado en la respuesta a su creación dentro del campo id. | Requerido | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
limit | Query. Número máximo de transacciones a devolver en la lista. Límite de 100 transacciones. | Opcional | 10 |
offset | Query. Número de transacciones a ser omitidas de la lista. | Opcional | 0 |
Authorization | Header. Hace referencia a tu clave privada, el 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.. | Requerido | - |
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. | 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": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "value": 1000 } } ] }
| 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. |
| transactions.id | Identificador único de la transacción, generado automáticamente. |
| transactions.created_date | Fecha de creación de la transacción. |
| transactions.last_update_date | Fecha de actualización del status de la transacción. |
| transactions.external_reference | Referencia externa de la transacción, generada por el integrador en la hora de la creación. |
| transactions.status | Status actual de la transacción. |
| transactions.status_detail | Información detallada del status de la transacción. |
| transactions.type | Tipo de transacción. El valor siempre será "TRANSACTION" para las transferencias bancarias vía Payouts. |
| transactions.amount.currency | Identificador de la moneda utilizada en la transacción. |
| transactions.amount.value | Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 1 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/{{payout_id}}/transactions/{{transaction_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Campo | Descripción | Requerido | Ejemplo |
payout_id | Path. String. Identificador del payout cuya transacción deseas consultar, retornado en la respuesta a su creación dentro del campo id. | Requerido | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
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 | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Hace referencia a tu clave privada, el 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.. | Requerido | - |
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. | true |
Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:
json
{ "id": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "value": 1000 } }
| 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. |
| type | Tipo de transacción. El valor siempre será "TRANSACTION" para las transferencias bancarias vía Payouts. |
| 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 1 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 '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": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T10:00:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Campo | Descripción | Requerido | Ejemplo |
Authorization | Header. Hace referencia a tu clave privada, el 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.. | Requerido | - |
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 salientar 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-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. | true |
external_reference | Body. Referencia para identificar el payout. La genera el integrador y puede ser cualquier valor numérico (1234) que permita el rastreo de la transacción, siempre que no exceda 7 caracteres y no esté duplicada. No puedes usar caracteres especiales (" ", [ ], ( ), @), letras (abcde), guiones (-) ni guiones bajos (_). | Obligatorio | 000197 |
schedule_date | Body. Fecha de ejecución del payout. El valor debe estar en el futuro y en el formato estándar ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"), sin huso horario. El huso horario se infiere automáticamente según el país de la solicitud. | Opcional | 2026-12-31T10:00:00 |
config | Body. Objeto que contiene configuraciones del usuario que realiza la transacción. | Opcional | - |
config.notification_url | Body. URL donde recibirás las notificaciones de eventos relacionados a la transacción, como cambios de status. | Opcional | https://link-your-webhook-notification.com |
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. Correo electrónico de la cuenta Mercado Pago de destino. | Requerido para transferencias entre cuentas Mercado Pago. | test_user_mx@testuser.com |
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 | MXN |
transactions.amount.value | Body. Valor de la transacción que será debitado de la cuenta corriente de origen. El valor mínimo es 1 y el máximo es 10000000000. | Requerido | 100 |
transactions.external_reference | Body. Referencia para identificar la transacción. Es generada por el integrador para permitir el rastreo de la salida de dinero y puede ser cualquier valor numérico (1234), desde que no exceda 7 caracteres. No puedes usar caracteres especiales (" ", [ ], ( ), @), letras (abcde), guiones (-) ni guiones bajos (_), y no puede estar duplicada. | Obligatorio | 000156 |
Si la ejecución fue exitosa, recibirás como respuesta un status code 202, indicando que la transacción fue aceptada.
pending, debes ejecutar la llamada para Obtener lista de transacciones o 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/{{payout_id}}/transactions/{{transaction_id}}/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 |
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 | POP01KKCFKH9J2C8TQSQZM4R3Z22C |
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 | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Hace referencia a tu clave privada, el 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.. | Requerido | - |
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. | 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 |
Si la ejecución fue exitosa, recibirás como respuesta un status code 204, indicando que la transacción fue cancelada.