Estados

O ciclo de vida de uma operação, do clique à liquidação.

Estado	Terminal	Significado
initiated	não	Criada; o pagador ainda não agiu
pending	não	O pagador agiu; falta a confirmação do rail
success	sim	Cobrada — os fundos estão creditados no seu saldo
failed	sim	Recusada ou falhada no rail
cancelled	sim	Anulada (pelo pagador ou por si) antes da cobrança
expired	sim	A ligação ou a sessão de pagamento expirou sem acção

Regras

• Um estado terminal nunca mais muda. success não se torna failed; uma cobrança contestada produz um recurso novo (reembolso, litígio), nunca uma reescrita do histórico.
• pending pode demorar — alguns pagadores validam o seu código USSD vários minutos depois. Nunca trate pending como uma falha.
• A transição que lhe interessa chega por webhook; a leitura (GET /v1/payments/{id}) é a rede de segurança, não o mecanismo principal.

Não derive o seu estado do nosso

Um estado descreve a nossa operação. Aquilo em que a sua encomenda deve tornar-se é decisão sua: um success não quer dizer «expedir», quer dizer «os fundos estão consigo». Mantenha a sua própria máquina de estados e faça-a avançar com os eventos, não o contrário.