Reconciliation Use Cases

Querying and managing reconciliation results across payment transactions.

Eclipse provides a reconciliation service that matches internal platform transaction records against external settlement and bank statement records. This enables operators and tenants to identify and resolve unmatched transactions.


Reconciliation Result Statuses

StatusDescription
MATCHEDThe record was automatically matched to a counterpart
UNMATCHEDThe record could not be automatically matched
IGNOREDThe record has been intentionally excluded from reconciliation
REMATCHThe record has been flagged for re-processing by the reconciliation engine

Query Reconciliation Results

Retrieve individual transaction-level recon results, optionally filtered by status, date, institution, or currency.

Prerequisites: A valid bearer token with Recons.READ.Allowed permission.

GET /rest/v1/recons/results
    ?tenantId={tenantId}
    &dateFromIncl={date}
    &dateToExcl={date}
    &status=UNMATCHED
    &limit=50
    &offset=0
Authorization: Bearer {jwt}

Query Parameters

ParameterDescription
tenantIdFilter by tenant ID
institutionIdFilter by institution ID
matchTypesComma-delimited match types to include
excludeMatchTypesComma-delimited match types to exclude
recordTypeFilter by record type (TX, SUM, BAL)
statusFilter by recon status: MATCHED, UNMATCHED, IGNORED, REMATCH
dateFromInclStart of date range (ISO 8601, inclusive)
dateToExclEnd of date range (ISO 8601, exclusive)
currencyFilter by ISO 3-letter currency code
differenceFromFilter for results where the absolute difference exceeds this amount
cardIdFilter by card ID
snapshotDateRead the frozen snapshot taken on this date (yyyy-MM-dd) instead of the live results
limitPage size (default: 50)
offsetPagination offset (default: 0)

Response:

[
  {
    "reconResultId": 1028374,
    "tenantId": 42,
    "institutionId": "7",
    "transactionDate": "2026-05-18T14:30:00.000Z",
    "difference": 750.00,
    "currency": "ZAR",
    "status": "UNMATCHED",
    "matchType": "AMOUNT_DATE",
    "recordType": "TX",
    "description": "No matching counterpart record found",
    "comment": "",
    "created": "2026-05-18T14:30:05.000Z",
    "recordA": {
      "reconRecordId": 7741,
      "recordType": "TX",
      "transactionDate": "2026-05-18T14:30:00.000Z",
      "transactionAmount": 750.00,
      "transactionCurrency": "ZAR",
      "normalisedAmount": 750.00,
      "normalisedCurrency": "ZAR",
      "internalUniqueId": "wdr-00001234",
      "externalUniqueId": "ext-ref-abcd",
      "dataSourceLocation": "wallet-service",
      "dataSourceId": 3,
      "matchingHint": "750.00|2026-05-18"
    },
    "recordB": null
  }
]

recordA is the Eclipse-side record. recordB is the external (e.g. bank statement) counterpart — null when no match has been found.

API Reference →


Get a Specific Reconciliation Result

GET /rest/v1/recons/results/{reconResultId}
Authorization: Bearer {jwt}

Response: Same structure as the list response, for a single result.

API Reference →


Get a Reconciliation Summary

Retrieve aggregated reconciliation statistics for a period. Useful for daily or monthly settlement review.

GET /rest/v1/recons/summaries
    ?tenantId={tenantId}
    &aggregation=DAY
    &dateFromIncl={date}
    &dateToExcl={date}
Authorization: Bearer {jwt}

Query Parameters

ParameterDescription
tenantIdFilter by tenant ID
institutionIdFilter by institution ID
matchTypesComma-delimited match types to include
statusFilter by status
dateFromInclStart of date range
dateToExclEnd of date range
currencyFilter by currency
aggregationAggregation bucket: HOUR, DAY, WEEK, MONTH (default: DAY)
groupByTenantIdBoolean — group results by tenant (default: false)
groupByInstitutionIdBoolean — group results by institution (default: false)
snapshotDateSummarise the frozen snapshot taken on this date (yyyy-MM-dd)

Response:

[
  {
    "timeBucket": "2026-05-18",
    "matchType": "AMOUNT_DATE",
    "recordType": "TX",
    "status": "MATCHED",
    "totalDifference": 0.00,
    "currency": "ZAR",
    "count": 1478,
    "tenantId": 42,
    "institutionId": "7"
  },
  {
    "timeBucket": "2026-05-18",
    "matchType": "AMOUNT_DATE",
    "recordType": "TX",
    "status": "UNMATCHED",
    "totalDifference": 1099.99,
    "currency": "ZAR",
    "count": 4,
    "tenantId": 42,
    "institutionId": "7"
  }
]

The summary returns one row per timeBucket / matchType / recordType / status combination. To assess overall reconciliation for a day, query for the period and compare the count across MATCHED vs UNMATCHED rows.

API Reference →


Update a Reconciliation Result

Operators can update the status or add a comment to a recon result — for example, to mark a record as IGNORED after manual investigation, or to flag it as REMATCH for re-processing.

PUT /rest/v1/recons/results/{reconResultId}
Authorization: Bearer {jwt}
Content-Type: application/json

Request body:

{
  "status": "IGNORED",
  "comment": "Confirmed duplicate entry from upstream feed — safe to exclude"
}
FieldRequiredDescription
statusYesNew status: MATCHED, UNMATCHED, IGNORED, or REMATCH
commentNoFree-text note recorded against the result for audit purposes

