Recursos para IA
Configurar transferencias de dinero
La integración de Payouts se realiza mediante la ejecución de una única llamada a la API /v1/transaction-intents/process para una sola transacción a una cuenta 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.
Las cuentas de destino deben ser cuentas corrientes, o sea, no es posible transferir a una cuenta de ahorro.
Con Payouts, puedes enviar dinero de dos formas distintas: Pix o transferencia entre cuentas, sean cuentas del Mercado Pago o bancarias. Sigue las instrucciones a continuación para saber cómo realizar la integración en cada caso.
Para integrar Payouts y permitir transferencias de dinero vía Pix, es necesario 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 /v1/transaction-intents/processAPI. Los parámetros correspondientes deben ser enviados conforme a las especificaciones detalladas en la tabla a continuación.
Para ofrecer transferencias vía Pix, es necesario tener las claves Pix registradas. Si aún no las tienes, haz clic aquí para más información sobre cómo registrarlas.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/transaction-intents/process'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'X-signature: true' \ -H 'X-Enforce-Signature: false' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -H 'X-Test-Token: false' \ -d '{ "external_reference": "MP0001", "point_of_interaction": "{"type":"PSP_TRANSFER"}", "seller_configuration": { "notification_info": { "notification_url": "http://ejemplo.com.br/notification" } }, "transaction": { "from": { "accounts": [ { "amount": 100 } ] }, "to": { "accounts": [ { "type": "current", "amount": 100, "chave": { "type": "CPF", "value": "1234567890" }, "owner": { "identification": { "type": "CPF", "number": "1234567890" } } } ] }, "total_amount": 100 } }'
| Campo | Descripción | Requerido | Ejemplo |
X-signature | Header. Firma de la solicitud con el cuerpo cifrado en base 64 con las claves pública y privada del integrador. Accede a la sección Cifrado de seguridad si necesitas más información. | Requerido sólo en el ambiente de producción. | - |
X-Enforce-Signature | Header. Booleano para indicar si el integrador enviará o no la firma. | No requerido en ambiente de pruebas, y requerido en ambiente productivo, que es cuando es obligatorio enviar la firma. | - |
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. String con una referencia para identificar la transacción. Es generada por el integrador y puede ser cualquier valor que permita hacer un seguimiento de las transacciones siempre que no tenga caracteres especiales (“”, [ ], (), @) y no exceda los 64 caracteres. Sí están permitidos números (1234), letras (abcde) y guiones medios y bajos (-; _). Su valor no puede ser duplicado con otras transacciones. | Opcional | MP0001 |
point_of_interaction.type | Body. Valor fijo. Siempre debe ser {"type":"PSP_TRANSFER"} | Requerido | {"type":"PSP_TRANSFER"} |
seller_configuration.notification_info.notification_url | Body. URL en la que se recibirán las notificaciones de los eventos relacionados a la transacción, como sus cambios de estado. Este campo tiene un límite de 500 caracteres. | Opcional | http://ejemplo.com.br/notification |
transaction.from.accounts.amount | Body. Valor de la transacción, que será retirado de la cuenta de origen from. El valor mínimo es 0, y el máximo, 10000000000. | Requerido | 100,00 |
transaction.to.accounts.type | Body. Tipo de cuenta de destino. Los valores posibles son current, para cuentas Pix, y mercadopago, para cuentas Mercado Pago. | Requerido | current / mercadopago |
transaction.to.accounts.amount | Body. Monto a enviar a la cuenta destino indicada en el to. Debe ser el mismo valor indicado para from.accounts.amount. | Requerido | 100,00 |
transaction.to.accounts.chave.type | Body. Tipo de clave de identificación Pix. Debe ser un valor de entre los indicados en la columna “Ejemplo”. | Requerido | EMAIL, PHONE, CPF, CNPJ, PIX_CODE |
transaction.to.accounts.chave.value | Body. Valor de la clave de identificación de la cuenta Pix seleccionada en el campo chave.type. | Requerido | 1234567890 |
transaction.to.accounts.owner.identification.type | Body. Tipo de identificación del titular de la cuenta de destino. | Requerido | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Número de identificación del titular de la cuenta de destino. | Requerido | 1234567890 |
transaction.total_amount | Body. Monto total de la transacción. Debe ser el mismo valor indicado para from.accounts.amount y to.accounts.amount | Requerido | 100,00 |
Para conocer en detalle todos los parámetros enviados y retornados en esta solicitud, consulta nuestra Referencia de API. Además, si recibes un error al enviar la transferencia, consulta nuestra lista de errores para más información.
Si la ejecución fue exitosa, recibirás automáticamente una respuesta con status code 202, que indica que la transacción fue aceptada, como en el ejemplo a continuación:
json
{ "created_date": "2021-01-01T00:00:00.000Z", "external_reference": "123456", "id": "0d5020ed", "last_updated_date": "2021-01-01T00:00:00.000Z", "point_of_interaction": { "type": "{\"type\":\"PSP_TRANSFER\"}" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.com.br/notification" } }, "status": "approved", "transaction": { "from": { "accounts": [ { "amount": "100,00" } ] }, "paid_amount": 100, "payer": { "id": 123456543 }, "refunded_amount": 1, "to": { "accounts": [ { "amount": "100,00", "origin_id": "01AAAM001A1AY43FBR8WCM9CES", "status_details": [ {} ], "owner": { "identification": { "number": "1234567890", "type": "CPF" } } } ] }, "total_amount": 100, "statement_descriptor": "test" } }
| Atributo | Descripción |
created_date | Fecha de creación de la transacción. Será devuelto en formato AAAA-MM-DDTHH:MM:SS.SSSZ. |
external_reference | Referencia externa de la transacción, que fue generada por el integrador al momento de crearla. |
id | Identificador único de la transacción, generado automáticamente. |
last_updated_date | Última actualización del estado de la transacción. Será devuelto en formato AAAA-MM-DDTHH:MM:SS.SSSZ. |
point_of_interaction.type | Punto de interacción. Es un valor fijo, siempre {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL en la que se recibirán las notificaciones de los eventos relacionados a la transacción, como sus cambios de estado. |
status | Estado de la transacción. Para conocer los posibles estados, dirígete a Estado de una transacción. |
transaction.from.accounts.amount | Monto debitado de la cuenta Mercado Pago de origen. |
transaction.paid_amount | Monto total cobrado al titular de la cuenta de origen. Será igual a from.accounts.amount, salvo que haya habido un reembolso total o parcial, indicado en refunded_amount |
transaction.payer.id | Identificador del integrador titular de la cuenta de origen. |
transaction.refunded_amount | En caso de un reembolso, indicará el monto total reembolsado al titular de la cuenta de origen. Si no hubo ningún reembolso, su valor será 0. |
transaction.to.accounts.amount | Monto transferido a la cuenta de destino. Su valor será igual a from.accounts.amount, salvo que haya habido un reembolso total o parcial, indicado este último en el campo transaction.refunded_amount. |
transaction.to.accounts.origin_id | Identificador que permite rastrear la transacción dentro del sistema bancario. |
transaction.to.accounts.amount.status_detail | Información detallada del estado de la transacción. Para conocer los posibles status_detail, dirígete a Estado de una transacción. |
transaction.to.accounts.owner.identification.number | Número identificador del titular de la cuenta de destino. |
transaction.to.accounts.owner.identification.type | Tipo de identificación del titular de la cuenta. |
transaction.total_amount | Monto total de la transacción. |
transaction.statement_descriptor | Mensaje adicional a la transacción. |
Para conocer en detalle todos los parámetros enviados y retornados en esta solicitud, consulta nuestra Referencia de API. Además, si recibes un error al enviar a transferencia, consulta nuestra lista de errores para más información.
Para integrar Payouts y permitir transferencias de dinero para cuentas bancarias, es necesario 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 /v1/transaction-intents/processAPI. Los parámetros correspondientes deben ser enviados conforme a las especificaciones detalladas en la tabla a continuación.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/transaction-intents/process'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'X-signature: true' \ -H 'X-Enforce-Signature: false' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "external_reference": "MP0001", "point_of_interaction": {"type":"PSP_TRANSFER"}, "seller_configuration": { "notification_info": { "notification_url": "http://ejemplo.com.br/notification" } }, "transaction": { "from": { "accounts": [ { "amount": 100 } ] }, "to": { "accounts": [ { "type": "current", "amount": 100, "bank_id": "99999004", "branch": "0001", "holder": "Jonh Doe", "provider_id": "spi", "currency_id": "BRL", "number": "10266732", "owner": { "identification": { "type": "CPF", "number": "1234567890" } } } ] }, "total_amount": 100 } }'
| Campo | Descripción | Requerido | Ejemplo |
X-signature | Header. Firma de la solicitud con el cuerpo cifrado en base 64 con las claves pública y privada del integrador. Accede a la sección Cifrado de seguridad si necesitas más información. | Requerido sólo en el ambiente de producción. | - |
X-Enforce-Signature | Header. Booleano para indicar si el integrador enviará o no la firma. | No requerido en ambiente de pruebas, y requerido en ambiente productivo, que es cuando es obligatorio enviar la firma. | - |
external_reference | Body. String con una referencia para identificar la transacción. Es generada por el integrador y puede ser cualquier valor que permita hacer un seguimiento de las transacciones siempre que no tenga caracteres especiales (“”, [ ], (), @) y no exceda los 64 caracteres. Sí están permitidos números (1234), letras (abcde) y guiones medios y bajos (-; _). Su valor no puede ser duplicado con otras transacciones. | Opcional | MP0001 |
point_of_interaction.type | Body. Valor fijo. Siempre debe ser {"type":"PSP_TRANSFER"} | Requerido | {"type":"PSP_TRANSFER"} |
seller_configuration.notification_info.notification_url | Body. URL en la que se recibirán las notificaciones de los eventos relacionados a la transacción, como sus cambios de estado. Este campo tiene un límite de 500 caracteres. | Opcional | http://ejemplo.com.br/notification |
transaction.from.accounts.amount | Body. Valor de la transacción, que será retirado de la cuenta de origen from. El valor mínimo es 0, y el máximo, 10000000000. | Requerido | 100,00 |
transaction.to.accounts.type | Body. Tipo de cuenta de destino. Los valores posibles son current, para cuentas bancarias, y mercadopago, para cuentas Mercado Pago. | Requerido | current / mercadopago |
transaction.to.accounts.amount | Body. Monto a enviar a la cuenta destino indicada en el to. Debe ser el mismo valor indicado para from.accounts.amount. | Requerido | 100,00 |
transaction.to.accounts.bank_id | Body. Número Identificador do Sistema de Pagamento Brasileiro (ISPB) del banco al que pertenece la cuenta de destino. | Requerido | 99999004 |
transaction.to.accounts.branch | Body. Número de agencia del banco receptor al que pertenece la cuenta de destino. | Requerido | 0001 |
transaction.to.accounts.holder | Body. Nombre y apellido del titular de la cuenta de destino. | Requerido | John Doe |
transaction.to.accounts.provider_id | Body. Identificador del proveedor de la cuenta de destino. El único valor posible es spi, identificador del Sistema de Pagos Instantáneos. | Requerido | spi |
transaction.to.accounts.currency_id | Body. Identificador de la moneda utilizada en la transacción. El único valor posible es BRL. | Requerido | BRL |
transaction.to.accounts.number | Body. Número único que representa la cuenta bancaria de destino. | Requerido | 10266732 |
transaction.to.accounts.owner.identification.type | Body. Tipo de identificación del titular de la cuenta de destino. | Requerido | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Número de identificación del titular de la cuenta de destino. | Requerido | 1234567890 |
transaction.total_amount | Body. Monto total de la transacción. Debe ser el mismo valor indicado para from.accounts.amount y to.accounts.amount | Requerido | 100,00 |
Ten en cuenta que esta respuesta puede tardar unos segundos y que, en caso de que su
status sea pending, deberás ejecutar el llamado para Obtener información sobre una transacción para verificar su actualización.Si la ejecución fue exitosa, recibirás una respuesta con status code 200, que indica que la transacción fue aceptada, como en el ejemplo a continuación.
json
{ "created_date": "2021-01-01T00:00:00.000Z", "external_reference": "123456", "id": "0d5020ed", "last_updated_date": "2021-01-01T00:00:00.000Z", "point_of_interaction": { "type": "{\"type\":\"PSP_TRANSFER\"}" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.com.br/notification" } }, "status": "approved", "transaction": { "from": { "accounts": [ { "amount": "100,00" } ] }, "paid_amount": 100, "payer": { "id": 123456543 }, "refunded_amount": 1, "to": { "accounts": [ { "amount": "100,00", "origin_id": "01AAAM001A1AY43FBR8WCM9CES", "status_details": [ {} ], "owner": { "identification": { "number": "1234567890", "type": "CPF" } }, "bank_id": "0000014", "type": "checking_account", "number": "123456" } ] }, "total_amount": 100, "statement_descriptor": "test" } }
| Atributo | Descripción |
created_date | Fecha de creación de la transacción. Será devuelto en formato AAAA-MM-DDTHH:MM:SS.SSSZ. |
external_reference | Referencia externa de la transacción, que fue generada por el integrador al momento de crearla. |
id | Identificador único de la transacción, generado automáticamente. |
last_updated_date | Última actualización del estado de la transacción. Será devuelto en formato AAAA-MM-DDTHH:MM:SS.SSSZ. |
point_of_interaction.type | Punto de interacción. Es un valor fijo, siempre {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL en la que se recibirán las notificaciones de los eventos relacionados a la transacción, como sus cambios de estado. |
status | Estado de la transacción. Para conocer los posibles estados, dirígete a Estado de una transacción. |
transaction.from.accounts.amount | Monto debitado de la cuenta Mercado Pago de origen. |
transaction.paid_amount | Monto total cobrado al titular de la cuenta de origen. Será igual a from.accounts.amount, salvo que haya habido un reembolso total o parcial, indicado en refunded_amount |
transaction.payer.id | Identificador del integrador titular de la cuenta de origen. |
transaction.refunded_amount | En caso de un reembolso, indicará el monto total reembolsado al titular de la cuenta de origen. Si no hubo ningún reembolso, su valor será 0. |
transaction.to.accounts.amount | Monto transferido a la cuenta de destino. Su valor será igual a from.accounts.amount, salvo que haya habido un reembolso total o parcial, indicado este último en el campo transaction.refunded_amount. |
transaction.to.accounts.origin_id | Identificador que permite rastrear la transacción dentro del sistema bancario. |
transaction.to.accounts.amount.status_detail | Información detallada del estado de la transacción. Para conocer los posibles status_detail, dirígete a Estado de una transacción. |
transaction.to.accounts.owner.identification.number | Número identificador del titular de la cuenta de destino. |
transaction.to.accounts.owner.identification.type | Tipo de identificación del titular de la cuenta. |
transaction.to.accounts.bank_id | Número identificador del banco al que pertence la cuenta de destino. |
transaction.to.accounts.type | Tipo de cuenta de destino. |
transaction.to.accounts.number | Número único que representa la cuenta de destino. |
transaction.total_amount | Monto total de la transacción. |
transaction.statement_descriptor | Mensaje adicional a la transacción. |
Para conocer en detalle todos los parámetros enviados y retornados en esta solicitud, consulta nuestra Referencia de API. Además, si recibes un error al enviar la transferencia, consulta nuestra lista de errores para más información.
Después de crear una transacción, es posible obtener información detallada sobre ella. Esto permite verificar si fue creada correctamente, consultar su status o confirmar 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/transaction-intents/{{transaction_intent_id}}API, reemplazando el transaction_intent_id por el ID obtenido en la respuesta al crear la transacción.
curl
curl --location --request GET 'https://api.mercadopago.com/v1/transaction-intents/{{transaction_intent_id}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
Para conocer en detalle todos los parámetros enviados y retornados en esta solicitud, consulta nuestra Referencia de API. Además, si recibes un error al enviar a transferencia, consulta nuestra lista de errores para más información.
Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:
json
{ "created_date": "2021-01-01T00:00:00.000Z", "external_reference": "123456", "id": "0d5020ed", "last_updated_date": "2021-01-01T00:00:00.000Z", "point_of_interaction": { "type": "{\"type\":\"PSP_TRANSFER\"}" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.cl/notification" } }, "status": "approved", "transaction": { "from": { "accounts": [ { "amount": "100,00" } ] }, "paid_amount": 100, "payer": { "id": 123456543 }, "refunded_amount": 1, "to": { "accounts": [ { "amount": "100,00", "origin_id": "01AAAM001A1AY43FBR8WCM9CES", "status_details": [ {} ], "owner": { "identification": { "number": "1234567890", "type": "CPF" } }, "bank_id": "0000014", "type": "checking_account", "number": "123456" } ] }, "total_amount": 100, "statement_descriptor": "test" } }
Para más información sobre los estados retornados, dirígete a Estado de una transacción