---
updatedAt: 2026-05-19T20:32:49.000Z
agentTools:
  projectIndex: https://developer.eftcorp.com/llms.txt
---

# 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 `Recon.READ.Allowed` permission.

```http
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                                             |
| `matchType`      | Filter by match type                                                 |
| `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 |
| `limit`          | Page size (default: `50`)                                            |
| `offset`         | Pagination offset (default: `0`)                                     |

**Response:**

```json
[
  {
    "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 →](https://developer.eftcorp.com/reference/get_rest-v1-recons-results)

***

## Get a Specific Reconciliation Result

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

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

[API Reference →](https://developer.eftcorp.com/reference/get_rest-v1-recons-results-reconresultid)

***

## Get a Reconciliation Summary

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

```http
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                                            |
| `matchType`            | Filter by match type                                                |
| `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`)           |

**Response:**

```json
[
  {
    "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 →](https://developer.eftcorp.com/reference/get_rest-v1-recons-summaries)

***

## 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.

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

**Request body:**

```json
{
  "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 `Recon.UPDATE.Allowed` permission.

[API Reference →](https://developer.eftcorp.com/reference/put_rest-v1-recons-results-reconresultid)

***

## 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.

***

## Permissions Required

```
Recon.READ.Allowed
Recon.UPDATE.Allowed
```