1
Pagamento aprovado (cartão)
Cobre um valor terminando em
00 com um cartão aprovado (...0000).
Espere: transação paid, webhook transaction.paid.2
Pagamento recusado (cartão)
Repita com um cartão de recusa (
...1002 = CARD_DECLINED).
Espere: transação refused, webhook transaction.refused, e sua UI tratando o erro.3
Falha retryável (cartão)
Use
...2001 (PROCESSING_ERROR).
Espere: falha que permite nova tentativa — valide seu fluxo de retry.4
PIX que paga sozinho
Crie um PIX com valor terminando em
07 (ex.: R$ 100,07).
Espere: waiting_payment → paid após o delay; webhook transaction.paid.5
PIX/boleto que expira
Use valor terminando em
17.
Espere: waiting_payment → expira/cancela; trate o vencimento.6
Estado aguardando (manual)
Use valor terminando em
27 (ou modo manual) e depois Simular Pagamento no painel.
Espere: controlar a transição waiting_payment → paid na hora que quiser.7
Estorno (refund)
Estorne um pagamento aprovado via
POST /transactions/{id}/refund, enviando o body
{ "reason": "Cliente solicitou cancelamento" } — o campo reason é obrigatório
(400 sem ele).
Espere: resposta { "refunds": [...], "processResults": [...] } com o reembolso refunded,
webhook transaction.refunded e o status da transação atualizado.8
Chargeback
Em um pagamento de cartão aprovado, abra a contestação (valor
...31 ou painel) e force o
desfecho won/lost.
Espere: ao abrir, a transação entra em in_protest e a carteira é debitada; no won ela volta
para paid, no lost vai para chargeback. Exercite o fluxo de defesa.9
Recebedor recusado (KYC)
Se você usa split, crie um recebedor com um
documento de teste terminado em
0003 (KYC reprovado).
Espere: webhook recipient.refused com pendencies no payload, e
GET /recipients/:id mostrando o motivo. Trate a exibição do motivo para o seu seller.10
Webhooks de ponta a ponta
Confirme que seu endpoint recebe e valida a assinatura de cada evento acima.
Veja Webhooks.
Tratou aprovação, recusa, retry, PIX, expiração, estorno, chargeback e recusa de recebedor?
Sua integração está pronta para produção. Troque as URLs base e a API key e siga em frente.