Recursos para IA

Testar a integração

Antes de ir para produção, recomendamos testar o funcionamento da integração e o processamento das transações. Assim, você pode verificar se a integração foi configurada corretamente e se as transações são processadas sem erros.

Se desejar, antes de testar sua integração você pode criptografar seus dados para realizar suas transações de teste. Para saber como criar essa criptografia, acesse Criptografia de segurança. Lembre-se de que essa criptografia é necessária apenas ao colocar sua integração em produção, ou seja, para suas transações reais.

Para testar sua integração com o Payouts, crie transações enviando uma solicitação com o 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. e o header X-test-token: true, para o endpoint /v1/payoutsPOST, para que a requisição seja feita em um ambiente de teste.

Para testar a criação e o processamento de um payout via Pix, envie uma ou várias transações para contas de destino no ambiente de teste.

A chave Pix usada no teste deve estar cadastrada para a conta de destino e seu formato deve corresponder ao tipo informado em transactions.pix.type.

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": "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"
    }
  ]
}'

Para saber 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 nossa lista 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": "BRL",
        "value": 11
      },
      "external_reference": "transaction_external_reference_01"
    },
    {
      "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M",
      "amount": {
        "currency": "BRL",
        "value": 12
      },
      "external_reference": "transaction_external_reference_02"
    }
  ]
}

O processamento das transações pode levar alguns minutos. Se uma transação estiver com status=pending, envia uma solicitação ao endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET para verificar as atualizações.

Pronto! Concluída esta etapa, a integração está completa e você pode subir em produção.

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

PróximoSubir em produçãoConheça as recomendações para colocar, de maneira eficaz e segura, a sua integração com o Payouts em produção.