pending e termina em um estado final. Entender esse ciclo evita os dois erros mais caros de uma integração de pagamento: liberar um pedido que não foi pago e cobrar duas vezes o mesmo pedido.
Estados
Uma vez fora de
pending, a transação não volta para ele. Os estados finais failed e cancelled não viram approved.Expiração
Uma cobrança Pix vale 15 minutos a partir da criação (expiresAt). Se não for paga, a NyxPag a cancela: status: "cancelled" e expired: true. Você recebe transaction.cancelled.
refunded
refunded existe para transações estornadas pela NyxPag. A API pública não tem endpoint de reembolso, e esse estado não dispara webhook transaction.*. Se o seu negócio depende de detectar estornos, concilie com GET /transactions.
202 não é um estado
O código HTTP202 Accepted significa que a operação foi recebida e está sendo conferida automaticamente. A transação continua pending, com processingState: "reconciling", até virar approved ou failed.
O objeto transação
É odata de POST /transactions, POST /transfers e GET /transactions/{id}, e o data dos eventos transaction.*.
processingState
Direção, tipo e método
Combine
direction e type para saber o efeito no saldo: out + withdrawal reduz o disponível, in + payment aumenta.
Como acompanhar
1
Webhook primeiro
transaction.approved, failed e cancelled chegam assim que o estado muda. Veja transaction.*.2
Consulta pelo seu externalId
GET /transactions/PEDIDO-1042 não exige guardar o ID da NyxPag.3
refresh=true com moderação
Confere o estado mais recente de uma transação
pending. Gasta a cota.4
Conciliação periódica
Um job que lista as transações recentes cobre webhook perdido e estados sem webhook, como
refunded.Acompanhar transações
Listagem, filtros, paginação e conciliação.
Eventos de transação
O payload dos webhooks de cada estado.