Status das transações
Estados possíveis de um pagamento e o que fazer em cada um.
Estados do pagamento
| Status | Valor numérico | Descrição |
|---|---|---|
pending | 1 | Criado e aguardando processamento pelo gateway |
approved | 2 | Aprovado — fundos reservados ou PIX confirmado |
failed | 3 | Falhou após todas as tentativas configuradas |
refunded | 4 | Estornado após aprovação |
processing | — | Estado transitório: resposta assíncrona (202) ainda em andamento |
O estado processing não existe no banco de dados — ele é retornado apenas na resposta HTTP 202 quando o gateway não respondeu dentro do time_to_wait_sync. O estado persistido permanece pending até a resolução.
O que fazer em cada estado
| Status | Ação recomendada |
|---|---|
pending | Aguarde o webhook de approved ou failed |
processing | Armazene o transaction_id e aguarde o webhook |
approved | Libere o produto/serviço ao cliente |
failed | Ofereça nova tentativa ao cliente com nova Idempotency-Key |
refunded | Confirme o estorno ao cliente; atualize seu sistema de pedidos |
Estados finais
Use o helper do pacote @plugtopay/api-client para distinguir estados que não mudarão mais:
import { isFinalPaymentStatus } from '@plugtopay/api-client'
if (isFinalPaymentStatus(payment.status)) {
// approved, failed ou refunded — pode encerrar o polling
}Mapeamento de múltiplas tentativas
Quando há fallback entre gateways, cada tentativa fica registrada em transactions[] com seu próprio status. O status raiz do PaymentResource reflete o resultado final após todas as tentativas:
{
"status": "approved",
"transactions": [
{ "attempt": 1, "gateway": "safe2pay", "status": "failed", "response_code": "51" },
{ "attempt": 2, "gateway": "pagarme", "status": "approved", "response_code": "00" }
]
}