API Pix sandbox: como testar sem mover dinheiro

O sandbox da API Pix da xFlow é o modo de teste que você liga só trocando a credencial. Com uma chave pk_test_ e o segredo sk_test_, você chama os mesmos endpoints da API Pix, recebe as mesmas respostas com livemode: false e não move dinheiro real. Para fechar o ciclo, um endpoint próprio, POST /api/v1/test/charges/{id}/pay, simula o pagamento e dispara o webhook transaction.paid.

Como criar a chave de teste

No painel, vá em Chaves de API > Criar chave e escolha o ambiente "Teste". Você recebe a chave pública pk_test_... e o segredo sk_test_.... Como na produção, o segredo aparece uma única vez: guarde antes de fechar a tela.

Um detalhe ajuda quem está começando: a chave de teste pode ser criada antes da aprovação do cadastro. Você integra enquanto a conta está em análise e, quando ela for liberada, só troca a credencial.

A autenticação é a mesma da produção, HTTP Basic com a chave pública como usuário e o segredo como senha:

curl https://app.xflowpayments.com/api/v1/balance -u "pk_test_...:sk_test_..."

O que muda entre teste e produção

O fluxo completo, do pedido ao estorno

1. Crie a cobrança de teste. A rota é a mesma da produção:

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_test_...:sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: teste-pedido-1" \
  -d '{"amountCents":1990,"customer":{"name":"Cliente","email":"c@ex.com","document":"00000000000"}}'

A resposta traz "livemode": false, "status": "pending" e o pix.copyPaste de teste. Não tente pagar esse código num app de banco: ele é só um marcador.

2. Simule o pagamento. Use o id que voltou na criação:

curl -X POST https://app.xflowpayments.com/api/v1/test/charges/{id}/pay \
  -u "pk_test_...:sk_test_..."

A cobrança vira paid, a taxa é calculada com as taxas reais da sua conta e o webhook transaction.paid sai com livemode: false. É um bom momento para conferir se o seu sistema calcula o líquido igual à API.

3. Consulte a cobrança.

curl https://app.xflowpayments.com/api/v1/charges/{id} \
  -u "pk_test_...:sk_test_..."

4. Teste o estorno. Em modo de teste, o estorno conclui na hora, sem provedor, e a cobrança passa a refunded:

curl -X POST https://app.xflowpayments.com/api/v1/charges/{id}/refund \
  -u "pk_test_...:sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"Teste de estorno"}'

Em produção o estorno é assíncrono. Use o teste para validar o código de chamada e o tratamento da resposta, e leia em estorno Pix por API como tratar o 202 pending e os webhooks de produção.

Como testar os webhooks

Os endpoints de webhook podem ser cadastrados pelo painel, em Integrações > Webhooks, ou pela API, com chave de produção ou de teste. Quando você simula um pagamento, o evento chega na sua URL como chegaria em produção, com duas diferenças no data: livemode: false e payer: null.

A regra de ouro é filtrar por livemode antes de dar baixa num pedido real:

const { event, data } = JSON.parse(rawBody);
if (event === "transaction.paid" && !data.livemode) {
  console.log("Pagamento de teste:", data.id);
  return; // nunca libere um pedido real com evento de teste
}

Valide a assinatura x-webhook-signature também no teste. Assim, o mesmo código vai para produção sem surpresa. O passo a passo da validação está em webhook Pix, e um projeto completo em Node.js está em API Pix com Node.js.

O que não funciona em teste

• Split. Enviar splits com chave de teste retorna 400. Valide a divisão em produção, com valores baixos. Veja as regras em split de pagamento.
• Saque. POST /api/v1/transfers com chave de teste retorna 403 test_mode_unsupported. Leia a API de saque Pix antes de liberar saques em produção.
• Saldo. GET /api/v1/balance responde zeros, com livemode: false.
• Pagamento real. O copia e cola de teste não paga, e nenhum provedor é chamado.
• Simular com chave de produção. O endpoint de simulação recusa chave pk_live_ com 403 test_mode_only.

Erros que vale provocar no sandbox

Um bom teste não cobre só o caminho feliz. No modo de teste você provoca os erros mais comuns e confere se o seu sistema reage bem:

Toda resposta de erro traz error, message e request_id. Confira se o seu código registra os três. O request_id é o dado que você informa ao suporte quando precisa de ajuda com uma chamada.

Teste a idempotência antes de ir ao ar

A Idempotency-Key funciona igual no modo de teste, então o sandbox é o lugar certo para provar que o seu retry não duplica cobrança. Faça duas chamadas com a mesma chave e o mesmo corpo: a segunda deve devolver a mesma cobrança. Depois, repita a chave com outro corpo: a resposta deve ser 409 idempotency_conflict. Entenda o conceito em idempotência em API de pagamento.

Checklist para ir para produção

1. Gere a chave de produção (pk_live_ e sk_live_) e troque as variáveis de ambiente. Com a conta ainda em análise, a API de produção responde 403 account_inactive.
2. Remova do código qualquer chamada a /api/v1/test/....
3. Confirme que o seu handler de webhook ignora eventos com livemode: false.
4. Revise o tratamento de 401, 409, 422, 429 e 502.
5. Se usar allowlist de IP, inclua os IPs dos servidores de produção. Fora da lista, a resposta é 401, mesmo com a credencial correta.
6. Guarde o request_id de cada chamada nos seus logs. Ele localiza a requisição em Integrações > Logs da API, com retenção de 30 dias.

Tudo o que você precisa para integrar, de chaves a guias por linguagem, está reunido em Desenvolvedores. A referência do modo de teste fica na documentação.