Integration configuration

The integration of Money Out is done by making a single API call to v1/transaction-intents. This way, the transaction is created and processed in a single request and, if successful, the money will be available to be withdrawn to the destination account, without the need for additional steps.

With Money Out, you can send money in two different ways: via Pix, or by transferring to a money account, whether it's a bank account or a Mercado Pago one. Follow the instructions below to learn how to integrate in each case.

Important

To set up the integration and test its proper functioning before going live, you'll need to use your test Access Token..

Set up withdrawals via Pix

To integrate Money Out and enable money withdrawals via Pix, you'll need to send a POST request, with your test Access Token in the Authorization header and your idempotency key in the X-Idempotency-Key header, to the endpoint /v1/transaction-intents/process. You should send the corresponding parameters following the instructions in the table below.

Note

Please note that only one destination account (transaction.to) per call is allowed. Additionally, the integrator's Pix key must have been previously registered, and the destination account's key must be active.

curl -X POST \
    'https://api.mercadopago.com/v1/transaction-intents/process'\
    -H 'Content-Type: application/json' \
       -H 'X-Idempotency-Key: {{idempotency_key}}' \
       -H 'x-Signature: true' \
       -H 'x-enforce-signature: false' \
       -H 'Authorization: Bearer TEST-7434*********159-03141*********cee51edf8*********f94f589-1*********' \
    -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/Optional	Example
`x-signature`	Header. Request signature with the body encrypted in base64 using the integrator's public and private keys. Check the End-to-end 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 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

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:

