Settlements

A settlement is a merchant-level aggregation of financial statements. Financial statements are generated first (daily, per terminal + currency). The settlement then collects all relevant statements for a merchant and currency, adds any manual adjustments, and produces a single merchant-facing document for the period.

How Settlements Work

The system periodically generates a settlement for each merchant and currency combination:

1. Financial statements are generated first (daily cron, per terminal + currency).
2. The settlement process selects a merchant, currency, and settlement period.
3. All unpaid financial statements for that merchant and period are collected.
4. Transaction volumes, fees, and rolling reserve are aggregated across the collected statements (1:N).
5. Any manual adjustments are applied.
6. The net amount is computed, producing the final merchant-facing document.
7. On finalization, the linked financial statements transition to paid status, preventing re-inclusion in future settlements.

Settlement Breakdown

Each settlement record contains a full financial breakdown for the period:

Revenue:

• Captured payment volume (gross)
• Chargeback reversals (if any)

Deductions:

• Refund volume
• Chargeback volume

Costs:

• Merchant fee (total fees charged to the merchant)
• Fee breakdown: provider fee, platform fee, tenant fee, partner commission
• Recurrent fees (subscription/access fees, if applicable)

Reserves:

• Rolling reserve held (new reserve withheld from this period)
• Rolling reserve released (reserve from prior periods returned)

Adjustments:

• Manual adjustments with a mandatory reason
• Each adjustment has an adjustmentDirection field:
  • credit — adds to the merchant's net (e.g., goodwill compensation, correction in merchant's favor)
  • debit — subtracts from the merchant's net (e.g., recovery of overpayment, penalty)
  • null — no adjustment for this settlement

Net to merchant:

netToMerchant = grossVolume - refundVolume - chargebackVolume
                - merchantFee
                - rollingReserveHeld + rollingReserveReleased
                - recurrentFees
                + adjustment (if credit) or - adjustment (if debit)

Settlement Configuration

Settlement generation frequency and the T+N availability delay are configured per merchant and currency. An operator sets this during merchant onboarding or updates it later.

Available frequencies: daily, weekly, biweekly.

To configure:

1. Open the Portal and navigate to the merchant's settings.
2. Go to the settlement configuration section.
3. Set the desired availability delay (T+1 through T+14), generation frequency, and auto-finalize preference.
4. Save. Changes apply to the next settlement cycle.

One configuration exists per merchant + currency combination.

Viewing Settlements

In the Portal, navigate to the Settlements section to see all settlement records.

Each record shows:

• Period: the date range covered (UTC)
• Currency: the settlement currency
• Gross volume: total captured transaction amount
• Fees: total merchant fee for the period
• Net: amount credited to the merchant's available balance
• Status: current settlement status

Click a settlement to view its full breakdown, fee decomposition, and linked financial statements (per-terminal details).

Settlement Statuses

Once a settlement is finalized, it cannot be modified. If a correction is needed after finalization, the operator creates a new adjustment settlement linked to the original.

Generation Modes

Automatic (periodic):

• Runs at the scheduled time (daily at 00:00 UTC by default).
• Creates a settlement in draft status, then auto-finalizes it (if auto-finalize is enabled).
• The merchant sees the financial statement in their dashboard.

Manual (on-demand):

• An operator selects a merchant, period, and currency.
• The system calculates a preview in draft status.
• The operator reviews and finalizes.

Adjustment Settlements

If a finalized settlement needs correction, do not modify the original. Instead:

1. Create a new adjustment settlement linked to the original (linkedSettlementId).
2. Specify the adjustment amount, direction (credit or debit), and reason.
3. Finalize the adjustment settlement.

The adjustment appears as a separate record in the merchant's settlement history.

Availability Transition

The Availability Transition is a separate automated process that moves funds from the pending balance bucket to available. It runs as a daily cron job independent of settlement document generation.

• Each captured transaction has an availability date calculated as T+N business days after capture (where N is the merchant's configured availability delay).
• The daily cron job finds all pending ledger entries where the availability date has passed and transitions them to available.
• Business days skip weekends (Saturday/Sunday).
• The cut-off time is UTC midnight (00:00 UTC).

The Availability Transition makes funds eligible for withdrawal. It does not produce any documents or statements — that is what the settlement does.

Key Points

• A settlement is a merchant-level aggregation of financial statements (1:N). Statements are per-terminal; settlements are per-merchant.
• Financial statements are generated first (daily cron). Settlements then collect and aggregate them.
• The Availability Transition (T+N pending-to-available) is a separate daily cron job, not part of the settlement.
• Settlement does NOT send money to the merchant's bank account — that is a withdrawal.
• Settlement does NOT trigger payouts — payouts are a separate merchant service.
• Adjustments exist only at the settlement level, not on individual financial statements.
• Finalized settlements are immutable. Use adjustment settlements for corrections.