Settlement & Liquidity

Beetles features a native engine for managing the lifecycle of money — from the moment a transaction is initiated until it becomes fully liquid and available for payout.

Balance Types

Beetles tracks two primary states for every account:

Available Balance

Represents the liquid funds that can be spent or withdrawn immediately. This balance is updated only when a transaction has been fully settled.

Available = credits_posted - debits_posted

Pending Balance (Receivables)

Represents funds that are guaranteed to arrive but are currently locked due to processing times, credit card settlement periods, or escrow terms.

Pending = credits_pending - debits_pending

Settlement Cycles

You can define how and when funds move from "Pending" to "Available" using three core modes:

1. Instant Settlement

Funds move directly between accounts and become available immediately. Ideal for internal wallet transfers or peer-to-peer payments.

{
  "amount": 10000,
  "code": 1
}

2. Authorization & Capture (Escrow)

Funds are "Reserved" (Pending) from the source account. They remain in a locked state until your application explicitly Captures them (moves to Available) or Voids them (returns to source).

Create a pending transfer

{
  "amount": 10000,
  "pending": true,
  "timeout": 3600
}

Then resolve:

Capture: POST /transfers/{id}/confirm
Void: POST /transfers/{id}/void
Auto-void: If timeout expires, the hold is released automatically.

3. Scheduled Settlement (Receivables)

Ideal for card processing and marketplaces. When a sale occurs, funds are registered as "Pending". Beetles automatically moves them to "Available" after a predefined date.

D+30 settlement

{
  "amount": 10000,
  "settlement_date": "2025-03-15T12:00:00Z"
}

Beetles uses durable workflows to automatically post the transfer on the settlement date.

Dispute & Reversal Logic

Financial systems must handle exceptions gracefully. Beetles provides native primitives for:

Scenario	Mechanism
Chargeback before settlement	`POST /transfers/{id}/void` — clean reversal of the pending transfer
Chargeback after settlement	New reverse transfer with `balancing_debit` flag — debits up to available balance
Partial reversal	Capture with a reduced `amount`
Overdraft protection	Account flag `debits_must_not_exceed_credits` prevents negative balances

Example: Card Payment (D+30)

Day 0:  Sale of $100 → Merchant's Pending Balance +$100
Day 1-29: Funds visible in reports but unavailable
Day 30: Beetles auto-posts → Pending -$100, Available +$100

Early capture (prepayment/anticipation) is supported — just call POST /transfers/{id}/confirm before the settlement date. The workflow handles the rest.

Settlement & Liquidity

On this page