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 para uma ou várias contas de destino, seja por transferência bancária, seja via Pix. Esse lote de transações (payout) é criado em uma única requisição, e cada transação do lote é processada de forma independente.

É possível fazer transferências para contas correntes e contas poupança. Além disso, para transferências via Pix, o destinatário deve ter uma chave Pix cadastrada disponível para receber as transações.

Veja a seguir como integrar o Payouts para realizar transações, obter informações sobre elas, programá-las e, se necessário, cancelá-las.

Criar um lote de transações

Crie um lote (payout) com uma ou várias transações de saída de dinheiro de uma conta Mercado Pago (via transferência bancária ou via Pix) 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 as indicações 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 via Pix, informe a chave Pix de cada destinatário e os dados das transferências que farão parte do payout.

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 'X-signature: true' \
--header 'Content-Type: application/json' \
--data '{
  "external_reference": "MP0197",
  "config": {
    "notification_url": "https://link-your-webhook-notification.com"
  },
  "description": "Payout for seller commissions",
  "transactions": [
    {
      "description": "Payment to seller Beltrano",
      "type": "pix",
      "pix": {
        "type": "CPF",
        "chave": "111.444.777-35"
      },
      "amount": {
        "currency": "BRL",
        "value": 10
      },
      "external_reference": "MP0197"
    }
  ]
}'

Campo	Descrição	Obrigatório	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. 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.	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.	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`).	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, letras, 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. 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. Use apenas letras, números, hífens (`-`), underlines (`_`) e espaços, sem pontuação.	Opcional	`Payout for seller commissions`
`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.type`	Body. Tipo de transação. Use `account` para transferências entre contas Mercado Pago ou para contas externas (seja conta corrente ou poupança), e `pix` para transferências via Pix.	Obrigatório	`pix`
`transactions.pix`	Body. Detalhes da chave Pix do destinatário. Esta chave deverá estar cadastrada e disponível para receber as transações.	Obrigatório quando `transactions.type=pix`.	-
`transactions.pix.type`	Body. Tipo da chave Pix. Valores possíveis: `EMAIL`, `PHONE`, `CPF`, `CNPJ` ou `PIX_CODE` (chave aleatória, também conhecida como EVP).	Obrigatório quando `transactions.type=pix`.	`CPF`
`transactions.pix.chave`	Body. Valor da chave Pix e com formato correspondente ao tipo definido em `transactions.pix.type`.	Obrigatório quando `transactions.type=pix`.	`111.444.777-35`
`transactions.amount.currency`	Body. Moeda usada na transação.	Obrigatório	`BRL`
`transactions.amount.value`	Body. Valor da transação a ser debitado da conta de origem. Mínimo 1, máximo 10000000000.	Obrigatório	`10`
`transactions.external_reference`	Body. Referência para identificar a transação, gerada pelo integrador. Aceita até 50 caracteres, apenas com letras, números, hífens (`-`) e underlines (`_`).	Opcional	`MP0197`

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.

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": "BRL",
        "value": 11
      },
      "external_reference": "transaction_external_reference_01"
    },
    {
      "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M",
      "amount": {
        "currency": "BRL",
        "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.

Obter informações sobre um lote

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.

curl
curl --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.

Obter lista de transações de um lote

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.

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 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": "BRL",
        "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": "BRL",
        "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.

Obter informações sobre uma transação

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.

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 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:

Se os dados enviados na chamada estiverem corretos, a resposta será parecida com 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": "BRL",
    "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.

Programar transaçõ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 via Pix, informe em schedule_date a data e a hora de execução do payout, além da chave Pix de cada destinatário.

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 'X-signature: true' \
--header 'Content-Type: application/json' \
--data '{
  "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": [
    {
      "description": "Payment to seller Beltrano",
      "type": "pix",
      "pix": {
        "type": "CPF",
        "chave": "111.444.777-35"
      },
      "amount": {
        "currency": "BRL",
        "value": 10
      },
      "external_reference": "MP0197"
    }
  ]
}'

Campo	Descrição	Obrigatório	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. 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.	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.	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`).	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, letras, 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. 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. Use apenas letras, números, hífens (`-`), underlines (`_`) e espaços, sem pontuação.	Opcional	`Payout for seller commissions`
`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.type`	Body. Tipo de transação. Use `account` para transferências entre contas Mercado Pago ou para contas externas (seja conta corrente ou poupança), e `pix` para transferências via Pix.	Obrigatório	`pix`
`transactions.pix`	Body. Detalhes da chave Pix do destinatário. Esta chave deverá estar cadastrada e disponível para receber as transações.	Obrigatório quando `transactions.type=pix`.	-
`transactions.pix.type`	Body. Tipo da chave Pix. Valores possíveis: `EMAIL`, `PHONE`, `CPF`, `CNPJ` ou `PIX_CODE` (chave aleatória, também conhecida como EVP).	Obrigatório quando `transactions.type=pix`.	`CPF`
`transactions.pix.chave`	Body. Valor da chave Pix e com formato correspondente ao tipo definido em `transactions.pix.type`.	Obrigatório quando `transactions.type=pix`.	`111.444.777-35`
`transactions.amount.currency`	Body. Moeda usada na transação.	Obrigatório	`BRL`
`transactions.amount.value`	Body. Valor da transação a ser debitado da conta de origem. Mínimo 1, máximo 10000000000.	Obrigatório	`10`
`transactions.external_reference`	Body. Referência para identificar a transação, gerada pelo integrador. Aceita até 50 caracteres, apenas com letras, números, hífens (`-`) e underlines (`_`).	Opcional	`MP0197`

Se a execução for bem-sucedida, a requisição retorna um status code 202, indicando que o payout foi aceito para processamento.

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.

Cancelar uma transação

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).

curl
curl --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.

AnteriorCriar aplicaçãoVeja como criar uma aplicação e acessar as credenciais necessárias para interagir com nossas APIs ou serviços.

PróximoConfigurar notificaçõesConfigure notificações do Mercado Pago para manter as transferências atualizadas no seu sistema.