Copy page

Fluxos de pagamento

Fluxo de pagamento — Caminho feliz

Esta página descreve o fluxo de pagamento end-to-end padrão na Fluxis: desde a criação de uma solicitação de pagamento até a detecção on-chain, processamento assíncrono e entrega de webhooks. Para resultados não padrão (pagamento insuficiente, expiração, transações falhas), consulte Fluxos de pagamento — Casos extremos.

Visão geral da arquitetura

O processamento de pagamentos Fluxis abrange quatro serviços cooperativos:

Code
graph LR
    API[Core API] --> DB[(PostgreSQL)]
    API --> Redis[(Redis)]
    Cron[Cron] --> Redis
    Cron --> SQS[(SQS transactions queue)]
    Worker[Transaction Worker] --> SQS
    Worker --> DB
    Worker --> API
    Cron --> Chain[Polygon / Base / Avalanche / Arbitrum]

Service	Role
Core API	Cria solicitações de pagamento, atribui endereços vault, gera tokens NASPIP, expõe endpoints REST
Cron	Consulta blockchains a cada 3 segundos por eventos ERC-20 Transfer para endereços vault ativos
Transaction Worker	Consome a fila SQS transactions e executa o ciclo de vida de pagamento de 3 saltos
Crypto Service	Serviço externo para gerenciamento de vaults, consolidação e liquidação (pós-pagamento)

Comerciantes interagem apenas com a Core API e webhooks em nível de conta. Monitoramento blockchain e confirmação de transações ocorrem de forma assíncrona.

Pré-requisitos

Antes que um pagamento possa ser bem-sucedido, a hierarquia do comerciante deve estar configurada:

Code
graph TD
    Org[Organization] --> Acct[Account]
    Acct --> POS[Point of Sale]
    Acct --> WH[Account Webhook]
    POS --> PR[Payment Request]

1. Organization and Account — Consulte Merchant Sign Up.
2. Point of Sale — Um PoS online_fixed (e-commerce) ou cashier_fixed (caixa física). Consulte Point of Sale.
3. Authentication — Bearer token + x-fluxis-api-key em rotas protegidas. Consulte Authentication & Configuration.
4. Webhook (recommended) — Registre em nível de conta: POST /v1/account/{accountID}/webhook. Consulte Webhooks.

Passo 1 — Criar uma solicitação de pagamento

Crie uma solicitação de pagamento pelo endpoint do Point of Sale — não uma rota independente /v1/payment-requests:

Code
POST /v1/pos/{posID}/payment-request
Authorization: Bearer <token>
x-fluxis-api-key: <api_key_id>

Code
{
  "reference_id": "order-12345",
  "amount": "49.99",
  "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
  "order": {
    "total": "49.99",
    "coin_code": "USD",
    "description": "Premium Subscription"
  }
}

O que a Fluxis faz internamente

Code
sequenceDiagram
    participant M as Merchant App
    participant API as Core API
    participant Pool as Vault Pool
    participant Redis as Redis Cache

    M->>API: POST /v1/pos/:posID/payment-request
    API->>Pool: Atomically assign vault (FOR UPDATE SKIP LOCKED)
    Pool-->>API: Vault address
    API->>API: Create payment request (status: created)
    API->>Redis: Cache vault → payment request mapping
    API->>API: Generate NASPIP token (PASETO v4)
    API-->>M: id, status, token, expiration

Na criação, a Fluxis:

1. Valida o PoS e resolve o UAI
2. Atribui um endereço vault único do pool pré-implantado
3. Define status created e timestamp de expiração de 8 minutos
4. Armazena em cache o endereço vault no Redis para buscas rápidas do cron
5. Retorna um token NASPIP para exibir QR / link de pagamento

Exemplo de resposta:

Code
{
  "status": "success",
  "data": {
    "id": "180ede28-2968-4ac7-8e81-ca446f201949",
    "reference_id": "order-12345",
    "status": "created",
    "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...",
    "expiration": 1759397652
  }
}

Passo 2 — Cliente paga on-chain

