Como testar um gateway de pagamento no sandbox da AbacatePay

Integrar um gateway e só descobrir o bug quando o cliente paga de verdade é o tipo de susto que dá pra evitar.

Sandbox existe pra isso. Na AbacatePay o nome é Dev mode: você cria cobrança, simula o Pix, recebe webhook e trata erro, sem mover um centavo. Quando o fluxo fecha, a ida pra produção é trocar a chave de API. A URL não muda.

A documentação completa está em Dev mode. Este texto é o mapa prático.

Por que testar o gateway

Pagamento não é um POST que devolve 200 e acabou. O cliente gera o QR, fecha a aba, o Pix cai dois segundos depois, o webhook chega duas vezes, o seu servidor estava fora. Se você só testou o “caminho feliz” no Postman, produção vai te ensinar o resto.

No sandbox você valida:

• Cobrança criada com success: true
• Pagamento confirmado (status PAID)
• Seu sistema liberando o produto / marcando o pedido
• Webhook assinado e idempotente (o mesmo evento duas vezes não duplica entrega)
• Erro 401, 403 e 4xx com mensagem clara pra você, não pra tela do cliente

Sem isso, o primeiro Pix real vira debug com dinheiro no meio. O desenho de produção (QR dinâmico, txid, webhook e idempotência) está em como confirmar um Pix automaticamente.

Como o sandbox da AbacatePay funciona

Não existe uma URL secreta de teste. Todas as chamadas vão para:

https://api.abacatepay.com/v2

O ambiente vem da chave:

Na resposta da API, o campo devMode: true confirma que você está no sandbox. No dashboard, a chave de Dev também tem indicador visual.

A conta nova já entra em Dev mode. Dá pra integrar inteiro antes de enviar documento. Produção é o passo seguinte: verificar a conta e gerar uma chave prod_.

Passo a passo no sandbox

1. Crie a chave de Dev

No dashboard, abra Integração → API Keys e crie uma chave em Dev mode.

Dê um nome óbvio (sandbox-local, ci). Marque as permissões que o fluxo usa. Para simular Pix no checkout transparente você precisa de CHECKOUT:READ.

Copie a chave na hora: ela só aparece uma vez. Guarde em variável de ambiente. Nunca no Git, nunca no frontend, nunca no app mobile.

Authorization: Bearer SUA_CHAVE_DEV

Espaço depois de Bearer. Sem aspas extras. Chave errada ou revogada devolve 401. Chave certa sem permissão devolve 403.

2. Crie uma cobrança de teste

Valores são inteiros em centavos. 1000 é R$ 10,00. Não manda 10.00.

Exemplo de Pix transparente:

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer $ABACATE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "method": "PIX"
  }'

A resposta traz o QR (brCode, brCodeBase64) e um id. Guarde o id. É ele que você vai “pagar” no passo seguinte. Fluxo completo de criação (cURL e Node): como gerar QR Code Pix via API.

Confira devMode: true. Se estiver false, você não está no sandbox.

3. Simule o Pix

Não precisa abrir o banco. No Dev mode existe um endpoint só pra isso:

curl -X POST "https://api.abacatepay.com/v2/transparents/simulate-payment?id=ID_DA_COBRANCA" \
  -H "Authorization: Bearer $ABACATE_API_KEY"

Só funciona com chave de Dev. Em produção esse endpoint erra de propósito.

O status deve ir para PAID. Aí você confere se o seu sistema reagiu: polling em /transparents/check ou, melhor, webhook.

4. Escute o webhook

Não dependa só de ficar consultando a API. Configure um endpoint HTTPS que receba transparent.completed (e o evento que o seu fluxo usa).

No localhost, exponha com um túnel (ngrok, Cloudflared) e cadastre essa URL no sandbox. Webhook de Dev não recebe evento de produção. Quando for ao vivo, crie o webhook de novo com a chave prod_.

Três regras que evitam a maior parte dos incidentes:

• Valide a assinatura HMAC com o secret que você cadastrou
• Grave o ID do evento e ignore duplicata
• Responda 2xx rápido; o trabalho pesado vai pra fila

5. Quebre de propósito

O caminho feliz não basta. No sandbox, force:

• Header sem Bearer → 401
• Chave de Dev sem a permissão certa → 403
• amount em reais em vez de centavos → valor absurdo ou erro
• simulate-payment com ID inexistente
• Webhook caindo com o mesmo evento duas vezes

Se a sua UI e o seu backend sobrevivem a isso, produção fica chato, do jeito certo.

Checklist antes de trocar a chave

A própria docs tem essa lista. Em resumo:

• Autenticação ok com chave dev_
• Cobrança cria com success: true
• Pix simulado via /transparents/simulate-payment
• Webhook recebe e processa o evento (sem duplicar)
• Erros 4xx e 5xx tratados (5xx com retry e backoff)
• Chave só em variável de ambiente

Aí sim: verifica a conta, gera chave prod_, recria o webhook, faz um Pix real de valor baixo. Código igual. Só a chave muda. Detalhe do go-live: indo para produção.

Crie a cobrança, simule o Pix, confira o webhook e só então processe um pagamento real.

Conta e chave de Dev: app.abacatepay.com. Referência: docs.abacatepay.com/pages/devmode.