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:

FigureWhere it comes from
Expected amountThe sum of every CHARGE entry in the internal ledger for that period and currency.
Reconciled amountThe sum of every successful payment transaction recorded for that period and currency, populated from payment-processor events.
Precise scope: the comparison is made against payment transactions recorded from processor webhook events, not against the processor’s payout or balance-transaction API. It answers "does our ledger agree with the payments we were told succeeded?" It does not by itself prove funds landed in a specific bank account, which remains a bank-statement reconciliation step.

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 |  <=  tolerance

Tolerance 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

StatusMeaningIn use today
RECONCILEDThe two figures matched within tolerance. This is a final state and cannot be retried.Yes
FAILEDThe figures disagreed. Stores the difference in lastError, and is eligible for retry.Yes
PENDINGReserved in the data model for a future queued-reconciliation flow.Not currently assigned
RETRYINGReserved in the data model for a future in-flight retry state.Not currently assigned
Reconciliation writes its result immediately, so in practice a record is created directly as either RECONCILED or FAILED. PENDING and RETRYING exist in the schema but are not written by any current code path. They are listed here for completeness so that nobody builds logic expecting them.

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 } ]
}
Important limitation on exchange rates. Currency conversion currently uses a fixed internal rate table covering USD, EUR and GBP only. Those rates are constants in the application, not live market rates, and they do not refresh. Any converted cross-currency total is therefore an approximation suitable for an internal dashboard figure. It should not be used as the basis for financial reporting, invoicing, or a filed account without first connecting a real rate source and recording the rate used at the time of conversion. Requesting a currency outside the supported three returns an explicit error rather than a wrong number.

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.

What this check proves. Verification does two things for every entry, per currency: recomputes its hash from its own stored fields, which catches an entry edited in place(including a direct database update that bypassed the application), and confirms its recorded previous-hash actually matches its real predecessor's hash, which catches an entry that was deleted, inserted, or reordered. A tamperer would need to recompute every hash from the point of tampering forward for a change to go undetected, the same limitation any hash chain has.

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.

Chargeback entries reduce the account balance, but are deliberately excluded from the settlement comparison, which sums original charges only. A disputed charge therefore stays visible as a reconciled charge plus a separate reversal, rather than quietly disappearing from the settlement history.

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
ExportFormatColumns
SettlementCSVid, periodStart, periodEnd, currency, expectedAmount, reconciledAmount, status, attempts, lastError, createdAt
LedgerJSON or CSVid, type, amount, balanceAfter, referenceType, referenceId, createdAt
Dates are ISO-8601 and amounts are integer minor units in both exports. The ledger export does not currently include the hash, previous-hash, or currency columns, so if you need to independently re-verify the chain outside the platform, request those fields be added rather than assuming the export is sufficient for that purpose.

12. Endpoint reference

All settlement endpoints require an API key with the settlement scope; ledger endpoints require the ledger scope.

EndpointWhat it does
GET /settlement/summaryCounts of total, reconciled, and failed records, plus the last reconciled timestamp.
GET /settlementLists settlement records, newest first. Default 100, maximum 1000.
POST /settlement/reconcileReconciles one period for one currency and creates or updates a record.
POST /settlement/reconcile-allReconciles one period across every currency with activity.
POST /settlement/reconcile-all/totalReturns one combined figure converted into a target currency.
GET /settlement/exportCSV export of settlement history.
POST /settlement/:id/retryRe-checks one failed record. Supports Idempotency-Key.
POST /settlement/bulk-retryRe-checks up to 100 records in one request.
GET /ledger/balanceCurrent balance for one currency.
GET /ledger/balance/totalBalances across currencies, converted and summed.
GET /ledger/entriesRecent ledger entries.
GET /ledger/verifyVerifies the hash chain, as described in section 8.
GET /ledger/exportJSON or CSV export of ledger entries.
The three 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?