Reconciliation

Use the Reconciliation API to reconcile terminal transactions and retrieve detailed reconciliation reports.

Endpoint

Method: GET
URL: baseUrl/api/v1/transactions/terminal-reconciliation/{terminalId}

Headers

• Authorization: Bearer {{accessToken}} (Include the token obtained from the Authentication API)

Response

A successful request returns a JSON object containing reconciliation details:

Field	Type	Description
success	Boolean	Indicates if the reconciliation process was successful.
message	String	Human-readable status message of the reconciliation.
data.id	Integer	Unique identifier for the reconciliation attempt.
data.bankId	String	Code of the acquiring bank (e.g., RAJB).
data.merchantId	String	Unique merchant identifier assigned by the bank.
data.madaTerminalId	String	Terminal ID used for the Mada network.
data.mcc	String	Merchant Category Code (MCC).
data.stan	String	System Trace Audit Number — a unique identifier for the reconciliation request.
data.version	String	Version of the reconciliation protocol or application used.
data.rrn	String	Retrieval Reference Number associated with the reconciliation session.
data.transactionTypeEn	String	Transaction type in English (e.g., "Reconciliation").
data.transactionTypeAr	String	Transaction type in Arabic (e.g., "موازنة").
data.status	String	Describes reconciliation status (e.g., "COMPLETED IN BALANCE").
data.startDateTime	String (timestamp)	Start time of the reconciliation session (UNIX epoch in milliseconds).
data.endDateTime	String (timestamp)	End time of the reconciliation session.
data.scheduledTime	String / null	If reconciliation was scheduled, this shows the scheduled time.
data.executionTime	String / null	Actual time of execution if scheduled.
data.reconTotals	Array	List of scheme-wise totals from both host and terminal for reconciliation.

Response Example:

{
  "success": true,
  "message": "Reconciliation success",
  "data": {
    "id": 108,
    "bankId": "RAJB",
    "merchantId": "123456789123",
    "madaTerminalId": "1234567891234567",
    "mcc": "4900",
    "stan": "000138",
    "version": "1.2.57",
    "rrn": "514712140284",
    "transactionTypeEn": "Reconciliation",
    "transactionTypeAr": "موازنة",
    "status": "RECONCILIATION COMPLETED IN BALANCE",
    "startDateTime": "1748341289985",
    "endDateTime": "1748341290985",
    "scheduledTime": null,
    "executionTime": null,
    "reconTotals": [
      {
        "id": null,
        "channel": {
          "id": 1,
          "nameAr": "",
          "nameEn": "mada HOST"
        },
        "cardScheme": {
          "id": "P1",
          "nameEn": "mada",
          "nameAr": null
        },
        "countCr": 1,
        "countDb": 0,
        "totalAmountCr": 10000,
        "totalAmountDb": 0
      },
      {
        "id": null,
        "channel": {
          "id": 2,
          "nameAr": null,
          "nameEn": "POS TERMINAL"
        },
        "cardScheme": {
          "id": "P1",
          "nameEn": "mada",
          "nameAr": null
        },
        "countCr": 1,
        "countDb": 0,
        "totalAmountCr": 10000,
        "totalAmountDb": 0
      }
    ]
  }
}

Usage Tips

1. Terminal ID: Ensure the terminalId in the path is valid and matches an active terminal.
2. Reconciliation Status: Monitor the status field to confirm if reconciliation is successfully completed and whether it resulted in a balance or unbalanced status.
3. Scheme Balancing: Check reconTotals for payment scheme-specific balancing insights.

Error Handling

If the reconciliation request fails, an error response may be returned:

Error Scenario	Possible Message	Action Required
Invalid Token	Unauthorized	Re-authenticate to obtain a valid token.
Missing Terminal ID	Bad Request	Include the terminalId in the URL path.
Invalid Terminal ID	Terminal Not Found	Verify the terminalId is correct.