Gatilhos
No ambiente de teste, quem decide o desfecho da cobrança são os dois últimos dígitos de amount.
Você escolhe o cenário escolhendo o valor.
Isso vale apenas com chave sk_test_. Em produção o valor é só o valor.
A tabela
amount termina em |
O que acontece |
|---|---|
| qualquer outro | Paga sozinha poucos segundos depois da criação. |
01 |
Nunca paga. Expira em pix.expires_at. |
02 |
Tempo esgotado no processador: 503 acquirer_timeout, cobrança pending sem QR e chave em andamento. |
03 |
A criação é recusada pelo processador: 503 acquirer_rejected. |
04 |
Paga e entrega o mesmo evento duas vezes. |
06 |
Paga e recebe uma contestação cerca de 10 segundos depois. |
07 |
Paga sem entregar webhook. |
08 |
Entrega transaction.expired e depois transaction.paid, fora de ordem. |
Com splits[] na cobrança, mais cinco finais. Eles só valem para cobrança com split e só depois
que ela passou pelas validações de split (lista de recebedores, cota e teto, ver Split); sem
splits[], esses valores pagam sozinhos como qualquer outro.
amount termina em |
O que acontece com splits[] |
|---|---|
21 |
400 split_rejected_by_partner: o processador recusou o percentual. |
22 |
400 split_rejected_by_partner: o processador recusou pelo volume de split. |
23 |
400 split_rejected_by_partner: o processador criou a cobrança sem os splits. |
24 |
Paga normalmente. O amount de cada split no transaction.split.settled é o valor projetado na criação. |
25 |
400 split_rejected_by_partner: o processador suspendeu o recebedor. |
Exemplos: R$ 100,00 são 10000, termina em 00, e paga sozinha. R$ 100,01 são 10001, termina
em 01, e expira. R$ 55,04 são 5504, termina em 04, e entrega o evento duas vezes.
Esses gatilhos são contrato público: mudar o efeito de um deles entra no changelog.
O que cada um testa
Caminho feliz (qualquer outro). O seu checkout inteiro, do QR ao transaction.paid.
01, expiração. O contador da tela, o transaction.expired e, principalmente, o seu sistema
não apagar o pedido ao receber esse evento. Pagamento tardio existe
(Expiração).
02 e 03, falha na criação. Os dois voltam 503 e a cobrança fica sem QR. Teste que a sua
tela de checkout mostra erro em vez de ficar em branco. No 03 a retentativa usa uma
Idempotency-Key nova (a mesma devolve o mesmo 503). No 02 a retentativa usa a mesma
chave depois de 60 s; no sandbox o valor terminado em 02 dá tempo esgotado toda vez, então a
retomada volta 503 de novo (Idempotência).
04, evento duplicado. O mesmo evento, com o mesmo identificador, chega duas vezes. Se o seu
receptor não deduplicar, você entrega o produto duas vezes ou credita o cliente em dobro. É o teste
mais importante desta lista.
06, contestação. A cobrança paga volta contestada e o valor sai do seu saldo. Teste o que o
seu sistema faz com transaction.chargeback numa venda já entregue.
07, pago sem webhook. Simula a entrega que nunca chegou, seja por queda do seu servidor, seja
por falha de rede. A cobrança está paid e o seu banco de dados não sabe. É o cenário que prova que
você precisa de uma rotina de reconciliação por consulta, e não só do webhook.
08, fora de ordem. transaction.expired chega antes de transaction.paid. Um receptor que
aplica eventos cegamente na ordem de chegada marca a venda como perdida e nunca mais a recupera.
21, 22, 23 e 25, split recusado. A cobrança fica failed e a mesma Idempotency-Key
devolve o mesmo 400. Teste que a sua tela mostra o erro e que a nova tentativa usa chave nova.
24, split pelo valor projetado. Pagamento normal com split. Do seu lado, o resultado é o
mesmo de qualquer outro final: os eventos de split chegam com o valor que a criação projetou.
Como usar isso de verdade
Rode os oito (e os cinco de split, se você usa split) no seu ambiente de testes automatizados, não à mão. São valores fixos e asserções sobre o estado final do seu banco, e eles cobrem quase todo o suporte que você teria depois.
Os gatilhos não mudam nada além do desfecho: validação, erros, limites e assinatura de webhook continuam iguais aos de produção.
Próximo passo
Saques, para fechar o ciclo do dinheiro.
Referência: Cria uma cobrança (PIX, voucher, cripto, cartão ou carteira) e Consulta uma cobrança.