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 única 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.
Veja abaixo como configurar a integração de uma única transação para uma conta de destino.
Para integrar Payouts e permitir retiradas 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 --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": "000197", "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 | 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. Referência para identificar o payout. É gerada pelo integrador e pode ser qualquer valor numérico (1234) que permita o rastreamento da transação, desde que não exceda 7 caracteres e não seja duplicada. Não é possível utilizar caracteres especiais ("", [ ], (), @), letras (abcde), hífens (-) e underlines (_). | Obrigatório | 000197 |
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.cl/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.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 banco ao qual pertence a conta de destino. O valor padrão é de 3 dígitos e sempre serão os 3 primeiros números da CLABE. | Obrigatório | 646 |
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.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.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á como resposta um status code 200, indicando que a transação foi aceita, como no exemplo a seguir.
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.json
{ "created_date": "2024-11-13T14:18:07.052+00:00", "external_reference": "000197", "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 | 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.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. |
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": "2024-11-13T14:18:07.052+00:00", "external_reference": "000197", "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 mais informações sobre os status retornados, acesse Status de uma transação.