Copy page

Payment Flows

Payment Flow — Happy Path

This page describes the standard end-to-end payment flow in Fluxis: from creating a payment request through on-chain detection, asynchronous processing, and webhook delivery. For non-standard outcomes (underpayment, expiration, failed transactions), see Payment Flows — Edge Cases.

Architecture overview

Fluxis payment processing spans four cooperating services:

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	Creates payment requests, assigns vault addresses, generates NASPIP tokens, exposes REST endpoints
Cron	Polls blockchains every 3 seconds for ERC-20 Transfer events to active vault addresses
Transaction Worker	Consumes the transactions SQS queue and runs the 3-hop payment lifecycle
Crypto Service	External service for vault management, consolidation, and settlement (post-payment)

Merchants interact only with the Core API and account-level webhooks. Blockchain monitoring and transaction confirmation happen asynchronously.

Prerequisites

Before a payment can succeed, the merchant hierarchy must be configured:

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

1. Organization and Account — See Merchant Sign Up.
2. Point of Sale — An online_fixed PoS (e-commerce) or cashier_fixed PoS (physical register). See Point of Sale.
3. Authentication — Bearer token + x-fluxis-api-key on protected routes. See Authentication & Configuration.
4. Webhook (recommended) — Register at account scope: POST /v1/account/{accountID}/webhook. See Webhooks.

Step 1 — Create a payment request

Create a payment request through the Point of Sale endpoint — not a standalone /v1/payment-requests route:

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"
  }
}

What Fluxis does internally

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

On creation, Fluxis:

1. Validates the PoS and resolves the UAI
2. Assigns a unique vault address from the pre-deployed pool
3. Sets status to created and an 8-minute expiration timestamp
4. Caches the vault address in Redis for fast cron lookups
5. Returns a NASPIP token for QR code / payment link display

Example response:

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
  }
}

Step 2 — Customer pays on-chain

The customer scans the NASPIP token (QR code or link) and sends the exact amount to the vault address on the configured network. Fluxis does not hold custody during this step — the payment goes directly to the vault smart contract.

Your application should:

• Display the NASPIP token and a countdown based on expiration
• Poll GET /v1/pos/{posID}/payment-request/{paymentRequestID} or wait for webhooks
• Not fulfill the order until the payment reaches a terminal status

Step 3 — Cron detects the transfer

The cron service runs a blockchain reading job every 3 seconds on supported networks (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

Key details:

• Uses eth_getLogs with adaptive chunking to query ERC-20 Transfer events efficiently
• Filters transactions where the recipient (to) matches an active vault address cached in Redis
• Enqueues matched transactions to the transactions SQS queue with event type transaction_incoming_payment

Step 4 — Three-hop SQS worker

The transaction worker processes each payment through three sequential SQS hops:

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

Hop 1 — transaction_incoming_payment

• Validates payment request is in created or processing
• Updates status to processing
• Sends a webhook with status processing
• Enqueues hop 2 with a finality delay (default 256 seconds on Polygon, configurable per network)

Hop 2 — transaction_check_update_payment_request

After the finality delay:

• Calls GetTransaction to verify on-chain status (pending / confirmed / failed)
• Uses the amount from cron's eth_getLogs detection (not from GetTransaction, which fails on proxy/router transactions)
• Compares received amount vs expected amount:
  • Equal → completed
  • Less → underpaid
  • Greater → overpaid
• Sends a webhook with the final status
• Enqueues hop 3 immediately and releases the vault

Hop 3 — transaction_confirm_payment_request

• Runs only for completed or overpaid payments
• Creates an internal Transaction record (fees, addresses, ledger entry)
• Updates payment request status to confirmed
• Does not send a webhook (see webhook matrix in Edge Cases)

Step 5 — Webhook notifications

Fluxis delivers webhooks at account scope when payment request status changes during hops 1 and 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 detected an on-chain transfer to the vault
completed	Confirmed after finality; amount matches expected
underpaid	Confirmed after finality; received less than expected
overpaid	Confirmed after finality; received more than expected

Verify every webhook with HMAC-SHA256 before processing. See Webhook Signature Verification and Webhooks.

Payment request states

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	Created via checkout; payer has not selected a UAI yet	Show checkout / asset picker
created	Vault assigned; awaiting on-chain payment (8-minute window)	Display NASPIP token; poll or use webhooks
processing	Transfer detected; awaiting blockchain finality	Inform customer payment is being confirmed
completed	Full payment confirmed after finality	Fulfill order
confirmed	Internal ledger transaction created	Payment is settled in Fluxis accounting
underpaid	Confirmed but amount is less than expected	See Edge Cases
overpaid	Confirmed but amount exceeds expected	See Edge Cases
expired	No payment received before expiration	Create a new payment request

Timing and expiration

Two different timeouts apply depending on the flow:

Flow	Timeout	Applies to
Payment request	8 minutes	From vault assignment (created status) until expiration
Payment intention	5 minutes	Cashier PoS flow (cashier_fixed / cashier_open) before the merchant creates the payment request

For the cashier flow, the merchant creates a payment intention via POST /v1/pos/{posID}/payment-intention with a 5-minute window. Once confirmed, Fluxis creates the payment request with the standard 8-minute payment window.

End-to-end sequence

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

Monitoring options

Method	Endpoint / setup	Best for
Webhooks (recommended)	POST /v1/account/{accountID}/webhook	Production — real-time status updates
Polling	GET /v1/pos/{posID}/payment-request/{paymentRequestID}	Development or webhook fallback
Transactions list	GET /v1/transactions?page=1&page_size=50	Reconciliation after confirmed

Related documentation

• Creating Payment Requests — Integration guide with API examples
• Payment Requests — States, fields, and checkout flow
• Payment Flows — Edge Cases — Underpaid, overpaid, expired, failed transactions, refunds
• Webhooks — Registration and payload format
• Webhook Signature Verification — HMAC verification and test workflow
• NASPIP — Token format and wallet compatibility
• API Reference — Point of Sale — Interactive endpoint documentation