Configurar transferências de dinheiro
A integração de Payouts é realizada executando uma única chamada à API /v1/payouts para múltiplas transações para várias contas 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.
Veja abaixo como configurar a integração de múltiplas transações para várias contas de destino.
Para integrar Payouts com destino a contas bancárias ou entre contas Mercado Pago, você deve enviar um POST com seu Access Token no header Authorization e sua chave de idempotência no header X-Idempotency-Key para o endpoint /v1/payouts. Você deve enviar os parâmetros correspondentes seguindo as indicações da tabela abaixo.
- Transferências entre contas Mercado Pago:
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: false' \ --data-raw '{ "config": { "notification_url": "https://webhook.site/d774cfea-67b7-4423-9dab-87c839ab4a0e" }, "external_reference": "global_111", "schedule_date": "2026-11-13T15:00:00", "description": "description_root", "transactions": [ { "type": "account", "account": { "email": "test_user_2471579826595803489@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "description": "description_transaction", "external_reference": "test_mp-mp-webhook_schedule" } ] }'
- Transferências para outros bancos a partir do Mercado Pago:
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: false' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "global_111", "description": "description_root", "transactions": [ { "type": "account", "account": { "holder": "test user", "number": "0000003100025957669623", "bank_id": "015", "owner_value": "95871050", "owner_type": "DNI" }, "amount": { "currency": "ARS", "value": 123 }, "external_reference": "test_mp-bank-mla", "description": "description_transaction" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
X-Idempotency-Key | Header. Esta função permite repetir solicitações de forma segura, sem o risco de realizar a mesma ação mais de uma vez por engano. Isso é útil para evitar erros, como a criação de dois transações idênticas, por exemplo. Para garantir que cada solicitação seja única, é importante usar um valor exclusivo no header da sua solicitação. Sugerimos o uso de um UUID V4 ou strings randômicas. É importante salientar que, a partir de 01/01/24, o envio deste parâmetro passará a ser obrigatório em todas as requisições. | Obrigatório | 0d5020ed-1af6-469c-ae06-c3bec19954bb |
X-signature | Header. Assinatura da requisição com o body criptografado na base 64 com as chaves pública e privada do integrador. | Obrigatório apenas no ambiente de produção. | - |
X-Enforce-Signature | Header. Booleano para indicar se o integrador irá ou não enviar a assinatura. Deve ser false para ambiente de teste ou true para ambiente produtivo, que é quando é obrigatório o envio da assinatura. | Obrigatório apenas no ambiente de produção. | false |
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 que permita o rastreamento da saída de dinheiro, desde que não possua caracteres especiais ("", [ ], (), @) e não exceda 7 caracteres. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_), e não pode ser duplicada. | Obrigatório | MP0001 |
description | Body. Texto curto de descrição da operação do payout completo, com todas as transferências enviadas. Limite de 100 caracteres contabilizando o espaço entre as palavras. | Opcional | "Payout for seller commissions" |
transactions.type | Body. Tipo de conta de destino. O único valor possível é account (contas bancárias). | Obrigatório | account |
transactions.description | Body. Texto curto de descrição da operação. | Opcional | "Payment to seller Beltrano" |
transactions.account | Body. Detalhes da conta de destino, que pode ser um e-mail para transferências entre contas Mercado Pago ou detalhes de uma conta bancária (titular, account_number e bank_id) para transferências a bancos externos. | Obrigatório e preencher de acordo com o modelo de transferência. | - |
transactions.account.email | Body. Endereço de e-mail associado à conta Mercado Pago. Este campo é obrigatório e exclusivo para transferências entre contas Mercado Pago. Quando este campo é utilizado, não é necessário fornecer os campos holder, number, bank_id, owner_value e owner_type. Há um limite de até 100 transações com e-mail por payout. | Obrigatório quando o modelo de transferência é entre contas Mercado Pago. | test_user_ar@testuser.com |
transactions.account.holder | Body. Nome e sobrenome do titular da conta de destino. Obrigatório para transferências para contas fora do Mercado Pago. | Obrigatório quando o modelo de transferência é entre contas Mercado Pago para fora. | María González |
transactions.account.account_number | Body. Número único que representa cada conta bancária. Neste caso, você deve enviar o número único da conta de destino. | Obrigatório | 0000003100025957669623 |
transactions.account.bank_id | Body. Número identificador do banco ao qual pertence a conta corrente de destino. O valor padrão é de 3 dígitos. | Obrigatório | 015 |
transactions.account.owner_value | Body. Número de identificação do titular da conta corrente de destino. Obrigatório para transferências para contas fora do Mercado Pago. | Obrigatório | 95871050 |
transactions.account.owner_type | Body. Tipo de documento de identificação. | Obrigatório | DNI |
transactions.amount | Body. Valor da transação, que será retirado da conta. | Obrigatório | - |
transactions.amount.currency | Body. Identificador da moeda utilizada na transação. | Obrigatório | ARS |
transactions.amount.value | Body. Valor da transação que será debitado da conta corrente de origem. O valor mínimo é 0 e o máximo é 10000000000. | Obrigatório | 100 |
transactions.external_reference | Body. Referência para identificar a transação. É gerada pelo integrador e pode ser qualquer valor que permita o rastreamento da transação, 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 | tx_ext_ref_123 |
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.
pending, você deve executar a chamada para Obter lista de transações ou Obter informações sobre uma transação para verificar a sua atualização.json
{ "id": "23917", "idempotency_key": "1764622137", "created_date": "2025-12-01T15:48:57.581+00:00", "status": "created", "schedule_date": "2026-11-13T15:00:00", "description": "description_root", "config": { "notification_url": "https://your-webhook-endpoint.com/notifications" } }
Você pode obter informações sobre todas as transações de um payout. Isso pode ser útil para confirmar que estas foram criadas corretamente, consultando seu status ou verificando 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/payouts/{id}/transactionsAPI, substituindo id pelo ID do payout obtido na resposta ao criar o lote.
curl
curl --location 'https://api.mercadopago.com/v1/payouts/9290/transactions?limit=100&offset=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Test-Token: true'
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json
{ "paging": { "limit": 100, "offset": 0, "total": 1 }, "transactions": [ { "id": "676739", "created_date": "2025-08-25T13:04:31.000+00:00", "last_update_date": "2025-08-25T13:04:33.000+00:00", "external_reference": "test_mp-mp-mla", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 1000 } } ] }
| Atributo | Descrição |
paging.limit | Número máximo de transações retornadas de acordo com o valor definido no parâmetro limit da requisição. |
paging.offset | Número de transações retornadas de acordo com o valor definido no parâmetro offset da requisição. |
paging.total | Número total de transações realizadas no payout. |
id | Identificador único da transação, gerado automaticamente. |
created_date | Data de criação da transação. |
last_update_date | Data de atualização do status da transação. |
external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
status | Status atual da transação. |
status_detail | Informação detalhada do status da transação. |
amount.currency | Identificador da moeda utilizada na transação. |
amount.value | Valor da transação que será debitado da conta corrente de origem. O valor mínimo é 0 e o máximo é 10000000000. |
Você também poderá obter informações sobre uma transação específica dentro de um payout. Isso pode ser útil para confirmar que esta foi criada corretamente, consultando seu status ou verificando 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/payouts/{payout_id}/transactions/{transaction_id}API, substituindo payout_id pelo ID do payout e transaction_id pelo ID da transação obtidos previamente.
curl
curl --location 'https://api.mercadopago.com/v1/payouts/9290/transactions/676739' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Test-Token: true'
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json
{ "id": "676739", "created_date": "2025-08-25T13:04:31.000+00:00", "last_update_date": "2025-08-25T13:04:33.000+00:00", "external_reference": "test_mp-mp-mla", "status": "success", "status_detail": "accredited", "type": "mp-user", "amount": { "currency": "ARS", "value": 1000 } }
| Atributo | Descrição |
id | Identificador único da transação, gerado automaticamente. |
created_date | Data de criação da transação. |
last_update_date | Data de atualização do status da transação. |
external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
status | Status atual da transação. |
status_detail | Informação detalhada do status da transação. |
amount.currency | Identificador da moeda utilizada na transação. |
amount.value | Valor da transação que será debitado da conta corrente de origem. O valor mínimo é 0 e o máximo é 10000000000. |
Você também poderá programar uma transferência utilizando o recurso de Scheduler, em que se automatiza a execução dos transferências programadas, garantindo que cada transferência ocorra exatamente na data e hora definidas, de forma segura e sem duplicações, registrando todos os passos para facilitar o acompanhamento e a auditoria.
Para programar uma transferência, envie 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/payoutsAPI incluindo o campo schedule_date no body.
curl
curl --location 'https://api.mercadopago.com/v1/payouts' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Enforce-Signature: false' \ --header 'X-Test-Token: true' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "global_111", "config": { "notification_url": "https://your-webhook-endpoint.com/notifications" }, "schedule_date":"2025-11-28T00:00:00", "transactions": [ { "type": "account", "account": { "holder": "test user", "number": "0000003100025957669623", "bank_id": "015", "owner_value": "95871050", "owner_type": "DNI" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "test_mp-bank-mla" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
schedule_date | Body. Data agendada para execução do payout. O valor deve estar no futuro e no formato padrão ISO 8601 ("YYYY-MM-DDTHH:MM:SS" ou "YYYY-MM-DDTHH:MM:SS.000±HH:MM" para timezones específicos). | Opcional | 2025-12-25T10:00:00 ou 2026-12-31T09:37:52.000-04:00 |
status for pending, deve-se executar a requisição para Obter informações sobre uma transação para verificar sua atualização.Você poderá cancelar uma transação agendada utilizando o ID de referência obtido na resposta à sua criação. O cancelamento destina-se a permitir a interrupção de operações de transferências incorretas ou indesejadas antes da conclusão financeira, sendo irreversível visando preservar a integridade operacional e garantir o rastreamento completo para auditoria.
pending e in_process) podem ser canceladas. Além disso, cancelamento só pode ser feito se houver um agendamento prévio. Ou seja, não é possível cancelar transações que não tenham sido agendadas.Para cancelar uma transação, envie um PUT 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/payouts/{payout_id}/transactions/{transaction_id}/cancelAPI, substituindo payout_id pelo ID do payout e transaction_id pelo ID da transação.
curl
curl --location --request PUT 'https://api.mercadopago.com/v1/payouts/123456/transactions/67890/cancel' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Test-Token: true' \ --header 'X-Enforce-Signature: false' \ --data '{ "comments": "delete because the payment was canceled", "deleted_by": "user_123" }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
X-Enforce-Signature | Header. Booleano para indicar se o integrador irá ou não enviar a assinatura. Deve ser false para ambiente de teste e true para ambiente produtivo. | Obrigatório | false |
X-signature | Header. Assinatura da requisição com o body criptografado na base 64 com as chaves pública e privada do integrador. É obrigatório apenas no ambiente de produção. | Obrigatório apenas no ambiente de produção | - |
X-Test-Token | Header. Booleano para indicar se a requisição será de teste ou não. Sempre obrigatório como true quando se trata de uma requisição de teste. Quando o Access Token não começa com TEST, este header deve ser usado para que a chamada 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 trata de uma requisição de teste | true |
comments | Body. String. Justificativa clara e objetiva para o cancelamento (evitar incluir informações pessoais sensíveis). Este campo é fundamental para histórico e auditoria. | Obrigatório | "delete because the payment was canceled" |
deleted_by | Body. String. Identificação única de quem realizou o cancelamento (usuário, sistema, etc). Este campo é fundamental para histórico e auditoria. | Obrigatório | user_123 |
payout_id | Path. String. Identificador do payout que deseja consultar a transação, retornado na resposta à sua criação dentro do campo id. | Obrigatório | 123456 |
transaction_id | Path. String. Identificador da transação que deseja consultar, retornado na resposta à sua criação dentro do campo id. | Obrigatório | 67890 |
Se a execução for bem-sucedida, você receberá como resposta um status code 204, indicando que a transação foi cancelada.