Recursos para IA
Configurar transferências de dinheiro
A integração de Payouts utiliza uma única chamada à API /v1/payoutsPOST para criar um lote de transações com uma ou várias transferências bancárias para uma ou várias contas de destino. Esse lote de transações (payout) é criado em uma única requisição, e cada transação do lote é processada de forma independente.
As contas de destino devem ser contas correntes, ou seja, não é possível transferir para uma conta poupança.
Veja a seguir como integrar o Payouts para realizar transações, obter informações sobre elas, programá-las e, se necessário, cancelá-las.
Crie um lote (payout) com uma ou várias transações de saída de dinheiro de uma conta Mercado Pago para um ou vários destinatários, sejam eles de outras contas Mercado Pago ou contas externas. O payout pode conter até 1000 transações, criadas e processadas em uma única requisição, desde que a conta de origem tenha saldo disponível.
Para isso, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payoutsPOST. Você deverá enviar os parâmetros correspondentes seguindo os respectivos cURLs de exemplo e os campos indicados nas tabelas que estão nas abas abaixo, de acordo com o tipo de transação desejado.
Para executar o lote em uma data futura, você pode programar as transações usando o campo
schedule_date. Para mais informações, consulte Programar transações.Para criar um lote de transações entre contas Mercado Pago, informe o e-mail associado à conta de cada destinatário e os dados das transferências que farão parte do payout.
curlcurl --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": "MP0197", "config": { "notification_url": "https://link-your-webhook-notification.com" }, "description": "Payout for seller commissions", "transactions": [ { "type": "account", "description": "Payment to seller Beltrano", "account": { "email": "test@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "MP0197" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
Authorization | Header. Faz referência à sua chave privada, o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 que permita o rastreamento da transação, desde que não possua caracteres especiais ("", [ ], (), @), não exceda 50 caracteres e não seja duplicada. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_). | Obrigatório | MP0197 |
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. Para mais informações, acesse Configurar notificações. | 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. Use apenas letras, números, hífens (-), underlines (_) e espaços, sem pontuação. | Opcional | Payout for seller commissions |
transactions.type | Body. Tipo de transação. O único valor possível é account (conta corrente). | Obrigatório | account |
transactions.description | Body. Descrição breve da transação individual. Use apenas letras, números, hífens (-), underlines (_) e espaços, sem pontuação. | Opcional | Payment to seller Beltrano |
transactions.account | Body. Detalhes da conta de destino quando transactions.type for account. Para esse modelo de transferência, informe o e-mail da conta Mercado Pago de destino. | Obrigatório quando transactions.type=account e deve ser preenchido de acordo com o modelo de transferência. | - |
transactions.account.email | Body. E-mail da conta Mercado Pago de destino. | Obrigatório quando o modelo de transferência é entre contas Mercado Pago. | test@testuser.com |
transactions.amount | Body. Valor da transação. | Obrigatório | - |
transactions.amount.currency | Body. Identificador da moeda utilizada na transação. | Obrigatório | ARS |
transactions.amount.value | Body. Valor da transação a ser debitado da conta corrente de origem. O valor mínimo é 1 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 50 caracteres. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_), e não pode ser duplicada. | Opcional | MP0197 |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. 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, a requisição retorna um status code 202, indicando que o payout foi aceito para processamento. O exemplo a seguir mostra um payout com duas transações:
json{ "id": "POP01KV681P6SJ38NQHWX3XK162SS", "external_reference": "payout_external_reference", "description": "description_root", "idempotency_key": "021957ca-7271-4f5e-8b8d-70ed87ce1a61", "created_date": "2026-06-15T14:17:36-03:00", "status": "created", "config": { "notification_url": "https://notification_url.com" }, "transactions": [ { "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "amount": { "currency": "ARS", "value": 11 }, "external_reference": "transaction_external_reference_01" }, { "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M", "amount": { "currency": "ARS", "value": 12 }, "external_reference": "transaction_external_reference_02" } ] }
| Atributo | Descrição |
id | Identificador único do payout, gerado automaticamente. |
external_reference | Referência externa do payout, gerada pelo integrador ao criá-lo. |
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 do payout. |
status | Status atual do payout. |
config.notification_url | URL em que serão recebidas as notificações de eventos relacionados ao payout e às suas transações, como mudanças de status. |
transactions.id | Identificador único da transação, gerado automaticamente. |
transactions.amount.currency | Identificador da moeda utilizada na transação. |
transactions.amount.value | Valor da transação. |
transactions.external_reference | Referência externa da transação, gerada pelo integrador no momento da criação. |
O código de status
202 confirma que o payout foi aceito para processamento, mas não que todas as transações foram validadas. A validação de formato e tamanho de transactions.external_reference ocorre de forma assíncrona: se o campo estiver inválido, a transação será marcada com erro durante o processamento. Consulte o status da transação para identificar o erro.Tenha em mente que esta resposta pode demorar alguns minutos e que, caso seu status seja
pending, você poderá utilizar as requisições descritas abaixo para obter mais informações sobre um lote ou sobre uma transação específica.Consulte o status e o resumo consolidado de um lote de transações (payout). Use este endpoint para verificar quantas transações foram concluídas com sucesso, quantas estão pendentes ou apresentaram erro.
Para obter uma lista completa com todas as transações de um lote ou obter informações sobre uma única transação, veja Obter lista de transações e Obter informações sobre uma transação, respectivamente.
Para isso, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payouts/{payout_id}GET, eviando o ID do payout (payout_id) obtido na resposta ao criar o lote.
curlcurl --location 'https://api.mercadopago.com/v1/payouts/{payout_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, retornado na resposta à sua criação dentro do campo id. | Obrigatório | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
Authorization | Header. Faz referência à sua chave privada, o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 |
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json{ "id": "POP01KV681P6SJ38NQHWX3XK162SS", "status": "completed", "external_reference": "payout_external_reference", "config": { "notification_url": "https://notification_url.com" }, "summary": { "pending": { "items": 0 }, "canceled": { "items": 0 }, "success": { "items": 0 }, "error": { "items": 2 } } }
| Atributo | Descrição |
id | Identificador único do payout, gerado automaticamente. |
status | Status atual do payout. |
external_reference | Referência externa do payout, gerada pelo integrador na hora da criação. |
config.notification_url | URL em que receberá as notificações de eventos relacionados ao payout, como as mudanças de status. Para mais informações, acesse Configurar notificações. |
summary.pending.items | Quantidade de transações pendentes. |
summary.canceled.items | Quantidade de transações canceladas. |
summary.success.items | Quantidade de transações concluídas com sucesso. |
summary.error.items | Quantidade de transações com erro. |
Para ver em detalhes todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. Caso receba um erro ao enviar a requisição, consulte os possíveis erros para mais informações.
Obtenha informações sobre todas as transações de um lote, podendo confirmar que estas foram criadas corretamente, consultando seu status ou verificando as informações recebidas em suas notificações.
Para consultar uma única transação ao invés da lista completa, veja Obter informações sobre uma transação.
Para isso, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payouts/{payout_id}/transactionsGET, substituindo payout_id pelo ID do payout obtido na resposta ao criar o lote.
curlcurl --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 vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 |
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json{ "external_reference": "payout_external_reference", "config": { "notification_url": "https://notification_url.com" }, "paging": { "limit": 50, "offset": 0, "total": 2 }, "transactions": [ { "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_02", "description": "description_transaction_02", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 12 } }, { "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_01", "description": "description_transaction_01", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 11 } } ] }
Para mais informações sobre os status retornados, acesse Status da transação.
| Atributo | Descrição |
external_reference | Referência externa do payout, gerada pelo integrador na hora da criação. |
config.notification_url | URL em que receberá as notificações de eventos relacionados ao payout, como as mudanças de status. Para mais informações, acesse Configurar notificações. |
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.amount.currency | Identificador da moeda utilizada na transação. |
transactions.amount.value | Valor da transação. |
Para ver em detalhes todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. Caso receba um erro ao enviar a requisição, consulte os possíveis erros para mais informações.
Obtenha informações sobre uma transação específica dentro de um lote, podendo confirmar que esta foi criada corretamente, consultando seu status ou verificando as informações recebidas em suas notificações.
Para obter informações sobre um lote de transações completo, veja Obter informações sobre um lote.
Para isso, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET, substituindo payout_id pelo ID do payout e transaction_id pelo ID da transação obtidos previamente.
curlcurl --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 no campo transactions[].id da resposta de criação do payout. | Obrigatório | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Faz referência à sua chave privada, o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 |
Se os dados enviados na chamada estiverem corretos, você receberá uma resposta como a seguinte:
json{ "id": "TOP01KV681P6SJ38NQHWX3SF2WM22", "created_date": "2026-06-15T14:17:38.606-03:00", "last_update_date": "2026-06-15T14:17:38.606-03:00", "external_reference": "transaction_external_reference_01", "description": "description_transaction_01", "status": "success", "status_detail": "accredited", "amount": { "currency": "ARS", "value": 11 } }
Para mais informações sobre os status retornados, acesse Status da 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. |
amount.currency | Identificador da moeda utilizada na transação. |
amount.value | Valor da transação. |
Para ver em detalhes todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. Caso receba um erro ao enviar a requisição, consulte os possíveis erros para mais informações.
Programe transferências utilizando o Scheduler, um recurso em que se automatiza a execução das transações 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 transferências, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payoutsPOST incluindo o campo schedule_date no body e os outros campos indicados nas tabelas que estão nas abas abaixo, de acordo com o tipo de transação desejado.
Para programar transferências entre contas Mercado Pago, informe em schedule_date a data e a hora de execução do payout, além do e-mail associado à conta de cada destinatário.
curlcurl --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": "MP0197", "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@testuser.com" }, "amount": { "currency": "ARS", "value": 10 }, "external_reference": "MP0197" } ] }'
| Campo | Descrição | Obrigatoriedade | Exemplo |
Authorization | Header. Faz referência à sua chave privada, o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 que permita o rastreamento da transação, desde que não possua caracteres especiais ("", [ ], (), @), não exceda 50 caracteres e não seja duplicada. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_). | Obrigatório | MP0197 |
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. Para mais informações, acesse Configurar notificações. | Opcional | https://link-your-webhook-notification.com |
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 hirá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 |
description | Body. Texto curto de descrição da operação do payout completo, com todas as transferências enviadas. Use apenas letras, números, hífens (-), underlines (_) e espaços, sem pontuação. | Opcional | Payout for seller commissions |
transactions.type | Body. Tipo de transação. O único valor possível é account (conta corrente). | Obrigatório | account |
transactions.description | Body. Descrição breve da transação individual. Use apenas letras, números, hífens (-), underlines (_) e espaços, sem pontuação. | Opcional | Payment to seller Beltrano |
transactions.account | Body. Detalhes da conta de destino quando transactions.type for account. Para esse modelo de transferência, informe o e-mail da conta Mercado Pago de destino. | Obrigatório quando transactions.type=account e deve ser preenchido de acordo com o modelo de transferência. | - |
transactions.account.email | Body. E-mail da conta Mercado Pago de destino. | Obrigatório quando o modelo de transferência é entre contas Mercado Pago. | test@testuser.com |
transactions.amount | Body. Valor da transação. | Obrigatório | - |
transactions.amount.currency | Body. Identificador da moeda utilizada na transação. | Obrigatório | ARS |
transactions.amount.value | Body. Valor da transação a ser debitado da conta corrente de origem. O valor mínimo é 1 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 50 caracteres. São permitidos números (1234), letras (abcde), hífens (-) e underlines (_), e não pode ser duplicada. | Opcional | MP0197 |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. 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, a requisição retorna um status code 202, indicando que o payout foi aceito para processamento.
O código de status
202 confirma que o payout foi aceito para processamento, mas não que todas as transações foram validadas. A validação de formato e tamanho de transactions.external_reference ocorre de forma assíncrona: se o campo estiver inválido, a transação será marcada com erro durante o processamento. Consulte o status da transação para identificar o erro.Tenha em mente que esta resposta pode demorar alguns minutos e que, caso seu status seja
pending, você poderá utilizar as requisições descritas acima para obter mais informações sobre um lote ou sobre uma transação específica.Cancele uma transação programada para interromper uma operação de transferência incorreta ou indesejada antes da liquidação financeira. Este procedimento é irreversível, preservando a integridade operacional e a rastreabilidade para auditoria.
Apenas transações programadas, que ainda não foram processadas e estejam com
status=pending ou status=in_process, podem ser canceladas.Envie o cancelamento com, no mínimo, 12 horas de antecedência em relação à data e hora programadas para execução.
Para cancelar uma transação, envie uma solicitação com seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend. ao endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}/cancelPUT, utilizando o ID do payout (payout_id) e ID da transação (transaction_id).
curlcurl --location --request PUT 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions/{transaction_id}/cancel' \ --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 '{ "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 contém a transação a ser cancelada, retornado na resposta à sua criação dentro do campo id. | Obrigatório | POP01KKYN1QY2SS1MKAY4KP6SSRCT |
transaction_id | Path. String. Identificador da transação que deseja cancelar, retornado no campo transactions[].id da resposta de criação do payout. | Obrigatório | TOP01KKYN1QY2SS1MKAY4E5KM8WZ6 |
Authorization | Header. Faz referência à sua chave privada, o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais e nunca deve ser exposta no frontend.. | 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 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 (evite incluir informações pessoais sensíveis). Este campo auxilia o histórico e a auditoria. | Opcional | delete because the payment was canceled |
deleted_by | Body. String. Identificação única de quem realizou o cancelamento (usuário, sistema etc.). Este campo auxilia o histórico e a auditoria. | Opcional | user_123 |
Para conhecer em detalhe todos os parâmetros enviados e retornados nesta requisição, consulte nossa Referência de APIAPI. 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 confirmar que o cancelamento foi aplicado corretamente.