Reconciliation Rail

Reconciliation Rail

Transaction reconciliation, matching, and exception handling.

Overview

The Reconciliation Rail provides endpoints for reconciling transactions across systems, automated matching, and managing reconciliation exceptions.

Base URL

/api/v1/reconciliation

Endpoints

Create Reconciliation Job

POST /api/v1/reconciliation/jobs

Create a new reconciliation job.

Request Body:

{
  "name": "Daily Bank Reconciliation",
  "type": "BANK_STATEMENT",
  "sourceSystem": "CORE_BANKING",
  "targetSystem": "BANK_FEED",
  "matchingRules": ["AMOUNT_EXACT", "DATE_RANGE", "REFERENCE_FUZZY"],
  "dateRange": {
    "from": "2025-01-14",
    "to": "2025-01-14"
  },
  "tolerance": {
    "amount": "0.01",
    "dateDays": 1
  }
}

Response:

{
  "data": {
    "jobId": "rec_abc123",
    "status": "PENDING",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Run Job

POST /api/v1/reconciliation/jobs/:jobId/run

Execute reconciliation job.

Response:

{
  "data": {
    "jobId": "rec_abc123",
    "status": "COMPLETED",
    "summary": {
      "sourceCount": 1500,
      "targetCount": 1498,
      "matchedCount": 1480,
      "unmatchedSource": 20,
      "unmatchedTarget": 18,
      "matchRate": 0.987,
      "totalAmount": "15000000.00",
      "matchedAmount": "14750000.00"
    },
    "completedAt": "2025-01-15T10:05:00Z"
  }
}

Get Job Status

GET /api/v1/reconciliation/jobs/:jobId

Get job status and summary.

List Jobs

GET /api/v1/reconciliation/jobs

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
type	string	Filter by type
dateFrom	string	Date range start

Get Exceptions

GET /api/v1/reconciliation/jobs/:jobId/exceptions

Get unmatched items (exceptions).

Response:

{
  "data": [
    {
      "exceptionId": "exc_123",
      "type": "UNMATCHED_SOURCE",
      "sourceRecord": {
        "transactionId": "txn_abc",
        "amount": "5000.00",
        "date": "2025-01-14",
        "reference": "PAY-001"
      },
      "possibleMatches": [
        {
          "recordId": "bank_xyz",
          "amount": "5000.00",
          "date": "2025-01-15",
          "matchScore": 0.85
        }
      ]
    }
  ]
}

Resolve Exception

POST /api/v1/reconciliation/exceptions/:exceptionId/resolve

Resolve an exception.

Request Body:

{
  "resolution": "MANUAL_MATCH",
  "matchedRecordId": "bank_xyz",
  "notes": "Date difference due to weekend processing"
}

Upload Statement

POST /api/v1/reconciliation/statements

Upload a bank statement for reconciliation.

Request Body (multipart/form-data):

file: statement.csv
format: CSV
bankCode: SABB
accountNumber: 1234567890

Create Matching Rule

POST /api/v1/reconciliation/rules

Create custom matching rule.

Request Body:

{
  "name": "Amount + Reference Match",
  "priority": 100,
  "conditions": [
    { "field": "amount", "operator": "EQUALS" },
    { "field": "reference", "operator": "CONTAINS" }
  ],
  "tolerance": {
    "amountPercent": 0.01
  }
}

Job Types

Type	Description
BANK_STATEMENT	Bank statement reconciliation
INTERCOMPANY	Intercompany transactions
NOSTRO	Nostro account reconciliation
CARD_SETTLEMENT	Card settlement reconciliation
CUSTOM	Custom reconciliation

Matching Operators

Operator	Description
EQUALS	Exact match
CONTAINS	Contains substring
FUZZY	Fuzzy matching
RANGE	Within range
REGEX	Regular expression

Exception Types

Type	Description
UNMATCHED_SOURCE	No match in target
UNMATCHED_TARGET	No match in source
AMOUNT_MISMATCH	Amounts differ
DATE_MISMATCH	Dates differ
DUPLICATE	Duplicate records

Resolution Types

Resolution	Description
MANUAL_MATCH	Manual matching
IGNORE	Ignore exception
ADJUST	Create adjustment
INVESTIGATE	Mark for investigation

Events

Event	Description
reconciliation.job.started	Job started
reconciliation.job.completed	Job completed
reconciliation.exception.created	Exception found
reconciliation.exception.resolved	Exception resolved

See Also

• Clearing Rail - Settlement
• Reporting Rail - Reports