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
| Status | Description |
|---|---|
MATCHED | The record was automatically matched to a counterpart |
UNMATCHED | The record could not be automatically matched |
IGNORED | The record has been intentionally excluded from reconciliation |
REMATCH | The 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
| Parameter | Description |
|---|---|
tenantId | Filter by tenant ID |
institutionId | Filter by institution ID |
matchTypes | Comma-delimited match types to include |
excludeMatchTypes | Comma-delimited match types to exclude |
recordType | Filter by record type (TX, SUM, BAL) |
status | Filter by recon status: MATCHED, UNMATCHED, IGNORED, REMATCH |
dateFromIncl | Start of date range (ISO 8601, inclusive) |
dateToExcl | End of date range (ISO 8601, exclusive) |
currency | Filter by ISO 3-letter currency code |
differenceFrom | Filter for results where the absolute difference exceeds this amount |
cardId | Filter by card ID |
snapshotDate | Read the frozen snapshot taken on this date (yyyy-MM-dd) instead of the live results |
limit | Page size (default: 50) |
offset | Pagination 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.
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.
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
| Parameter | Description |
|---|---|
tenantId | Filter by tenant ID |
institutionId | Filter by institution ID |
matchTypes | Comma-delimited match types to include |
status | Filter by status |
dateFromIncl | Start of date range |
dateToExcl | End of date range |
currency | Filter by currency |
aggregation | Aggregation bucket: HOUR, DAY, WEEK, MONTH (default: DAY) |
groupByTenantId | Boolean — group results by tenant (default: false) |
groupByInstitutionId | Boolean — group results by institution (default: false) |
snapshotDate | Summarise 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.
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/jsonRequest body:
{
"status": "IGNORED",
"comment": "Confirmed duplicate entry from upstream feed — safe to exclude"
}| Field | Required | Description |
|---|---|---|
status | Yes | New status: MATCHED, UNMATCHED, IGNORED, or REMATCH |
comment | No | Free-text note recorded against the result for audit purposes |
Response: The full updated ReconResult object.
Requires Recons.UPDATE.Allowed permission.
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 }format | Sent as | fileName must match |
|---|---|---|
BANK_GENERIC | tenantId, accountNumber, currency, plus transactions and/or closingBalances | Letters, digits, ., _, -, up to 100 characters |
SBSA_POOL_ACCOUNT | The bank's MT940 file in base64EncodedSource | MT940_*.txt |
SBSA_SUSPENSE_ACCOUNT | The bank's suspense CSV in base64EncodedSource | BaaS_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_GENERICtransactions 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).
| Parameter | Description |
|---|---|
tenantId, institutionId | Filter by tenant or institution |
recordType | TX, SUM or BAL |
transactionTypes, transactionTypeStartsWith | Comma-delimited transaction types, or a prefix |
dataSourceLocation, dataSourceLocationStartsWith | Where the record came from, or a prefix |
poolAccountNumber, walletAccountNumber, walletId, cardId | Filter by account, wallet or card |
currency, drCrIndicator | Filter by currency or debit/credit |
dateFromIncl, dateToExcl | Transaction date range (balance records have no transaction date) |
balanceDateFromIncl, balanceDateToExcl | Balance date range, yyyy-MM-dd (balance records only) |
matchingHint, internalUniqueId, externalUniqueId | Exact 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:
-
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:00ZCompare the
countonUNMATCHEDrows againstMATCHEDrows to gauge the mismatch volume. -
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 -
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:
PUTwithstatus: "IGNORED"and acommentexplaining the reason. - If it requires re-running the matching algorithm:
PUTwithstatus: "REMATCH".
- If it is a known duplicate or correctly excludable:
-
Re-run the summary to confirm the unmatched count has reduced as expected.
-
Remove confirmed false positives from the day's snapshot if your reporting uses snapshots (see Remove a Result from a Snapshot).
Permissions Required
| Permission | Description |
|---|---|
Recons.READ.Allowed | Read recon results, summaries and records |
Recons.UPDATE.Allowed | Update a recon result, or remove one from a snapshot |
BankStatements.CREATE.Allowed | Load a bank statement |
Updated 26 days ago
