Reconciliation

Reconciliation matches the gateway's settlement records against the payments the service confirmed, surfacing any discrepancy for an operator to investigate.

Both endpoints below are admin session-authenticated and gated by the report:read authority. Reconciliation is a cross-app system view, so there is no app-scope narrowing — a run spans every LIVE app at once and each result carries its owning applicationId for attribution. See RBAC for the authority model and app isolation for the usual per-app rule this view intentionally steps outside of.

All responses use the standard envelope: { "data": …, "meta": { "success": true, … }, "pagination": … }. The sections below show only the data payload.

How a run classifies each item

A run matches the gateway settlement rows for a period against the internal LIVE payments that settled in that period. The match is keyed on the transactionRef (the payment reference echoed in the settlement report). Settlement rows are indexed and consumed as internal payments match them, so whatever is left over was present in settlement but not internally. An internal payment with no settlement row that settled within a configurable timing tolerance of the day's cutoff (default 6 hours) is DEFERRED — its settlement may simply lag to the next cycle — otherwise it is MISSING_IN_SETTLEMENT.

Reconciliation statuses

ReconciliationStatus has exactly five values. (There is no FLAGGED status — "flagged" describes the four non-MATCHED outcomes collectively.)

Trigger a run — POST /admin/reconciliation/runs

Reconciles the already-imported settlement records for one period (the same sweep the daily scheduler runs) and returns the run tally. period is a required ISO date (yyyy-MM-dd) query parameter; gated by report:read. Re-running a period is naturally idempotent — the run deletes that period's prior (derived) results and recomputes them.

curl -X POST "http://localhost:8080/api/v1/admin/reconciliation/runs?period=2026-06-29" \
  -H "Authorization: Bearer SESSION_TOKEN"

The data payload is a ReconciliationRunSummary:

{
  "data": {
    "period": "2026-06-29",
    "matched": 412,
    "missingInSettlement": 1,
    "missingInternal": 0,
    "amountMismatch": 2,
    "deferred": 7,
    "ledgerBalanced": true
  },
  "meta": {
    "success": true,
    "message": null,
    "errorCode": null,
    "timestamp": "2026-06-30T02:00:00Z"
  },
  "pagination": null
}

Run summary fields

List results — GET /admin/reconciliation/results

Lists the per-item outcomes of the daily run — paginated and filterable by mode, period, and status. Gated by report:read.

curl "http://localhost:8080/api/v1/admin/reconciliation/results?period=2026-06-29&status=AMOUNT_MISMATCH&page=0&size=20" \
  -H "Authorization: Bearer SESSION_TOKEN"

The data payload is a list of ReconciliationResultDto; pagination carries the page metadata:

{
  "data": [
    {
      "id": 90431,
      "mode": "LIVE",
      "period": "2026-06-29",
      "status": "AMOUNT_MISMATCH",
      "transactionRef": "TXN-7Y2K9QF4",
      "settlementRecordId": 5521,
      "paymentId": 88102,
      "paymentReference": "TXN-7Y2K9QF4",
      "applicationId": 1042,
      "expectedAmountMinor": 150000,
      "settledAmountMinor": 149500,
      "currency": "BDT",
      "detail": "Amount mismatch: internal 150000 vs settled 149500 (minor units)",
      "createdAt": "2026-06-30T02:00:01Z"
    }
  ],
  "meta": {
    "success": true,
    "message": null,
    "errorCode": null,
    "timestamp": "2026-06-30T02:05:00Z"
  },
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 2,
    "totalPages": 1
  }
}

Result fields

Either side may be absent: settlementRecordId is null when an internal payment had no settlement row; paymentId/paymentReference are null when a settlement row had no internal payment.

Scheduled runs

A run executes automatically every day at 02:00 UTC, reconciling the previous day's cycle (by which point that day's settlement report has been imported — fetching the report from the gateway is an out-of-band ops action). A failed nightly run is logged and swallowed so one bad night never kills the scheduler; the next cycle simply tries again. Trigger an on-demand run with POST /admin/reconciliation/runs (above) when you need to re-reconcile a period after a late import.

Related