# 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

```mermaid
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.

::::note
Consolidation minimum thresholds apply (aggregation uses a configurable minimum amount). Small balances may remain in vaults until the threshold is met.
:::::

## 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):

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

### REST API — account scope

```
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](/docs/developers/webhook-events) and [Transactions](/docs/developers/transactions) to track payment confirmation before expecting settlement

::::warning
Settlement execution depends on valid addresses for each network and item type. Missing addresses block settlement for affected batches—configure addresses before going live.
:::::

## 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](/docs/key-concepts/payment-request) — status lifecycle through `confirmed`
- [Transactions](/docs/developers/transactions) — ledger records that feed settlement
- [API Integration Guide](/docs/developers/tutorials/api-integration-guide) — Step 4 settlement configuration
- [About Fluxis](/docs/introduction/about) — supported networks and settlement scope