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.
Ve a continuación cómo configurar la integración de una sola transacción a una cuenta de destino.
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 --request POST \ --url https://api.mercadopago.com/v1/transaction-intents/process \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: false' \ --data '{ "external_reference": "12345", "point_of_interaction": { "type": "PSP_TRANSFER" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.mx/notification" } }, "transaction": { "from": { "accounts": [ { "amount": 25 } ] }, "to": { "total_amount": 25, "accounts": [ { "amount": 25, "bank_id": "646", "number": "646180110400000007", "holder": "JUAN JOSE MARIA", "type": "savings_account", "description": "envio de 25" } ] }, "total_amount": 25 } }'
| 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. | Opcional 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. 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 |
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 donde recibirá las notificaciones de eventos relacionados a la transacción, como mudanzas de estado. Este campo tiene un límite de 500 caracteres. | Opcional | http://ejemplo.cl/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 es 10000000000. | Requerido | 100,00 |
transaction.to.accounts.amount | Body. Monto a ser enviado para la cuenta de destino indicado 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 del banco al que pertenece la cuenta de destino. El valor por defecto es de 3 dígitos y siempre serán los 3 primeros números de la CLABE. | Requerido | 646 |
transaction.to.accounts.type | Body. Tipo de cuenta de destino. Los valores posibles son current, para cuentas bancarias, y mercadopago, para cuentas del Mercado Pago. | Requerido | current / mercadopago |
transaction.to.accounts.number | Body. Número único que representa cada cuenta bancaria. En este caso, el número único de la cuenta de destino. | Requerido | 10266732 |
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 como respuesta un status code 200, indicando que la transacción fue aceptada, como en el ejemplo a continuación.
Esta respuesta puede demorar algunos segundos. Si tu
status es pending, debes ejecutar la solicitud para Obtener información sobre una transacción para verificar su actualización.json
{ "created_date": "2024-11-13T14:18:07.052+00:00", "external_reference": "12345", "id": "22dvqmseu6a", "last_updated_date": "2024-11-13T14:18:07.663+00:00", "point_of_interaction": { "type": "PSP_TRANSFER" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.mx/notification" } }, "status": "processed", "transaction": { "from": { "accounts": [ { "amount": 25, "status_details": [] } ] }, "paid_amount": 0, "payer": { "id": 1992483662 }, "refunded_amount": 0, "to": { "accounts": [ { "amount": 25, "description": "envio de 25", "origin_id": "01JCJY70ACGJ2AP8433JGG0ZRY", "status_details": [] } ] }, "total_amount": 25, "statement_descriptor": "", "binary_mode": false } }
| 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, generada por el integrador en la hora de la creación. |
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. Valor fijo. Siempre debe ser {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL donde recibirá las notificaciones de eventos relacionados a la transacción, como mudanzas de estado. |
status | Estado de la transacción. Para verificar los posibles estados, consulta la sección 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, a menos que haya habido 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 reembolso, indicará el monto total reembolsado al titular de la cuenta de origen. Si no hubo reembolso, su valor será 0. |
transaction.to.accounts.amount | Monto transferido para la cuenta de destino. El monto será igual a from.accounts.amount, a menos que haya habido reembolso total o parcial indicado 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 operación. Para verificar los posibles status_detail, consulta la sección Status de una transacción. |
transaction.to.accounts.bank_id | Número identificador del banco al que pertenece 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 para la transacció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 la 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": "2024-11-13T14:18:07.052+00:00", "external_reference": "12345", "id": "22dvqmseu6a", "last_updated_date": "2024-11-13T14:18:07.663+00:00", "point_of_interaction": { "type": "PSP_TRANSFER" }, "seller_configuration": { "notification_info": { "notification_url": "http://example.mx/notification" } }, "status": "processed", "transaction": { "from": { "accounts": [ { "amount": 25, "status_details": [] } ] }, "paid_amount": 0, "payer": { "id": 1992483662 }, "refunded_amount": 0, "to": { "accounts": [ { "amount": 25, "description": "envio de 25", "origin_id": "01JCJY70ACGJ2AP8433JGG0ZRY", "status_details": [] } ] }, "total_amount": 25, "statement_descriptor": "", "binary_mode": false } }
Para más información sobre los status retornados, acceda Estado de una transacción.