O cliente escaneia o token NASPIP (QR code ou link) e envia o valor exato para o endereço vault na rede configurada. A Fluxis não detém custódia neste passo — o pagamento vai diretamente para o smart contract vault.

Sua aplicação deve:

• Exibir o token NASPIP e uma contagem regressiva baseada em expiration
• Consultar GET /v1/pos/{posID}/payment-request/{paymentRequestID} ou aguardar webhooks
• Não cumprir o pedido até o pagamento atingir um status terminal

Passo 3 — Cron detecta a transferência

O serviço cron executa um job de leitura blockchain a cada 3 segundos em redes suportadas (Polygon, Base, Avalanche, Arbitrum):

Code
flowchart TD
    A[Acquire Redis lock] --> B[Read last processed block]
    B --> C[eth_getLogs Transfer events]
    C --> D[Match tx.to against active vaults in Redis]
    D --> E{Match found?}
    E -->|Yes| F[Enqueue transaction_incoming_payment to SQS]
    E -->|No| G[Update last processed block]
    F --> G

Detalhes importantes:

• Usa eth_getLogs com chunking adaptativo para consultar eventos ERC-20 Transfer eficientemente
• Filtra transações onde o destinatário (to) corresponde a um endereço vault ativo em cache no Redis
• Enfileira transações correspondentes na fila SQS transactions com tipo de evento transaction_incoming_payment

Passo 4 — Worker SQS de três saltos

O transaction worker processa cada pagamento por três saltos SQS sequenciais:

Code
sequenceDiagram
    participant SQS as SQS Queue
    participant W as Transaction Worker
    participant Chain as Blockchain RPC
    participant WH as Merchant Webhook

    Note over SQS,W: Hop 1 — transaction_incoming_payment
    SQS->>W: Incoming payment detected
    W->>W: created → processing
    W->>WH: Webhook (processing)
    W->>SQS: Enqueue check (finality delay)

    Note over SQS,W: Hop 2 — transaction_check_update_payment_request
    SQS->>W: After finality delay (~256s default)
    W->>Chain: GetTransaction (verify status)
    alt Confirmed
        W->>W: Compare amounts → completed / underpaid / overpaid
        W->>WH: Webhook (final status)
        W->>SQS: Enqueue confirm (immediate)
        W->>W: Release vault, clear Redis cache
    else Still pending
        W->>SQS: Re-enqueue with finality delay
    end

    Note over SQS,W: Hop 3 — transaction_confirm_payment_request
    SQS->>W: Confirm payment request
    W->>W: Create internal Transaction record
    W->>W: completed/overpaid → confirmed

Salto 1 — transaction_incoming_payment

• Valida que a solicitação de pagamento está em created ou processing
• Atualiza status para processing
• Envia webhook com status processing
• Enfileira salto 2 com atraso de finalidade (padrão 256 segundos na Polygon, configurável por rede)

Salto 2 — transaction_check_update_payment_request

Após o atraso de finalidade:

• Chama GetTransaction para verificar status on-chain (pending / confirmed / failed)
• Usa o valor da detecção eth_getLogs do cron (não de GetTransaction, que falha em transações proxy/router)
• Compara valor recebido vs valor esperado:
  • Igual → completed
  • Menor → underpaid
  • Maior → overpaid
• Envia webhook com status final
• Enfileira salto 3 imediatamente e libera o vault

Salto 3 — transaction_confirm_payment_request

• Executa apenas para pagamentos completed ou overpaid
• Cria registro interno de Transaction (taxas, endereços, entrada de ledger)
• Atualiza status da solicitação de pagamento para confirmed
• Não envia webhook (consulte a matriz de webhooks em Edge Cases)

Passo 5 — Notificações webhook

A Fluxis entrega webhooks em nível de conta quando o status da solicitação de pagamento muda durante os saltos 1 e 2:

Code
{
  "data": {
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "external_reference_id": "order-12345",
    "status": "completed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d"
  }
}

