Recursos para IA
Configurar transferências de dinheiro
A integração de Payouts é realizada executando uma única chamada à API /v1/transaction-intents/process para uma unica transação para uma conta de destino. Isso significa que a transação é criada e processada em uma única solicitação e, se a execução for bem-sucedida, o dinheiro estará disponível para ser retirado na conta de destino, sem a necessidade de etapas adicionais.
As contas de destino devem ser contas correntes, ou seja, não é possível transferir para uma conta poupança.
Com o Payouts é possível enviar dinheiro de duas formas distintas: Pix ou transferência entre contas, sejam elas contas do Mercado Pago ou bancárias. Siga as instruções abaixo para saber como realizar a integração em cada caso.
Para integrar o Payouts e permitir transferências de dinheiro via Pix, é necessário enviar um POST com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. ao endpoint /v1/transaction-intents/processAPI. Os parâmetros correspondentes devem ser enviados conforme as especificações detalhadas na tabela a seguir.
Para oferecer transferências via Pix, é necessário ter as chaves Pix cadastradas. Caso ainda não tenha, clique aqui para mais informações sobre como cadastrá-las.
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://exemplo.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 | Descrição | Obrigatoriedade | Exemplo |
X-signature | Header. Assinatura da solicitação com o corpo criptografado em base 64 usando as chaves pública e privada do integrador. Acesse a seção Criptografia de segurança se precisar de mais informações. | Obrigatório apenas no ambiente de produção. | - |
X-Enforce-Signature | Header. Booleano que indica se o integrador enviará ou não a assinatura. | Opcional em ambiente de testes, e obrigatório em ambiente produtivo, que é quando é obrigatório o envio da assinatura. | - |
X-Test-Token | Header. Booleano para indicar se a requisição será de teste (true) ou não (false), devendo ser usado para que a requisição seja feita no ambiente de teste. Ao utilizar este header, é possível usar o X-Enforce-Signature como true e usar o X-signature para testar a validação do body criptografado. | Obrigatório como true quando se tratar de um teste. | false |
external_reference | Body. String com uma referência para identificar a transação. Essa referência é gerada pelo integrador e pode ser qualquer valor que permita rastrear as transações, desde que não possua caracteres especiais (“”, [ ], (), @) e não exceda 64 caracteres. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_), e não pode ser duplicada. | Opcional | MP0001 |
point_of_interaction.type | Body. Valor fixo. Sempre deve ser {"type":"PSP_TRANSFER"}. | Obrigatório | {"type":"PSP_TRANSFER"} |
seller_configuration.notification_info.notification_url | Body. URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. Este campo tem um limite de 500 caracteres. | Opcional | http://exemplo.com.br/notification |
transaction.from.accounts.amount | Body. Valor da transação, que será retirado da conta de origem from. O valor mínimo é 0, e o valor máximo é 10000000000. | Obrigatório | 100,00 |
transaction.to.accounts.type | Body. Tipo de conta de destino. Os valores possíveis são current, para contas Pix, e mercadopago, para contas do Mercado Pago. | Obrigatório | current / mercadopago |
transaction.to.accounts.amount | Body. Valor a enviar para a conta de destino indicado no to. Deve ser o mesmo valor indicado para from.accounts.amount. | Obrigatório | 100,00 |
transaction.to.accounts.chave.type | Body. Tipo de chave de identificação Pix. Deve ser um valor entre os indicados na coluna “Exemplo”. | Obrigatório | EMAIL, PHONE, CPF, CNPJ, PIX_CODE |
transaction.to.accounts.chave.value | Body. Valor da chave de identificação da conta Pix selecionada no campo chave.type. | Obrigatório | 1234567890 |
transaction.to.accounts.owner.identification.type | Body. Tipo de identificação do titular da conta de destino. | Obrigatório | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Número de identificação do titular da conta de destino. | Obrigatório | 1234567890 |
transaction.total_amount | Body. Montante total da transação. Deve ser o mesmo valor indicado para from.accounts.amount e to.accounts.amount. | Obrigatório | 100,00 |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de API. Além disso, caso receba um erro ao enviar a transferência, consulte nossa lista de erros para mais informações.
Se a execução for bem-sucedida, você receberá automaticamente uma resposta com o status code 202, indicando que a transação foi aceita, como no exemplo a seguir:
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 | Descrição |
created_date | Data de criação da transação. Será retornada no formato YYYY-MM-DDTHH:MM:SS.SSSZ. |
external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
id | Identificador único da transação, gerado automaticamente. |
last_updated_date | Última atualização do status da transação. Será retornada no formato YYYY-MM-DDTHH:MM:SS.SSSZ. |
point_of_interaction.type | Ponto de interação. Valor fixo. Sempre deve ser {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. |
status | Status da transação. Para verificar os possíveis status, consulte a seção Status de uma transação. |
transaction.from.accounts.amount | Valor debitado da conta Mercado Pago de origem. |
transaction.paid_amount | Valor total cobrado ao titular da conta de origem. Será igual a from.accounts.amount, a menos que tenha havido reembolso total ou parcial, indicado em refunded_amount. |
transaction.payer.id | Identificador do integrador titular da conta de origem. |
transaction.refunded_amount | No caso de reembolso, indicará o valor total reembolsado ao titular da conta de origem. Se não houve reembolso, seu valor será 0. |
transaction.to.accounts.amount | Valor transferido para a conta de destino. O valor será igual a from.accounts.amount, a menos que tenha havido reembolso total ou parcial indicado no campo transaction.refunded_amount. |
transaction.to.accounts.origin_id | Identificador que permite rastrear a transação dentro do sistema bancário. |
transaction.to.accounts.amount.status_detail | Informação detalhada do status da operação. Para verificar os possíveis status_detail, consulte a seção Status de uma transação. |
transaction.to.accounts.owner.identification.number | Número identificador do titular da conta de destino. |
transaction.to.accounts.owner.identification.type | Tipo de identificação do titular da conta de destino. |
transaction.total_amount | Valor total da transação. |
transaction.statement_descriptor | Mensagem adicional para a transação. |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de API. Além disso, caso receba um erro ao enviar a transferência, consulte nossa lista de erros para mais informações.
Para integrar Payouts e permitir transferências de dinheiro para contas bancárias é necessário enviar um POST com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. ao endpoint /v1/transaction-intents/processAPI. Os parâmetros correspondentes devem ser enviados conforme as especificações detalhadas na tabela a seguir.
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://exemplo.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 | Descrição | Obrigatoriedade | Exemplo |
X-signature | Header. Assinatura da solicitação com o corpo criptografado em base 64 usando as chaves pública e privada do integrador. Acesse a seção Criptografia de segurança se precisar de mais informações. | Obrigatório apenas no ambiente de produção. | - |
X-Enforce-Signature | Header. Booleano que indica se o integrador enviará ou não a assinatura. | Opcional em ambiente de testes, e obrigatório em ambiente produtivo, que é quando é obrigatório o envio da assinatura. | - |
external_reference | Body. String com uma referência para identificar a transação. Essa referência é gerada pelo integrador e pode ser qualquer valor que permita rastrear as transações, desde que não possua caracteres especiais (“”, [ ], (), @) e não exceda 64 caracteres. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_), e não pode ser duplicada. | Opcional | MP0001 |
point_of_interaction.type | Body. Valor fixo. Sempre deve ser {"type":"PSP_TRANSFER"}. | Obrigatório | {"type":"PSP_TRANSFER"} |
seller_configuration.notification_info.notification_url | Body. URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. Este campo tem um limite de 500 caracteres. | Opcional | http://exemplo.com.br/notification |
transaction.from.accounts.amount | Body. Valor da transação, que será retirado da conta de origem from. O valor mínimo é 0, e o valor máximo é 10000000000. | Obrigatório | 100,00 |
transaction.to.accounts.type | Body. Tipo de conta de destino. Os valores possíveis são current, para contas bancárias, e mercadopago, para contas do Mercado Pago. | Obrigatório | current / mercadopago |
transaction.to.accounts.amount | Body. Valor a ser enviado para a conta de destino indicado no to. Deve ser o mesmo valor indicado para from.accounts.amount. | Obrigatório | 100,00 |
transaction.to.accounts.bank_id | Body. Número Identificador do Sistema de Pagamento Brasileiro (ISPB) do banco ao qual pertence a conta de destino. | Obrigatório | 99999004 |
transaction.to.accounts.branch | Body. Número de agência no banco recebedor à qual pertence a conta de destino. | Obrigatório | 0001 |
transaction.to.accounts.holder | Body. Nome e sobrenome do titular da conta de destino. | Obrigatório | John Doe |
transaction.to.accounts.provider_id | Body. Identificador do provedor da conta de destino. O único valor possível é spi, identificador do Sistema de Pagamentos Instantâneos. | Obrigatório | spi |
transaction.to.accounts.currency_id | Body. Identificador da moeda utilizada na transação. O único valor possível é BRL. | Obrigatório | BRL |
transaction.to.accounts.number | Body. Número único que representa cada conta bancária. Neste caso, o número único da conta de destino. | Obrigatório | 10266732 |
transaction.to.accounts.owner.identification.type | Body. Tipo de identificação do titular da conta de destino. | Obrigatório | “CPF” “CNPJ” |
transaction.to.accounts[n].owner.identification.number | Body. Número de identificação do titular da conta de destino. | Obrigatório | 1234567890 |
transaction.total_amount | Body. Montante total da transação. Deve ser o mesmo valor indicado para from.accounts.amount e to.accounts.amount. | Obrigatório | 100,00 |
Esta resposta pode demorar alguns segundos. Se seu
status for pending, deve-se executar a requisição para Obter informações sobre uma transação para verificar sua atualização.Se a execução for bem-sucedida, você receberá como resposta um status code 200, indicando que a transação foi aceita, como no exemplo a seguir.
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 | Descrição |
created_date | Data de criação da transação. Será retornada no formato YYYY-MM-DDTHH:MM:SS.SSSZ. |
external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
id | Identificador único da transação, gerado automaticamente. |
last_updated_date | Última atualização do status da transação. Será retornada no formato YYYY-MM-DDTHH:MM:SS.SSSZ. |
point_of_interaction.type | Ponto de interação. Valor fixo. Sempre deve ser {"type":"PSP_TRANSFER"}. |
seller_configuration.notification_info.notification_url | URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. |
status | Status da transação. Para verificar os possíveis status, consulte a seção Status de uma transação. |
transaction.from.accounts.amount | Valor debitado da conta Mercado Pago de origem. |
transaction.paid_amount | Valor total cobrado ao titular da conta de origem. Será igual a from.accounts.amount, a menos que tenha havido reembolso total ou parcial, indicado em refunded_amount. |
transaction.payer.id | Identificador do integrador titular da conta de origem. |
transaction.refunded_amount | No caso de reembolso, indicará o valor total reembolsado ao titular da conta de origem. Se não houve reembolso, seu valor será 0. |
transaction.to.accounts.amount | Valor transferido para a conta de destino. O valor será igual a from.accounts.amount, a menos que tenha havido reembolso total ou parcial indicado no campo transaction.refunded_amount. |
transaction.to.accounts.origin_id | Identificador que permite rastrear a transação dentro do sistema bancário. |
transaction.to.accounts.amount.status_detail | Informação detalhada do status da operação. Para verificar os possíveis status_detail, consulte a seção Status de uma transação. |
transaction.to.accounts.owner.identification.number | Número identificador do titular da conta de destino. |
transaction.to.accounts.owner.identification.type | Tipo de identificação do titular da conta de destino. |
transaction.to.accounts.bank_id | Número identificador do banco ao qual pertence a conta de destino. |
transaction.to.accounts.type | Tipo de conta de destino. |
transaction.to.accounts.number | Número único que representa a conta de destino. |
transaction.total_amount | Valor total da transação. |
transaction.statement_descriptor | Mensagem adicional para a transação. |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de API. Além disso, caso receba um erro ao enviar a transferência, consulte nossa lista de erros para mais informações.
Após criar uma transação, é possível obter informações detalhadas sobre ela. Isso permite verificar se ela foi criada corretamente, consultar seu status ou confirmar as informações recebidas em suas notificações.
Para isso, envie um GET com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. ao endpoint /v1/transaction-intents/{{transaction_intent_id}}API, substituindo o transaction_intent_id pelo ID obtido na resposta ao criar a transação.
curl
curl --location --request GET 'https://api.mercadopago.com/v1/transaction-intents/{{transaction_intent_id}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de API. Além disso, caso receba um erro ao enviar a transferência, consulte nossa lista de erros para mais informações.
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
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 mais informações sobre os status retornados, acesse Status de uma transação