Referência
Status de pagamentos
Status normalizados usados pela Allya Payments.
A Allya normaliza os status retornados pelos gateways para um conjunto único.
Status disponíveis
| Status | Descrição |
|---|---|
created | Pagamento criado internamente antes da chamada ao gateway. |
pending | Pagamento aguarda ação do cliente ou confirmação do gateway. |
processing | Gateway retornou status intermediário (Pagar.me authorized em fluxo auth_and_capture, drift de contrato em algum provedor, etc.). Aguarda confirmação por webhook ou sync. |
paid | Pagamento confirmado. |
failed | Pagamento falhou ou foi recusado. |
canceled | Pagamento cancelado antes da confirmação, expirado/cancelado no gateway ou reembolsado quando o gateway só expõe esse estado como cancelamento normalizado. |
expired | Pagamento expirado. |
Eventos de webhook
Eventos enviados ao cliente seguem o formato:
payment.{status}Eventos atuais:
payment.createdpayment.pendingpayment.paidpayment.failedpayment.expiredpayment.canceled
O status processing não gera evento público na versão atual.
Status do gateway
Além do status normalizado, a Allya guarda o gatewayStatus, que é o status original retornado pelo gateway.
Use o status normalizado para lógica de negócio. Use o status do gateway apenas para investigação técnica.
Cancelamento
canceled não significa necessariamente estorno. Na rota POST /v1/payments/:id/cancel, ele representa uma cobrança de cartão que ainda não tinha sido paga e foi encerrada antes da confirmação.
Pagamentos paid exigem um fluxo próprio de refund, separado do cancelamento.
Veja também
- Webhooks: eventos
payment.*disparados em cada transição. - Sincronizar pagamento: destravar
processingconsultando o gateway. - Cancelar pagamento: quando o gateway permite e quando rejeita.
- Status de assinatura: equivalente para recorrência.