Webhook-delivered status	When
processing	Cron detectou transferência on-chain para o vault
completed	Confirmado após finalidade; valor corresponde ao esperado
underpaid	Confirmado após finalidade; recebido menos que o esperado
overpaid	Confirmado após finalidade; recebido mais que o esperado

Verifique cada webhook com HMAC-SHA256 antes de processar. Consulte Webhook Signature Verification e Webhooks.

Estados da solicitação de pagamento

Code
stateDiagram-v2
    [*] --> pending: Checkout created
    pending --> created: Payer selects UAI / vault assigned
    created --> expired: 8 min timeout
    created --> processing: On-chain payment detected
    processing --> completed: Amount matches
    processing --> underpaid: Amount too low
    processing --> overpaid: Amount too high
    completed --> confirmed: Internal transaction created
    overpaid --> confirmed: Internal transaction created

    expired --> [*]
    underpaid --> [*]
    confirmed --> [*]
    completed --> [*]
    overpaid --> [*]

State	Description	Merchant action
pending	Criada via checkout; pagador ainda não selecionou um UAI	Exibir checkout / seletor de ativo
created	Vault atribuído; aguardando pagamento on-chain (janela de 8 minutos)	Exibir token NASPIP; consultar ou usar webhooks
processing	Transferência detectada; aguardando finalidade blockchain	Informar cliente que pagamento está sendo confirmado
completed	Pagamento integral confirmado após finalidade	Cumprir pedido
confirmed	Transação interna de ledger criada	Pagamento liquidado na contabilidade Fluxis
underpaid	Confirmado, mas valor menor que o esperado	Consulte Edge Cases
overpaid	Confirmado, mas valor excede o esperado	Consulte Edge Cases
expired	Nenhum pagamento recebido antes da expiração	Criar nova solicitação de pagamento

Temporização e expiração

Dois timeouts distintos se aplicam conforme o fluxo:

Flow	Timeout	Applies to
Payment request	8 minutos	Desde atribuição de vault (status created) até expiração
Payment intention	5 minutos	Fluxo PoS caixa (cashier_fixed / cashier_open) antes do comerciante criar a solicitação de pagamento

Para o fluxo de caixa, o comerciante cria uma intenção de pagamento via POST /v1/pos/{posID}/payment-intention com janela de 5 minutos. Uma vez confirmada, a Fluxis cria a solicitação de pagamento com a janela padrão de 8 minutos.

Sequência end-to-end

Code
sequenceDiagram
    participant M as Merchant
    participant F as Fluxis API
    participant C as Customer
    participant B as Blockchain
    participant Cron as Cron
    participant W as Worker

    M->>F: POST /v1/pos/:posID/payment-request
    F-->>M: status: created, NASPIP token
    M->>C: Display QR / payment link
    C->>B: Send USDC to vault address
    Cron->>B: eth_getLogs (every 3s)
    Cron->>W: SQS: transaction_incoming_payment
    W->>M: Webhook: processing
    Note over W: Finality delay (~256s)
    W->>B: Verify transaction confirmed
    W->>M: Webhook: completed
    W->>W: Create internal transaction
    Note over W: status → confirmed (no webhook)
    M->>C: Order fulfilled

Opções de monitoramento

Method	Endpoint / setup	Best for
Webhooks (recommended)	POST /v1/account/{accountID}/webhook	Produção — atualizações de status em tempo real
Polling	GET /v1/pos/{posID}/payment-request/{paymentRequestID}	Desenvolvimento ou fallback de webhook
Transactions list	GET /v1/transactions?page=1&page_size=50	Reconciliação após confirmed

Documentação relacionada

• Creating Payment Requests — Guia de integração com exemplos de API
• Payment Requests — Status, campos e fluxo de checkout
• Payment Flows — Edge Cases — Underpaid, overpaid, expired, transações falhas, reembolsos
• Webhooks — Registro e formato de payload
• Webhook Signature Verification — Verificação HMAC e fluxo de teste
• NASPIP — Formato de token e compatibilidade com wallets
• API Reference — Point of Sale — Documentação interativa de endpoints