Copy page

Key Concepts

Settlements & Consolidation

After customers pay, Fluxis processes funds through two automated backend pipelines: consolidation (moving assets from payment vaults) and settlement (batching confirmed ledger transactions and sending net proceeds to your configured addresses).

High-level flow

Code
flowchart LR
    PR[Payment Request] --> V[Vault Address]
    V --> C[Consolidation]
    C --> LT[Ledger Transaction]
    LT --> S[Settlement Batch]
    S --> ADDR[Your Settlement Address]

1. Payment — customer sends crypto to a per-request vault address
2. Consolidation — cron jobs aggregate completed payments from vaults
3. Confirmation — payment requests reach confirmed; ledger transactions are created
4. Settlement — cron jobs batch transactions and transfer net amounts to your settlement address

On-chain monitoring runs on Polygon, Base, Avalanche, and Arbitrum today.

Consolidation

Consolidation groups completed payment requests by vault address and asset, then moves funds from ephemeral vault wallets toward Fluxis-controlled consolidation wallets.

Cron schedule

Job	Schedule	Purpose
CONSOLIDATION_AGGREGATION_JOB	Every 10 minutes	Group eligible payment requests by vault + token
CONSOLIDATION_EXECUTION_JOB	Every 30 minutes	Execute pending consolidation transfers

Payment requests linked to a consolidation receive a consolidation_id in the database. This is an internal operational step—merchants typically observe the outcome through payment request status and transaction records rather than consolidation IDs directly.

Settlement

Settlement batches confirmed ledger transactions by account, organization, and token, then sends net proceeds to configured settlement addresses.

Cron schedule

Job	Schedule	Purpose
SETTLEMENT_AGGREGATION_JOB	Hourly at :00	Group unsettled transactions into settlement records
SETTLEMENT_EXECUTION_JOB	Hourly at :05	Process pending settlements (on-chain transfers)
SETTLEMENT_CONFIRMATION_JOB	Hourly at :15	Confirm settlement transactions on chain

Settlement statuses

Status	Meaning
created	Settlement record created
pending	Ready for execution
processing	Transfer in progress
completed	Funds delivered
failed	Execution failed
in_review	Manual review required

If no settlement address is configured for the account (or its parent organization) on the required network, aggregation logs an error and skips that batch.

Settlement addresses

Settlement addresses tell Fluxis where to send your net proceeds per blockchain network. Resolution order:

1. Account-level address for the network (if configured)
2. Organization-level address for the network (fallback default)

REST API — organization scope

Organization API keys can manage addresses directly:

Method	Endpoint	Description
GET	/v1/organization/settlement-addresses	List organization addresses
POST	/v1/organization/settlement-addresses	Create address for a network
PUT	/v1/organization/settlement-addresses	Update address for a network
DELETE	/v1/organization/settlement-addresses?network=polygon	Remove address for a network

Request body (POST/PUT):

Code
{
  "network": "polygon",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "address_tag": null
}

REST API — account scope

Code
GET /v1/account/{accountId}/settlement-addresses

Returns effective settlement addresses for the account (including organization fallbacks). Account-level create/update/delete endpoints exist in code but are not currently exposed on the public API—configure account-specific overrides through the Fluxis Dashboard or contact support.

Response fields

Field	Description
owner	organization or account
settlement_type	Fee category (e.g. payment_net_amount, payment_service_fee)
settlement_address	Destination blockchain address
address_type	Network identifier (e.g. polygon, base)
address_tag	Optional memo/tag for supported networks

Dashboard

Account settlement addresses can also be managed in the Fluxis Dashboard under account settings (settlement addresses section).

Settlement items

Each settlement may contain multiple items representing fee splits:

• Net amount to merchant (payment_net_amount)
• Service fees (payment_service_fee)
• Developer fees (payment_developer_fee)
• Revenue share fees (payment_revenue_shared_fee)

Each item maps to a settlement address of the matching type when configured.

What merchants should configure

1. Organization settlement addresses — at minimum, one address per network you accept (Polygon, Base, Avalanche, Arbitrum)
2. Account overrides (optional) — per-account destinations when sub-merchants need separate payouts
3. Webhook + transaction reconciliation — settlement is asynchronous; use Webhook Events and Transactions to track payment confirmation before expecting settlement

Relationship to payment requests

Payment request status	Consolidation	Settlement
completed / overpaid / underpaid	Eligible after processing	After confirmed + ledger transaction
confirmed	May already be consolidated	Eligible for settlement aggregation
expired / failed	Not eligible	Not eligible

Related documentation

• Payment Requests — status lifecycle through confirmed
• Transactions — ledger records that feed settlement
• API Integration Guide — Step 4 settlement configuration
• About Fluxis — supported networks and settlement scope