Reversal Request
- Method: POST
- Endpoint: /api/v1/reversal
- Request Parameters
- Response Parameters
Request Parameters
| Field Name | Data Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Unique identifier generated by the originating institution to uniquely reference the reversal request across the switch and participating banks. |
| stan | String | Yes | System Trace Audit Number assigned to the reversal transaction for tracking, reconciliation, and audit purposes. |
| processingCode | String | Yes | Code indicating a reversal transaction. This value is defined by the switch processing code catalog (e.g., 400000 = Reversal). |
| tranDateTime | String (ISO-8601) | Yes | Date and time the reversal request was initiated by the originating institution. |
| currency | String | Yes | ISO 4217 currency code in which the original transaction was processed (e.g., NGN). |
| countryCode | String | No | ISO 3166-1 alpha-2 country code indicating the origin of the reversal request. |
| originalTransaction | Object | Yes | Container holding details of the original transaction being reversed. Used for validation and matching by the receiving bank. |
| originalTransaction.stan | String | Yes | System Trace Audit Number of the original transaction to be reversed. |
| originalTransaction.requestId | String | Yes | Original request identifier of the transaction being reversed, as previously processed by the switch. |
| originalTransaction.tranDateTime | String (ISO-8601) | Yes | Date and time the original transaction was initiated or processed. |
| originalTransaction.tranAmt | String | Yes | Amount of the original transaction to be reversed. Must exactly match the original transaction amount. |
| reversalReason | String | Optional | Standardized reason code or description indicating why the reversal is being requested (e.g., DUPLICATE_TRANSACTION, TIMEOUT, SYSTEM_ERROR). |
| sourceInstitution | String | Yes | Code identifying the originating institution |
| channel | String | Yes | Transaction channel (API, WEB, MOBILE, POS) |
Response Parameters
| Field Name | Data Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Unique identifier of the transaction request, used to correlate the response with the originating request. |
| responseCode | String | Yes | Standardized response code returned by the bank. A value of 00 indicates successful processing. |
| responseMessage | String | Yes | Human-readable description corresponding to the response code (e.g., SUCCESS). |
| stan | String | Yes | System Trace Audit Number (STAN). A unique transaction reference used for transaction tracking, reconciliation, and audit purposes. |
| tranDateTime | String | Yes | Date and time when the transaction was processed by the bank, in ISO-8601 format (YYYY-MM-DDThh:mm:ss). |
| availableBalance | Decimal | Optional | The balance available for use after transaction processing. Required for financial transactions impacting account balance. |
| ledgerBalance | Decimal | Optional | The ledger (book) balance after transaction posting, including uncleared or pending items. |
| currency | String | Yes | ISO 4217 currency code representing the denomination of all monetary values (e.g., NGN). |
- Sample Request
- Sample Response
Request Parameters
{
"requestId": "REQ-20260123-000004",
"stan": "000401",
"processingCode": "400000",
"tranDateTime": "2026-01-23T12:00:00",
"currency": "NGN",
"countryCode": "NG",
"originalTransaction": {
"stan": "000301",
"requestId": "REQ-20260123-000003",
"tranDateTime": "2026-01-23T11:00:00",
"tranAmt": "243021.00"
},
"sourceInstitution": "044",
"channel": "Mobile",
"reversalReason": "DUPLICATE_TRANSACTION"
}
Response Parameters
{
"requestId": "REQ-20260123-000004",
"responseCode": "00",
"responseMessage": "SUCCESS",
"stan": "000401",
"tranDateTime": "2026-01-23T12:00:05",
"availableBalance": "13269143.00",
"ledgerBalance": "13277643.00",
"currency": "NGN"
}