{
  "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 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.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.

Set up withdrawals to bank accounts

To integrate Money Out with destination to bank accounts, first obtain the list of available banks to make the transaction. To do this, send a GET with your Access Token to the following endpoint:

curl --request GET \
  --url https://api.mercadopago.com/open-banking/payments/v1/banks \
  --header 'Authorization: Bearer <ENV_ACCESS_TOKEN>'

Then, if the bank to which the destination account belongs is available to carry out the transaction, you will need to send a POST request, with your Access Token in the Authorization header and your idempotency key in the X-Idempotency-Key header, to the endpoint /v1/transaction-intents/process. You should send the corresponding parameters following the instructions in the table below.

Note

Please note that only one destination account (transaction.to) per call is allowed.

curl -X POST \
    'https://api.mercadopago.com/v1/transaction-intents/process'\
    -H 'Content-Type: application/json' \
       -H 'X-Idempotency-Key: {{idempotency_key}}' \
       -H 'x-Signature: true' \
       -H 'x-enforce-signature: false' \
       -H 'Authorization: Bearer TEST-7434*********159-03141*********cee51edf8*********f94f589-1*********' \
    -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/Optional	Example
`x-signature`	Header. Request signature with the body encrypted in base64 using the integrator's public and private keys. Check the End-to-end 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 automatically receive a response with status code 202, indicating that the transaction was accepted, as in the example below.

Important

Please note that this response may take a few seconds, and if its status is pending, you should make a call to Get information about a transaction to check its update.

{
  "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 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.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.

Set up notifications

In order to keep track of the status of your transactions, you must configure the Webhook notifications. These are messages sent by the Mercado Pago server in response to events that occur in your application. Specifically for Money Out, these events can be either the creation of a transaction or the status updates that the transaction goes through during its processing.

You can configure your Webhook notifications when creating a transaction by using the notification_url field. Simply fill it with the URL where you want to receive your updates.

You can see examples of the messages you will receive when registering an event below.

- Message for transaction creation.

{
  "action": "transaction_intent.created",
  "api_version": "v1",
  "data": {
    "id": "1108917506-01GGTH198RP0K71H133EK9BJAT" // ID of the transaction intent
  },
  "date_created": "2022-11-01T17:19:53.915-04:00",
  "id": "103686924004", // ID of the notification
  "last_updated": "0001-01-01T00:00:00Z",
  "status": "new",
  "type": "transaction_intent"
}

- Message for a transaction update.

{
  "action": "transaction_intent.updated",
  "api_version": "v1",
  "data": {
    "id": "1108917506-01GGTH198RP0K71H133EK9BJAT" // ID of the transaction intent
  },
  "date_created": "2022-11-01T17:19:53.915-04:00",
  "id": "103686918006", // ID of the notification
  "last_updated": "2022-11-01T17:19:55.001-04:00",
  "status": "partially_processed",
  "type": "transaction_intent"
}

The data.id attribute corresponds to the ID of the transaction being notified to you, the id parameter will be the identifier of the notification, and status will inform you whether it is the creation of the transaction or the update of its status.

Required actions after receiving the notification

When you receive a notification on your platform, you should first validate the information of the notified resource. To do this, execute the request for Get information about a transaction using the transaction ID that was notified to you.

Once the transaction data is cross-validated and verified, Mercado Pago expects a response to ensure that the notification was received correctly. To do this, you should return an HTTP STATUS 200 (OK) or 201 (CREATED) to the URL sent in the notification_url field. If this response is not sent, it will be understood that you have not received the notification and a new sending attempt will be made until the response is received.

In the following table, you can find the main events, deadlines, and waiting time to receive new notification attempts.

Event	Deadline after the first sending	Confirmation waiting time
Sending	-	22 seconds
First attempt	15 minutes	5 seconds
Second attempt	30 minutes	5 seconds
Third attempt	6 hours	5 seconds
Fourth attempt	48 hours	5 seconds
Fifth attempt	96 hours	5 seconds

Get information about a transaction

If you wish, you can retrieve information about a transaction. This can be useful to confirm that it was created correctly, to check its status, or to verify the information received in your notifications.

To do so, send a GET request with your Access Token to the endpoint /v1/transaction-intents/{{transaction_intent_id}}, replacing transaction_intent_id with the ID obtained in the response at the time of creating the transaction.

curl --location --request GET 'https://api.mercadopago.com/v1/transaction-intents/{{transaction_intent_id}}' \
--header 'Authorization: Bearer {{access_token}}'

If the data sent in the call is correct, you will receive a response like the following:

{
  "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": "RUT"
            }
          },
          "bank_id": "0000014",
          "type": "checking_account",
          "number": "123456"
        }
      ]
    },
    "total_amount": 100,
    "statement_descriptor": "test"
  }
}

To know the details of each returned attribute, refer to the response in the Withdrawals Configuration.

Possible transaction status

When you create a transaction or when you query information related to it, the responses will return two fields that allow you to know the state in which it currently stands.

On one hand, the status field will provide information regarding the current processing status. On the other hand, the status_detail field, found as an attribute of transaction.to.accounts, will allow you to understand the reasons or details that resulted in that status.

Below, you can see all the possible status a transaction can go through during its processing.

`status`	`status_detail`	Description
`processed`	`approved`	The transaction processing was successful.
`approved`	`partially_refunded`	The transaction was partially refunded by the destination bank.
`transaction_in_process`	`pending_authorized`	The transaction is in process, awaiting final status, and awaits authorization.
`transaction_in_process`	`pending_bank`	The destination bank did not respond, so the transaction is pending final status.
`refunded`	`refunded`	The transaction was refunded by the destination bank.
`rejected`	`by_bank`	The destination bank rejected the transfer. Please make the request again.
`rejected`	`by_provider`	The provider rejected the transfer. Please make the request again.
`rejected`	`high_risk`	The transaction is rejected due to fraud risk. Please make the request again.
`rejected`	`insufficient_funds`	Transaction rejected due to insufficient funds in the origin account. Please make the request again.
`rejected`	`other_reason`	Transaction rejected by default due to internal issues during processing. Please make the request again.
`rejected`	`review_manual`	The transaction is rejected and referred to fraud prevention for analysis. Please make the request again.