Response: The full updated ReconResult object.

Requires Recons.UPDATE.Allowed permission.

API Reference →


Remove a Result from a Snapshot

Each day's recon results are frozen into a snapshot. To take a break out of a snapshot, for example once it is shown to be a false positive, delete it from that snapshot. The live result is not changed, and a later snapshot picks it up again if it is still unreconciled.

DELETE /rest/v1/recons/snapshots/{snapshotDate}/results/{reconResultId}
Authorization: Bearer {jwt}

snapshotDate is yyyy-MM-dd. Returns 404 if that snapshot has no such result. Requires Recons.UPDATE.Allowed.


Load a Bank Statement

Load a statement by hand when it was not, or could not be, collected automatically.

POST /rest/v1/recons/bank-statements
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "format": "BANK_GENERIC",
  "fileName": "acme-collections-2026-10-22",
  "tenantId": 42,
  "accountNumber": "1234567890",
  "currency": "ZAR",
  "transactions": [
    { "date": "2026-10-22", "amount": 1500.00, "reference": "INV 1001", "transactionCode": "EFT", "uniqueId": "BNK-778812" },
    { "date": "2026-10-22", "amount": -250.00, "reference": "Bank charges" }
  ],
  "closingBalances": [
    { "date": "2026-10-22", "balance": 98250.00 }
  ]
}

Response (200 OK):

{ "format": "BANK_GENERIC", "fileName": "acme-collections-2026-10-22", "rowsRead": 3, "recordsWritten": 3, "rowsSkipped": 0 }
formatSent asfileName must match
BANK_GENERICtenantId, accountNumber, currency, plus transactions and/or closingBalancesLetters, digits, ., _, -, up to 100 characters
SBSA_POOL_ACCOUNTThe bank's MT940 file in base64EncodedSourceMT940_*.txt
SBSA_SUSPENSE_ACCOUNTThe bank's suspense CSV in base64EncodedSourceBaaS_VA_Suspense_*.csv

For BANK_GENERIC: transaction date is yyyy-MM-dd or an ISO 8601 date-time, amount is positive for credits and negative for debits, and reference, transactionCode and uniqueId (the bank's ID for the line) are optional. Closing balance date is yyyy-MM-dd.

Use the name the bank gave the file. Loading the same file again, or the automatic job later collecting it, overwrites the same records instead of duplicating them. A statement that fails validation writes nothing. Limits are 100,000 lines and 10 MB.

📘

Note

BANK_GENERIC transactions are stored and searchable, but no matcher reconciles them yet. Closing balances join the pool account balance recon only when the account is the tenant's pool account in that currency.

Requires BankStatements.CREATE.Allowed. The SBSA formats can span several tenants, so they are only permitted to roles granted in the global configuration.


Search Reconciliation Records

Records are the individual lines the matchers work on, from both sides, whether matched or not — for example every line of a loaded bank statement.

GET /rest/v1/recons/records
    ?tenantId={tenantId}
    &poolAccountNumber={accountNumber}
    &dateFromIncl={date}
    &dateToExcl={date}
    &limit=100
Authorization: Bearer {jwt}

At least one filter is required, and filters are combined. Results are newest first; limit is 1 to 1000 (default 50).

ParameterDescription
tenantId, institutionIdFilter by tenant or institution
recordTypeTX, SUM or BAL
transactionTypes, transactionTypeStartsWithComma-delimited transaction types, or a prefix
dataSourceLocation, dataSourceLocationStartsWithWhere the record came from, or a prefix
poolAccountNumber, walletAccountNumber, walletId, cardIdFilter by account, wallet or card
currency, drCrIndicatorFilter by currency or debit/credit
dateFromIncl, dateToExclTransaction date range (balance records have no transaction date)
balanceDateFromIncl, balanceDateToExclBalance date range, yyyy-MM-dd (balance records only)
matchingHint, internalUniqueId, externalUniqueIdExact match on these record fields

A single record is returned by GET /rest/v1/recons/records/{reconRecordId}. Both require Recons.READ.Allowed.


Typical Reconciliation Workflow

A typical end-of-day reconciliation workflow:

  1. Run the summary query to assess overall match rate for the day:

    GET /rest/v1/recons/summaries?tenantId=42&aggregation=DAY&dateFromIncl=2026-05-18T00:00:00Z&dateToExcl=2026-05-19T00:00:00Z

    Compare the count on UNMATCHED rows against MATCHED rows to gauge the mismatch volume.

  2. Pull the individual unmatched results for investigation:

    GET /rest/v1/recons/results?tenantId=42&status=UNMATCHED&dateFromIncl=2026-05-18T00:00:00Z&dateToExcl=2026-05-19T00:00:00Z
  3. For each unmatched result, review recordA (the Eclipse-side record) against your bank statement or settlement file:

    • If it is a known duplicate or correctly excludable: PUT with status: "IGNORED" and a comment explaining the reason.
    • If it requires re-running the matching algorithm: PUT with status: "REMATCH".
  4. Re-run the summary to confirm the unmatched count has reduced as expected.

  5. Remove confirmed false positives from the day's snapshot if your reporting uses snapshots (see Remove a Result from a Snapshot).


Permissions Required

PermissionDescription
Recons.READ.AllowedRead recon results, summaries and records
Recons.UPDATE.AllowedUpdate a recon result, or remove one from a snapshot
BankStatements.CREATE.AllowedLoad a bank statement

Did this page help you?