Noviuz DocsCiclo de vida e máquinas de estado
Diagramas de estados formais, transições, regras de negócio e eventos de webhook para cobranças PIX e saques.
Na Conta Nexiuz, operações financeiras seguem máquinas de estado formais e determinísticas (Finite State Machines - FSM). O estado de um recurso não é alterado de forma arbitrária; cada transição decorre de eventos auditáveis, respeitando a separação entre intenção, confirmação bancária e efeito contábil.
1. Ciclo de Vida da Cobrança PIX
A cobrança PIX é emitida com valor fixo e código de idempotência (code), gerando um QR Code estático ou dinâmico e o código Copia-e-Cola correspondente.
Diagrama de Estados (FSM PIX)
POST /api/public/v1/pix
│
▼
┌───────────────┐
│ PENDING │ ◄─── QR Code gerado; aguardando pagamento
└───┬───────┬───┘
│ │
Pagamento │ │ Tempo limite atingido (expires_at + 10 min)
confirmado│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ SETTLED │ │ EXPIRED │
└───────────┘ └───┬───────┘
│
│ Pagamento tardio aceito (janela de 7 dias)
▼
┌───────────┐
│ SETTLED │
└───────────┘Detalhamento dos Estados
| Estado | Significado | Efeito Econômico |
|---|---|---|
PENDING | Cobrança criada e ativa. Aguardando o pagador escanear e transferir via PIX. | Nenhum efeito no saldo da conta. |
SETTLED | O valor foi liquidado pelo Banco Central e creditado na conta recebedora. | Saldo disponível aumenta pelo valor líquido (net_amount = amount - fees). |
EXPIRED | O prazo de validade (expires_at) expirou sem registro de pagamento. | Nenhum efeito no saldo. |
FAILED | Ocorrência de erro cadastral, estorno bancário ou rejeição regulatória. | Nenhum efeito no saldo (ou compensado em caso de estorno). |
Regras de Negócio Críticas do PIX
- Margem de Graça na Expiração (
PIX_EXPIRY_GRACE):- O sistema aplica uma tolerância de 10 minutos além do horário estipulado em
expires_atantes de transicionar paraEXPIRED. Essa margem acomoda atrasos de rede e webhooks bancários em trânsito.
- O sistema aplica uma tolerância de 10 minutos além do horário estipulado em
- Pagamentos Tardios (
LATE_PAYMENT_WINDOW):- Caso um pagador realize a transferência no app bancário no último instante e a notificação chegue após a cobrança estar
EXPIRED, o sistema suporta liquidação tardia em até 7 dias. Nesse caso, o recurso transiciona deEXPIREDparaSETTLED, credita o saldo da conta e emite o webhookpix.settled.
- Caso um pagador realize a transferência no app bancário no último instante e a notificação chegue após a cobrança estar
- Imunidade à Expiração por Retenção:
- Se o pagamento for detectado pela rede bancária, a cobrança entra em processamento interno e nunca mais expira, mesmo que passe por análise de compliance ou confirmação de custódia.
2. Ciclo de Vida do Saque
O saque bancário via PIX retira fundos da conta vinculada e os transfere para uma chave PIX de destino pertencente a um beneficiário elegível.
Diagrama de Estados (FSM Saque)
POST /api/public/v1/withdrawals
│
▼
┌───────────────┐
│ PENDING │ ◄─── Saldo reservado; ordem despachada ao rail PIX
└───┬───────┬───┘
│ │
Liquidação│ │ Rejeição bancária, chave inválida ou
bancária │ │ saldo insuficiente
▼ ▼
┌───────────┐ ┌───────────┐
│ SETTLED │ │ FAILED │
└───────────┘ └───────────┘
│
▼
Saldo reservado é
estornado automaticamenteDetalhamento dos Estados
| Estado | Significado | Efeito Econômico |
|---|---|---|
PENDING | Saque aceito e registrado. A ordem de transferência foi enviada para o canal de liquidação. | Saldo disponível diminui e saldo reservado aumenta no mesmo instante. |
SETTLED | O banco de destino confirmou o recebimento do crédito via PIX. | O saldo reservado é baixado definitivamente. Operação concluída. |
FAILED | A transferência falhou (chave inexistente, conta destino encerrada, limite de terceiros). | O saldo reservado é estornado integralmente de volta ao saldo disponível da conta. |
Garantias de Consistência e Reserva
Zero Perda de Saldo: Na criação do saque (PENDING), o valor bruto (amount) é imediatamente movido para a reserva da conta. Se a transferência falhar por qualquer motivo (FAILED), o estorno da reserva para o saldo disponível é atômico. Não existe estado intermediário em que o saldo desapareça ou fique duplicado.
3. Mapeamento de Transições e Webhooks
Toda transição de estado relevante emite um evento de webhook assinado para os endpoints cadastrados:
| Recurso | De | Para | Evento de Webhook | Gatilho / Ação |
|---|---|---|---|---|
| Cobrança PIX | PENDING | SETTLED | pix.settled | Pagamento confirmado na rede bancária. |
| Cobrança PIX | PENDING | EXPIRED | pix.expired | Tempo limite esgotado sem pagamento. |
| Cobrança PIX | EXPIRED | SETTLED | pix.settled | Pagamento tardio recebido na janela de 7 dias. |
| Cobrança PIX | PENDING | FAILED | pix.failed | Pagamento cancelado ou devolvido. |
| Saque PIX | PENDING | SETTLED | withdrawal.settled | Transferência bancária concluída com sucesso. |
| Saque PIX | PENDING | FAILED | withdrawal.failed | Transferência rejeitada; saldo estornado. |
4. Simulação em Sandbox (Ambiente TEST)
No ambiente TEST, a máquina de estados não depende de bancos externos. Você força as transições de teste utilizando os endpoints de simulação:
POST /api/public/v1/pix/{charge_id}/simulate-payment
Corpo: { "outcome": "SUCCESS" } ──► Transiciona cobrança para SETTLED e credita conta
Corpo: { "outcome": "FAILURE" } ──► Transiciona cobrança para FAILED
POST /api/public/v1/withdrawals/{withdrawal_id}/simulate-outcome
Corpo: { "outcome": "SUCCESS" } ──► Transiciona saque para SETTLED e baixa reserva
Corpo: { "outcome": "FAILURE" } ──► Transiciona saque para FAILED e estorna saldoOs endpoints de simulação existem exclusivamente no ambiente TEST. Em ambiente LIVE, essas rotas respondem 404 NOT_FOUND por segurança estrutural.