Recursos para IA
Configurar transferências de dinheiro
A integração de Payouts é realizada executando uma única chamada à API /v1/payouts para configurar transações únicas (para uma única conta de destino) ou múltiplas (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.
As contas de destino devem ser contas correntes, ou seja, não é possível transferir para uma conta poupança.
Veja abaixo como integrar Payouts para realizar as transações e também como obter informações sobre elas, programá-las e, caso necessário, cancelá-las.
Para configurar transações com destino a contas bancárias ou entre contas Mercado Pago, você deve 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/payoutsAPI. Você deverá enviar os parâmetros correspondentes seguindo os respectivos cURLs de exemplo e as indicações nas tabelas que estão abaixo.
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: true' \ --header 'X-signature: true' \ --data-raw '{ "external_reference": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T14:30:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
Authorization | Header. Faz referência à sua chave privada, o 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.. | Obrigatório | - |
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. | true |
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 |
config | Body. Objeto contendo configurações do usuário que realiza a transação. | Opcional | - |
config.notification_url | Body. URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. | Opcional | https://link-your-webhook-notification.com |
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" |
schedule_date | Body. Data de execução do payout. O valor deve estar no futuro e no formato padrão ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"), sem fuso horário. O fuso horário é inferido automaticamente com base no país da requisição. Veja mais informações em Programar transações | Opcional | 2026-12-31T14:30:00 |
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. E-mail da conta Mercado Pago de destino. | Obrigatório para transferências entre contas Mercado Pago. | test_user_mx@testuser.com |
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 | MXN |
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 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 | 000156 |
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 requisição, consulte nossos possíveis de erros para mais informações.
Se a execução for bem-sucedida, você receberá como resposta um status code 202, indicando que a transação foi aceita, como no exemplo a seguir.
json
{ "id": "POP01KM145R903TZ06BWK6204DGG1", "external_reference": "000197", "description": "Payout for seller commissions", "idempotency_key": "1773859430", "created_date": "2026-03-18T14:43:50-04:00", "status": "created", "schedule_date": "2026-12-31T14:30:00", "config": { "notification_url": "https://link-your-webhook-notification.com" } }
| Atributo | Descrição |
id | Identificador único da transação, gerado automaticamente. |
external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
description | Texto de descrição da operação do payout completo, com todas as transferências enviadas. |
idempotency_key | Chave de idempotência para evitar duplicatas. |
created_date | Data de criação da transação. |
status | Status atual da transação. |
schedule_date | Data de execução do payout. O valor estará no futuro e no formato padrão ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"). |
config.notification_url | URL em que receberão as notificações de eventos relacionados à transação, como as mudanças de status. |
Tenha em mente que esta resposta pode demorar alguns minutos e que, caso seu status seja
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.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/{{payout_id}}/transactions?limit=10&offset=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Campo | Descrição | Obrigatoriedade | Exemplo |
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 | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
limit | Query. Número máximo de transações a serem retornadas na lista. Limite de 100 transações. | Opcional | 10 |
offset | Query. Número de transações a serem omitidas da lista. | Opcional | 0 |
Authorization | Header. Faz referência à sua chave privada, o 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.. | Obrigatório | - |
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. | true |
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 requisição, consulte nossos possíveis de erros para mais informações.
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": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "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. |
transactions.id | Identificador único da transação, gerado automaticamente. |
transactions.created_date | Data de criação da transação. |
transactions.last_update_date | Data de atualização do status da transação. |
transactions.external_reference | Referência externa da transação, gerada pelo integrador na hora da criação. |
transactions.status | Status atual da transação. |
transactions.status_detail | Informação detalhada do status da transação. |
transactions.type | Tipo de transação. O valor sempre será "TRANSACTION" para as transferências bancárias via Payouts. |
transactions.amount.currency | Identificador da moeda utilizada na transação. |
transactions.amount.value | Valor da transação que será debitado da conta corrente de origem. O valor mínimo é 0 e o máximo é 10000000000. |
Para mais informações sobre os status retornados, acesse Status de uma transação.
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/{{payout_id}}/transactions/{{transaction_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-test-token: true'
| Campo | Descrição | Obrigatoriedade | Exemplo |
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 | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
transaction_id | Path. String. Identificador da transação que deseja consultar, retornado na resposta à sua criação dentro do campo id. | Obrigatório | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Faz referência à sua chave privada, o 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.. | Obrigatório | - |
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. | true |
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 requisição, consulte nossos possíveis de erros para mais informações.
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json
{ "id": "TOP01KKYN1QY2SS1MKAY4G9DV5NK9", "created_date": "2026-03-17T15:41:03.632-04:00", "last_update_date": "2026-03-23T17:18:29.665-04:00", "external_reference": "000197", "status": "success", "status_detail": "accredited", "type": "TRANSACTION", "amount": { "currency": "MXN", "value": 1000 } }
Para mais informações sobre os status retornados, acesse Status de uma transação.
| 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. |
type | Tipo de transação. O valor sempre será "TRANSACTION" para as transferências bancárias via Payouts. |
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 das 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.
É importante que as transações sejam agendadas para uma data/hora futura, fora de finais de semana ou feriados e que, além de se garantir que haja saldo disponível na data/hora definidas, a transação esteja alinhada com as janelas operativas da instituição financeira.
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 'Content-Type: application/json' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ --header 'X-enforce-signature: false' \ --header 'X-test-token: true' \ --header 'X-signature: true' \ --data-raw '{ "external_reference": "000197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "schedule_date": "2026-12-31T14:30:00", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test_user_mx@testuser.com" }, "amount": { "currency": "MXN", "value": 1 }, "external_reference": "000197" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
Authorization | Header. Faz referência à sua chave privada, o 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.. | Obrigatório | - |
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. | true |
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 |
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" |
schedule_date | Body. Data de execução do payout. O valor deve estar no futuro e no formato padrão ISO 8601 UTC-0 ("YYYY-MM-DDTHH:MM:SS"), sem fuso horário. O fuso horário é inferido automaticamente com base no país da requisição. | Opcional | 2026-12-31T14:30:00 |
config | Body. Objeto contendo configurações do usuário que realiza a transação. | Opcional | - |
config.notification_url | Body. URL onde receberá as notificações de eventos relacionados à transação, como mudanças de status. | Opcional | https://link-your-webhook-notification.com |
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. E-mail da conta Mercado Pago de destino. | Obrigatório para transferências entre contas Mercado Pago. | test_user_mx@testuser.com |
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 | MXN |
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 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 | 000156 |
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 requisição, consulte nossos possíveis de erros para mais informações.
Se a execução for bem-sucedida, você receberá como resposta um status code 202, indicando que a transação foi aceita.
Tenha em mente que esta resposta pode demorar alguns minutos e que, caso seu status seja
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.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.
Apenas transações que ainda não foram processadas (
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/{{payout_id}}/transactions/{{transaction_id}}/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 |
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 | POP01KKCFKH9J2C8TQSQZM4R3Z22C |
transaction_id | Path. String. Identificador da transação que deseja consultar, retornado na resposta à sua criação dentro do campo id. | Obrigatório | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Faz referência à sua chave privada, o 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.. | Obrigatório | - |
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 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. | 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 |
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 requisição, consulte nossos possíveis de erros para mais informações.
Se a execução for bem-sucedida, você receberá como resposta um status code 204, indicando que a transação foi cancelada.
Sempre revise o estado atual da transação antes de tentar cancelá-la novamente. Acesse Obter informações sobre uma transação para verificar sua atualização.