Settlement System
How the platform checks that the money it recorded as charged actually arrived, how mismatches are surfaced and retried, and how the financial record is protected against silent modification.
1. What settlement actually does
Every charge the platform makes is written to an internal ledger. Separately, the payment processor reports back what it actually collected. Settlement is the process of comparing those two numbers for a given period and currency, and recording whether they agree.
Concretely, for one account, one currency, and one date range, it compares:
| Figure | Where it comes from |
|---|---|
| Expected amount | The sum of every CHARGE entry in the internal ledger for that period and currency. |
| Reconciled amount | The sum of every successful payment transaction recorded for that period and currency, populated from payment-processor events. |
2. The match test and tolerance
A period is marked reconciled when the difference between the two figures is within the configured tolerance:
| expectedAmount - reconciledAmount | <= toleranceTolerance is set by the SETTLEMENT_TOLERANCE_CENTS environment variable and defaults to 0, meaning an exact match is required. Raising it above zero is a deliberate business decision to absorb rounding or fee differences, and should be documented if you change it, because it directly widens what counts as "correct".
When the figures disagree, the record is marked failed and stores a human-readable reason, for example:
Expected 59700 but processor settled 39800 (difference: 19900)All amounts are integer minor units, so 59700 means $597.00.
3. Settlement record statuses
| Status | Meaning | In use today |
|---|---|---|
| RECONCILED | The two figures matched within tolerance. This is a final state and cannot be retried. | Yes |
| FAILED | The figures disagreed. Stores the difference in lastError, and is eligible for retry. | Yes |
| PENDING | Reserved in the data model for a future queued-reconciliation flow. | Not currently assigned |
| RETRYING | Reserved in the data model for a future in-flight retry state. | Not currently assigned |
4. What happens when settlement fails
A failed settlement is not just a row in a table. It has real downstream consequences:
- The failure is written to the audit log, so there is a permanent record of when it was detected.
- A Slack alert is sent, if a Slack webhook is configured, so the failure is noticed rather than sitting unread in a dashboard.
- A webhook event is dispatched to any endpoint you have subscribed, so your own systems can react.
- Repeated, unresolved failure feeds the dunning process, which escalates from reminder, to final notice, to account suspension.
The dunning link is the important one: settlement is not a passive report. Left unresolved, it is what eventually suspends a non-paying account. See Billing for the escalation timing.
5. Retrying a failed settlement
Retrying does not re-attempt a payment or contact the card network. It recomputes both figures from current data for that record’s own period and currency, then updates the status. It exists because the usual cause of a mismatch is a timing gap, a payment event that had not yet been recorded when reconciliation first ran.
# Retry a single settlement record
curl -X POST https://portal.orenyxengine.com/api/v1/settlement/SETTLEMENT_ID/retry \
-H "x-api-key: your_api_key_here" \
-H "Idempotency-Key: unique-retry-id-001"
# Retry many at once (maximum 100 ids per request)
curl -X POST https://portal.orenyxengine.com/api/v1/settlement/bulk-retry \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"ids": ["rec_1", "rec_2", "rec_3"]}'- Each retry increments an attempt counter, so you can see how many times a period has been re-checked.
- A successful retry clears the stored error; a repeated failure overwrites it with the current difference.
- Bulk retry is error-isolated: one bad id returns an error for that id only and does not abort the rest of the batch.
- Single retry honors the Idempotency-Key header, so a network timeout cannot cause a double retry. Bulk retry does not currently support idempotency keys.
- Retrying an already-reconciled record is rejected, since there is nothing to correct.
6. Automatic nightly reconciliation
Reconciliation runs automatically once per day at 03:30 server time, covering the previous calendar day for every active account, one record per currency that had activity. A failure while processing one account does not stop the others.
The API endpoints described below are for on-demand reconciliation of an arbitrary period, and are independent of the nightly run.
7. Multi-currency handling
Reconciliation is per currency, not blended. The system finds every currency that had ledger or payment activity in the period and produces a separate record for each, so a mismatch in one currency cannot be masked by a surplus in another.
A separate endpoint converts every currency’s reconciled amount into one chosen target currency to give a single combined figure.
curl -X POST "https://portal.orenyxengine.com/api/v1/settlement/reconcile-all/total?periodStart=2026-07-01&periodEnd=2026-08-01&targetCurrency=usd" \
-H "x-api-key: your_api_key_here"
# Response
{
"targetCurrency": "usd",
"total": 0,
"byCurrency": [ { "currency": "usd", "reconciledAmount": 0 } ]
}8. The ledger and its integrity check
Every financial movement is appended to a ledger. Each entry stores a running balance and a SHA-256 hash computed over the entry’s own fields plus the hash of the entry before it, forming a chain per account and currency.
hash = SHA256( previousHash : accountId : type : amount : referenceType : referenceId : balanceAfter )You can ask the platform to verify that chain at any time:
curl https://portal.orenyxengine.com/api/v1/ledger/verify -H "x-api-key: your_api_key_here"
# Response when intact
{ "valid": true, "brokenAtEntryId": null }This runs automatically every hour across all accounts. A failure writes an audit-log record and sends a Slack alert, so corruption is surfaced rather than waiting to be discovered.
9. Concurrency safety
Two payments settling at the same instant could otherwise each read the same "previous" entry and write conflicting balances. To prevent that, every ledger write takes a database advisory lock keyed to the account and currency, inside the same transaction that reads the previous entry and inserts the new one. Writes for the same account and currency are therefore serialized, while writes for different accounts or currencies still run in parallel.
This was verified under load with thousands of concurrent writes, confirming balances and the hash chain remained consistent.
10. Chargebacks and disputes
When the payment processor reports that a cardholder disputed a charge, the platform matches the dispute to the original payment transaction and appends a CHARGEBACK ledger entry with a negative amount, in the original currency, referencing the transaction it reverses. Disputes raised in the processor’s test mode are recorded at zero so test activity cannot distort a real balance.
11. Exporting settlement and ledger data
For accounting review or an external audit, both records can be exported.
# Settlement history, CSV
curl "https://portal.orenyxengine.com/api/v1/settlement/export" -H "x-api-key: your_api_key_here" -o settlement.csv
# Ledger, JSON or CSV
curl "https://portal.orenyxengine.com/api/v1/ledger/export?format=csv" -H "x-api-key: your_api_key_here" -o ledger.csv| Export | Format | Columns |
|---|---|---|
| Settlement | CSV | id, periodStart, periodEnd, currency, expectedAmount, reconciledAmount, status, attempts, lastError, createdAt |
| Ledger | JSON or CSV | id, type, amount, balanceAfter, referenceType, referenceId, createdAt |
12. Endpoint reference
All settlement endpoints require an API key with the settlement scope; ledger endpoints require the ledger scope.
| Endpoint | What it does |
|---|---|
| GET /settlement/summary | Counts of total, reconciled, and failed records, plus the last reconciled timestamp. |
| GET /settlement | Lists settlement records, newest first. Default 100, maximum 1000. |
| POST /settlement/reconcile | Reconciles one period for one currency and creates or updates a record. |
| POST /settlement/reconcile-all | Reconciles one period across every currency with activity. |
| POST /settlement/reconcile-all/total | Returns one combined figure converted into a target currency. |
| GET /settlement/export | CSV export of settlement history. |
| POST /settlement/:id/retry | Re-checks one failed record. Supports Idempotency-Key. |
| POST /settlement/bulk-retry | Re-checks up to 100 records in one request. |
| GET /ledger/balance | Current balance for one currency. |
| GET /ledger/balance/total | Balances across currencies, converted and summed. |
| GET /ledger/entries | Recent ledger entries. |
| GET /ledger/verify | Verifies the hash chain, as described in section 8. |
| GET /ledger/export | JSON or CSV export of ledger entries. |
reconcile endpoints are POST requests, matching what they actually do: each one creates or updates a record, sends webhooks, and writes an audit entry. Re-reconciling the same account, period, and currency does not create a duplicate record, it updates the existing one and increments its attempt count, this is enforced by a uniqueness constraint at the database level, not just application logic.Was this page helpful?