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.
With Payouts, you can send money in two different ways: Pix or transfer between accounts, whether they are Mercado Pago accounts or bank accounts. Follow the instructions below to learn how to integrate in each case.
To integrate Payouts and enable money transfers via Pix, 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.
To offer payments via Pix, you need to have Pix keys registered. If you don't have them yet, click here for more information on how to register them.
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://example.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 } }'
| 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. | Not required in the testing environment, and required in the production environment, where 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. String with a reference to identify the transaction. It is generated by the integrator and it can be any value that allows transactions to be tracked as long as it does not have special characters (“”, [ ], (), @) and does not exceed 64 characters. Numbers (1234), letters (abcde) and middle and underscore hyphens (-; _) are allowed. Its value cannot be duplicated with another transaction. | Optional | MP0001 |
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.com.br/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.type | Body. Destination account type. Possible values are current, for Pix accounts, and mercadopago, for Mercado Pago accounts. | Required | current / mercadopago |
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.chave.type | Body. Type of Pix identification key. It must be a value from those indicated in the "Example" column. | Required | EMAIL, PHONE, CPF, CNPJ, PIX_CODE |
transaction.to.accounts.chave.value | Body. Value of the identification key of the selected Pix account in the chave.type field. | Required | 1234567890 |
transaction.to.accounts.owner.identification.type | Body. Type of identification of the holder of the destination account. | Required | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Identification number of the holder of the destination account. | Required | 1234567890 |
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 |
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.
If the execution was successful, you will automatically receive a response with status code 202, indicating that the transaction was accepted, as in the example below:
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" } }
| 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 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 Transaction status. |
transaction.to.accounts.owner.identification.number | Identification number of the holder of the destination account. |
transaction.to.accounts.owner.identification.type | Type of identification of the destination account holder. |
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.
To integrate Payouts and enable money transfers 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 -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://example.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 } }'
| 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. | Not required in the testing environment, and required in the production environment, where sending the signature is mandatory. | - |
external_reference | Body. String with a reference to identify the transaction. It is generated by the integrator and it can be any value that allows transactions to be tracked as long as it does not have special characters (“”, [ ], (), @) and does not exceed 64 characters. Numbers (1234), letters (abcde) and middle and underscore hyphens (-; _) are allowed. Its value cannot be duplicated with another transaction. | Optional | MP0001 |
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.com.br/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.type | Body. Destination account type. Possible values are current, for bank accounts, and mercadopago, for Mercado Pago accounts. | Required | current / mercadopago |
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. Identificador do Sistema de Pagamento Brasileiro (ISPB) number of the bank to which the destination account belongs. | Required | 99999004 |
transaction.to.accounts.branch | Body. Agency number of the receiving bank to which the destination account belongs. | Required | 0001 |
transaction.to.accounts.holder | Body. First and last name of the holder of the destination account. | Required | John Doe |
transaction.to.accounts.provider_id | Body. Identifier of the provider of the destination account. The only possible value is spi, identifier of the Instant Payment System. | Required | spi |
transaction.to.accounts.currency_id | Body. Identifier of the currency used in the transaction. The only possible value is BRL. | Required | BRL |
transaction.to.accounts.number | Body. Unique number representing the destination bank account. | Required | 10266732 |
transaction.to.accounts.owner.identification.type | Body. Type of identification of the holder of the destination account. | Required | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Identification number of the holder of the destination account. | Required | 1234567890 |
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 was 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": "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" } }
| 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 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 Transaction status. |
transaction.to.accounts.owner.identification.number | dentification number of the holder of the destination account. |
transaction.to.accounts.owner.identification.type | Type of identification of the destination account holder. |
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}}'
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.
If the data sent in the call is correct, you will receive a response like the following:
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" } }
For more information about the returned statuses, go to Transaction status