O modo de teste permite testar todo o ciclo de vida de pagamentos sem processar transações reais. Use chaves pgz_test_* para acessar o sandbox.
Simulações disponíveis
PIX
| Cenário | Endpoint | Descrição |
|---|
| Sucesso | POST /payments/:id/simulate/succeed | Confirma o pagamento |
| Expiração | POST /payments/:id/simulate/expire | Expira o QR Code |
| Falha | POST /payments/:id/simulate/fail | Marca como falho |
Cartão de crédito
Para simular risk analysis em cartão, use um cartão terminando em 9999:
const payment = await pagozz.payments.createCard({
link_id: 'link-id',
payer: { name: 'João', email: 'joao@email.com', cpf: '12345678900' },
card: { number: '4111111111119999', exp_month: 12, exp_year: 2027, cvv: '123' },
});
// Status: AWAITING_RISK_ANALYSIS → simule aprovação
Saque
| Cenário | Endpoint | Descrição |
|---|
| Sucesso | POST /withdrawals/:id/simulate/succeed | Confirma o saque |
| Falha | POST /withdrawals/:id/simulate/fail | Falha e estorna saldo |
Assinaturas (Cycles)
| Cenário | Endpoint | Descrição |
|---|
| Pagar fatura | POST /invoices/:id/simulate/pay | Simula pagamento da fatura |
| Expirar fatura | POST /invoices/:id/simulate/expire | Simula expiração (gera dunning) |
| Avançar período | POST /cycles/:id/simulate/advance | Avança billing period e gera nova fatura |
KYC
No painel (test mode), botões de simulação permitem aprovar ou rejeitar verificação KYC sem passar pelo provedor real.
Exemplo completo
Crie um link
curl -X POST https://api.pagozz.com/v1/links \
-H "Pagozz-Token: pgz_test_XXX" \
-H "Content-Type: application/json" \
-d '{"name": "Teste", "amount": 1000, "value_mode": "fixed", "payment_methods": ["pix"]}'
Crie um pagamento
curl -X POST https://api.pagozz.com/v1/payments/pix \
-H "Pagozz-Token: pgz_test_XXX" \
-H "Content-Type: application/json" \
-d '{"link_id": "LINK_ID", "payer": {"email": "teste@email.com", "cpf": "12345678900"}}'
Simule o pagamento
curl -X POST https://api.pagozz.com/v1/payments/TRANSACTION_ID/simulate/succeed \
-H "Pagozz-Token: pgz_test_XXX"
Verifique o webhook
Seu endpoint receberá um evento payment.succeeded normalmente.
Diferenças entre test e live
| Aspecto | Test | Live |
|---|
| PIX | QR Code placeholder | QR Code real via Woovi |
| Confirmação | Simulação manual | Webhook do provedor |
| Saldo | Disponível imediatamente | Ciclo normal (D+0 para PIX) |
| Webhooks | Disparados normalmente | Disparados normalmente |
| Rate limits | Mesmos limites | Mesmos limites |
Guards de segurança
- Simulações só funcionam com
environment = test
- Tentativas em live retornam
403 Forbidden
- Simulações são idempotentes: simular uma transação já completa retorna sucesso sem efeito
Todas as simulações disparam webhooks normalmente, permitindo testar o fluxo end-to-end completo.
