Status das transações

Estados do pagamento

Status	Valor numérico	Descrição
`pending`	`1`	Criado e aguardando processamento pelo gateway
`authorized`	`2`	Pré-autorizado — valor reservado no cartão, aguardando captura
`approved`	`3`	Aprovado — cobrança efetivada ou PIX confirmado
`failed`	`4`	Falhou após todas as tentativas configuradas
`refunded`	`5`	Estornado após aprovação
`cancelled`	`6`	Pré-autorização cancelada — valor liberado no cartã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
`authorized`	Capture quando confirmar o pedido, ou cancele para liberar o valor
`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
`cancelled`	A reserva foi desfeita; nada foi cobrado do cliente

authorized não é um estado final: o valor está apenas reservado. Se você não capturar, o gateway libera a reserva sozinho depois de alguns dias e a venda se perde.

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, refunded ou cancelled — pode encerrar o polling
}

authorized não conta como final: a transação ainda espera uma captura ou um cancelamento.

Mapeamento de múltiplas tentativas

Quando há fallback entre gateways, cada tentativa fica registrada em transactions[] com seu próprio status e request_time (tempo daquela tentativa específica). O status raiz do PaymentResource reflete o resultado final após todas as tentativas; total_request_time, plugtopay_request_time e gateways_request_time dão o tempo total, o tempo interno da PlugToPay e o tempo somado gasto nos gateways, respectivamente:

{
  "status": "approved",
  "total_request_time": "5.21s",
  "plugtopay_request_time": "0.08s",
  "gateways_request_time": "5.13s",
  "transactions": [
    { "attempt": 1, "gateway": "safe2pay", "status": "failed", "response_code": "51", "request_time": "2.10s" },
    { "attempt": 2, "gateway": "pagarme",  "status": "approved", "response_code": "00", "request_time": "1.21s" }
  ]
}

Introdução

Conceitos principais

Orquestração

Pagamentos

Assinaturas

Recursos

Status das transações

Estados do pagamento

O que fazer em cada estado

Estados finais

Mapeamento de múltiplas tentativas

​Estados do pagamento

​O que fazer em cada estado

​Estados finais

​Mapeamento de múltiplas tentativas

Estados do pagamento

O que fazer em cada estado

Estados finais

Mapeamento de múltiplas tentativas