Balance & ledger
Each merchant has a balance per currency, split into three buckets:
| Bucket | Meaning |
|---|---|
available | Withdrawable now. Ready for the next payout batch. |
pending | Charged but not yet released. Moves to available once settled. |
reserved | Held against open chargeback risk. Released back to available after the dispute window. |
All amounts are signed BigInt minor units — 12550 for TRY = ₺125.50. Never use Number for money in your client code; the API returns these as strings to avoid float rounding.
The ledger
Every balance change is recorded as one or more append-only LedgerEntry rows tagged with a shared balanceTransactionId. Common patterns:
| Event | Entries |
|---|---|
| Charge succeeds | deposit_credit (gross) + fee_debit (our fee) |
| Pending → available | reserve_release |
| Crypto payout | payout_debit |
| Refund | refund_debit |
| Manual adjustment | adjustment (back-office only) |
The sum of all LedgerEntry.amountMinor for an org+currency, by bucket, equals the current Balance row. This invariant is what reconciliation checks every morning.
Settlement timing
Lidya targets T+1 settlement — the gross funds from charges that succeed today are available tomorrow morning at 03:00 UTC, after which the daily payout batch goes out. Each merchant's reserve schedule may shift this depending on KYC tier and risk tier.