Sweeping Accounts - Máquina de Estados

Visão Geral

O Sweeping Accounts possui duas máquinas de estados independentes que operam em conjunto:

1. Máquina de Estados do Consentimento: controla o ciclo de vida da autorização recorrente
2. Máquina de Estados do Pagamento: controla o ciclo de vida de cada transação Pix individual

---

1. Máquina de Estados do Consentimento

O consentimento (payment initiation) representa a autorização recorrente dada pelo usuário para que a ITP execute transferências automáticas dentro dos limites definidos.

Diagrama de Estados

stateDiagram-v2
    direction LR

    [*] --> AWAITING_AUTHORISATION : Criação da\nPayment Initiation

    AWAITING_AUTHORISATION --> AUTHORISED : Usuário aprova\n(callback recebido)
    AWAITING_AUTHORISATION --> REJECTED   : Usuário rejeita\nou timeout
    AWAITING_AUTHORISATION --> REVOKED    : Cancelamento\nantes da autorização

    AUTHORISED --> CONSUMED : totalAllowedAmount\natingido
    AUTHORISED --> EXPIRED  : Data de expiração\natingida
    AUTHORISED --> REVOKED  : Cancelamento via PATCH\n(ITP ou usuário)

    REJECTED --> [*]
    CONSUMED --> [*]
    EXPIRED  --> [*]
    REVOKED  --> [*]

    classDef terminal  fill:#f5c6c6,stroke:#c0392b,color:#333
    classDef active    fill:#c6e2f5,stroke:#2980b9,color:#333
    classDef initial   fill:#d5f5d5,stroke:#27ae60,color:#333

    class REJECTED,CONSUMED,EXPIRED,REVOKED terminal
    class AUTHORISED active
    class AWAITING_AUTHORISATION initial

Descrição dos Estados

Transições Válidas

---

2. Máquina de Estados do Pagamento

Cada transação Pix executada dentro de um consentimento AUTHORISED possui seu próprio ciclo de vida.

Diagrama de Estados

stateDiagram-v2
    direction LR

    [*] --> PDNG : Pagamento criado

    PDNG --> SCHD : Agendamento validado\n(liquidação futura)
    PDNG --> ACSP : Enviado ao SPI\n(liquidação imediata)
    PDNG --> RJCT : Falha na validação\n(limites, consentimento, dados)

    SCHD --> ACSP : Data de liquidação\natingida
    SCHD --> CANC : Cancelamento antes\nda liquidação
    SCHD --> RJCT : Falha no agendamento

    ACSP --> ACSC : Liquidação confirmada\npelo SPI
    ACSP --> RJCT : Falha durante\na liquidação

    ACSC --> [*]
    RJCT --> [*]
    CANC --> [*]

    classDef terminal   fill:#f5c6c6,stroke:#c0392b,color:#333
    classDef success    fill:#d5f5d5,stroke:#27ae60,color:#333
    classDef inprogress fill:#fef9c3,stroke:#f39c12,color:#333
    classDef initial    fill:#c6e2f5,stroke:#2980b9,color:#333

    class RJCT,CANC terminal
    class ACSC success
    class SCHD,ACSP inprogress
    class PDNG initial

Descrição dos Estados

Transições Válidas

---

Relação entre Consentimento e Pagamentos

---

flowchart TD
    PI["🔓 Payment Initiation\n[AUTHORISED]"]

    PI --> P1["✅ Pagamento #1\nACSC"]
    PI --> P2["✅ Pagamento #2\nACSD"]
    PI --> P3["❌ Pagamento #3\nRJCT"]
    PI --> P4["⏳ Pagamento #4\nPDNG"]

    P1 -->|"totalUsedAmount += valor"| SUM[("Σ totalUsedAmount\nacumulado")]
    P2 -->|"totalUsedAmount += valor"| SUM
    P3 -->|"sem alteração"| SUM

    SUM -->|"totalUsedAmount\n== totalAllowedAmount"| CONSUMED["🔒 Payment Initiation\n[CONSUMED]"]

    style PI       fill:#c6e2f5,stroke:#2980b9,color:#333
    style CONSUMED fill:#f5c6c6,stroke:#c0392b,color:#333
    style P1       fill:#d5f5d5,stroke:#27ae60,color:#333
    style P2       fill:#d5f5d5,stroke:#27ae60,color:#333
    style P3       fill:#f5c6c6,stroke:#c0392b,color:#333
    style P4       fill:#fef9c3,stroke:#f39c12,color:#333
    style SUM      fill:#f0f0f0,stroke:#888,color:#33

Códigos de Rejeição (RJCT)

Quando um pagamento é rejeitado, o campo rejectionReason indica o motivo:

Erros marcados como retriáveis podem ser tentados novamente respeitando as janelas de retry definidas pelo Open Finance Brasil: Intradia (até 12h do mesmo dia) e Extradia (até 7 dias corridos).

---

Pontos de Atenção

⚠️

Estados terminais são irreversíveis: Uma vez que um pagamento ou consentimento atinge um estado terminal (ACSC, RJCT, CANC, CONSUMED, REVOKED, EXPIRED), não há transição de retorno. Para recomeçar, uma nova payment initiation deve ser criada e autorizada.

⚠️

Consentimento CONSUMED ≠ REVOKED: CONSUMED indica uso completo do limite (comportamento esperado); REVOKED indica cancelamento explícito. Comunique de forma diferente ao usuário: o primeiro pode sugerir criação de novo consentimento, o segundo deve confirmar o encerramento intencional.

⚠️

Pagamentos rejeitados não reduzem o totalUsedAmount: Apenas pagamentos com status ACSC incrementam o total utilizado. Pagamentos RJCT não consomem o limite do consentimento.

⚠️

Monitoramento: Implemente alertas para consentimentos com alto totalUsedAmount relativo ao totalAllowedAmount (ex: ≥ 80%), para que o usuário possa renovar o consentimento antes de ser interrompido.