AI resources
Configure money transfers
The integration of Payouts is carried out by making a single call to the /v1/transaction-intents/process API for one transaction to a destination account. This means that the transaction is created and processed in a single request, and if the execution is successful, the money will be available to be withdrawn to the destination account, with no need for additional steps.
Destination accounts must be checking accounts, meaning it is not possible to transfer to a savings account.
See below how to configure the integration of a single transaction to a destination account.
To integrate Payouts and enable withdrawals to bank accounts, you need to send a POST with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/transaction-intents/processAPI. The corresponding parameters must be sent according to the detailed specifications in the table below.
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 } }'
| Field | Description | Required | Example |
X-signature | Header. Request signature with the body encrypted in base64 using the integrator's public and private keys. Check the Security encryption section if you need more information. | Required only in the production environment. | - |
X-Enforce-Signature | Header. Boolean to indicate whether the integrator will send the signature or not. | Optional in the testing environment, and required in the production environment, which is when sending the signature is mandatory. | - |
X-Test-Token | Header. Boolean to indicate whether the request will be a test (true) or not (false). You must use it for the request to be sent to the test environment. When using this header, you can set X-Enforce-Signature to true and use X-Signature to test validation of the encrypted body. | Required as true when it is a test. | false |
external_reference | Body. Reference used to identify the payout. It is generated by the integrator and can be any numeric value (1234) that allows tracking the transaction, as long as it does not exceed 7 characters and is not duplicated. You cannot use special characters (" ", [ ], ( ), @), letters (abcde), hyphens (-), or underscores (_). | Required | 000197 |
point_of_interaction.type | Body. Fix value. It must always be {"type":"PSP_TRANSFER"} | Required | {"type":"PSP_TRANSFER"} |
seller_configuration.notification_info.notification_url | Body. URL where notifications of events related to the transaction, such as status changes, will be received. This field has a limit of 500 characters. | Optional | http://example.cl/notification |
transaction.from.accounts.amount | Body. Transaction amount, which will be withdrawn from the source account from. The minimum value is 0, and the maximum is 10000000000. | Required | 100,00 |
transaction.to.accounts.amount | Body. Amount to be sent to the destination account indicated in to. It must be the same value indicated for from.accounts.amount. | Required | 100,00 |
transaction.to.accounts.bank_id | Body. Identification number of the bank to which the destination account belongs. The default value is 3 digits and always will be the first 3 numbers of the CLABE. | Required | 646 |
transaction.to.accounts.type | Body. Destination account type. Possible values are current, for bank accounts, and mercadopago, for Mercado Pago accounts. | Required | current / mercadopago |
transaction.to.accounts.number | Body. Unique number representing the destination bank account. | Required | 10266732 |
transaction.total_amount | Body. Total amount of the transaction. It must be the same value indicated for from.accounts.amount and to.accounts.amount | Required | 100,00 |
If the execution is successful, you will receive a response with status code 200, indicating that the transaction was accepted, as in the example below.
This response may take a few seconds. If your
status is pending, you must execute the request to Get information about a transaction to verify its update.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 } }
| Attribute | Description |
created_date | Transaction creation date. It will be in YYYY-MM-DDTHH:MM:SS.SSSZ format. |
external_reference | External reference of the transaction, generated by the integrator when creating it. |
id | Automatically generated unique transaction identifier. |
last_updated_date | Last update of the transaction status. It will be in YYYY-MM-DDTHH:MM:SS.SSSZ format. |
point_of_interaction.type | Point of interaction. It is a fix value, always {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL where notifications of events related to the transaction, such as status changes, will be received. |
status | Transaction status. To learn about possible status, go to Possible transaction status. |
transaction.from.accounts.amount | Amount debited from the origin Mercado Pago account. |
transaction.paid_amount | Total amount charged to the account holder of the origin account. It will be equal to from.accounts.amount, unless there has been a total or partial refund, indicated in refunded_amount |
transaction.payer.id | Identifier of the integrator holding the origin account. |
transaction.refunded_amount | In case of a refund, it will indicate the total amount refunded to the account holder of the origin account. If there was no refund, its value will be 0. |
transaction.to.accounts.amount | Amount transferred to the destination account. Its value will be equal to from.accounts.amount, unless there has been a total or partial refund, the latter indicated in the transaction.refunded_amount field. |
transaction.to.accounts.origin_id | Identifier that allows the transaction to be tracked within the banking system. |
transaction.to.accounts.amount.status_detail | Detailed information about the transaction status. To learn about possible status_detail, refer to Possible transaction status. |
transaction.to.accounts.bank_id | Identification number of the bank to which the destination account belongs. |
transaction.to.accounts.type | Destination account type. |
transaction.to.accounts.number | Unique number that represents the destination bank account. |
transaction.total_amount | Total value of the transaction. |
transaction.statement_descriptor | Additional message to the transaction. |
To learn in detail about all parameters sent and returned in this request, check our API Reference. Also, if you receive an error when sending the payment, check our error list for more information.
After creating a transaction, you can get detailed information about it. This allows you to verify if it was created correctly, check its status, or confirm the information received in your notifications.
To do so, send a GET with your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /v1/transaction-intents/{{transaction_intent_id}}API, replacing transaction_intent_id with the ID obtained in the response when creating the transaction.
curl
curl --location --request GET 'https://api.mercadopago.com/v1/transaction-intents/{{transaction_intent_id}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
If the data sent in the call is correct, you will receive a response like the following:
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 } }
For more information about the returned status, access Transaction status.