Bank confirmation API
The Bank confirmation APIs are required to be implemented by your financial institution. Two of these endpoints need to be developed by your financial institution to be shared with us at Interswitch. Our system will make requests to these endpoints, and your system must respond with the accepted response stated in this section.
Endpoints
- Account Inquiry Endpoint
- Credit Instruction Endpoint
Server Specification: Servers should be load-balanced and configured to communicate directly with your Core Banking Application.
API Specification: The APIs are recommended to be in a restful format that supports JSON data format.
Security: All APIs should ONLY be made available over VPN by the bank or financial institution to Interswitch.
Encryption: The account validation and credit Instruction request and response data must be encrypted using the PGP Encryption/Decryption model.
In this section, we have outlined the steps needed for efficient integration.
Step 1- Make a bank account Inquiry endpoint
This API validates that an account to be credited is available and functional at the receiving institution and may also include an amount validation check to ensure the account can receive the amount in the request.
The account Inquiry endpoint performs the following :
- That the account exists.
- That the account is active.
- That the account can receive the funds intended to be transferred (E.g A child savings account may not be able to receive a certain amount of funds)
- In the case of a zero-amount validation, checking that the account exists and is active will suffice.
In summary, this endpoint receives a request to confirm if an account specified by the destination account number can be credited with a specified amount (or zero amount for backward compatibility). The response to this request typically includes a boolean field, canCredit
, which indicates if the inquiry was successful and if credit can proceed.
Upon the successful completion of an account inquiry, the transaction is logged in the Transfer service, and a credit completion request is expected to initiate the credit to the beneficiary account.
Endpoint
url /endpoint goes here
Headers
"Content-Type":"application/json"
Body Parameters
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | accountNumber | String | Required | Beneficiary account number |
2 | transactionAmount | Long (Minor denomination e.g., kobo for Naira currency) Can also be a zero amount. | Required | This is the value of funds intended to be transferred. The purpose of this field is to allow the bank to perform additional checks to see if the funds can be received by the beneficiary. For example, if customer X cannot receive this amount, canCredit should be false in the response body. |
3 | currencyCode | String | Required | Currency code of the transaction. This is the ISO currency code, e.g., NGN for Naira. |
4 | transactionReference | String | Required | Unique transaction reference generated by Transfer Service and used throughout the entire life of the transaction. This transaction reference will be used to complete the funds transfer instruction. There should be no duplicate check on the transactionReference . Each request with the same transaction reference should perform a new account validation and return the response again. |
5 | channelCode | Integer | Required | Channel ID. Identifies transaction channel. Read more here |
6 | requestTime | String | Required | Transaction request time in the format dd-MM-yyyy HH:mm. |
7 | institutionCode | String | Required | TS Institution code for the destination institution. Find more information here |
8 | initiatingInstitutionCode | String | Required | TS Institution code for the initiating institution. |
Response Message field description
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | firstName | String | Optional | Beneficiary first name |
2 | lastName | String | Optional | Beneficiary last name |
3 | accountName | String | Required | Core banking account name |
4 | accountType | String | Optional | Current, Savings, or Credit |
5 | accountCurrency | String | Required | ISO currency |
6 | address | String | Optional | Beneficiary address |
7 | responseCode | String | Required | TS response code. See Response Code Appendix below for response code mapping |
8 | institutionResponseMessage | String | Required | Bank response message |
9 | transactionReferenceNumber | String | Required | The TS transaction reference number sent in request |
10 | processTime | String | Required | Date the request was processed on the bank’s end in dd-MM-yyyy HH:mm:ss format |
11 | institutionReference | String | Optional | Core Banking transaction reference for the account validation request |
12 | bankVerificationNumber | String | Optional | The BVN of the customer |
13 | kycLevel | String | Optional | The KYC level of the customer |
14 | canCredit | Boolean | Required | Account number and transaction amount are validated in real-time to ascertain that the account can be credited. Validation checks to set this value include account credit limits, dormancy, or inactivity (including other checks specific to your bank). |
15 | canDebit | Boolean | Optional | Account number and transaction amount are validated in real-time to ascertain that the account can be debited. Validation checks to set this value include account debit limits, account balance, minimum balance, dormancy, or inactivity (including other checks specific to your bank). |
16 | action | String | Required | Indicates status of inquiry; could be SUCCESS or FAILURE |
17 | institutionResponseCode | String | Required | Response code from Institution CBA before mapping to TS Response Code |
This is what a typical successful or failed response would look like
{
"lastName": null,
"address": null,
"accountName": "BAKARE KAMORUDEEN ADEWALE",
"transactionReferenceNumber": "CR|ZIB|FBN|150120211439|402452",
"institutionReference": "88A402ED5F1744B5A3D7086CC4B8BBD1",
"accountType": null,
"accountCurrency": "NGN",
"canCredit": true,
"processTime": "15-06-2020 14:39:56",
"responseCode": "00",
"canDebit": null,
"firstName": null,
"kycLevel": null,
"institutionResponseMessage": "Success",
"institutionResponseCode": "00",
"action": "SUCCESS",
"responseMessage": "Success",
"bankVerificationNumber": null
}
{
"transactionReferenceNumber": "CR|ZIB|FBN|150120211439|402452",
"institutionReference": "88A402ED5F1744B5A3D7086CC4B8BBD1",
"accountType": null,
"canCredit": false,
"processTime": "15-06-2020 14:39:56",
"responseCode": "39",
"canDebit": null,
"firstName": null,
"kycLevel": null,
"institutionResponseMessage": "failed",
"institutionResponseCode": "39",
"action": "FAILURE",
"responseMessage": "failed",
"bankVerificationNumber": null
}
Step 2 - make a credit Instruction endpoint
The credit instruction endpoint will be used by the transfer service to credit any beneficiary within the bank. The unique ref generated during the Inquiry API call or the transaction reference generated by the Transfer Service on an account inquiry must be provided in this request.
Endpoint
url /endpoint goes here
Headers
"Content-Type":"application/json"
Body Parameters
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | destinationAccountName | String | Required | Beneficiary account name |
2 | destinationAccountNumber | String | Required | Beneficiary account number |
3 | transactionAmount | Long (Minor denomination) | Required | Amount to be credited to beneficiary |
4 | narration | String | Required | Transaction narration |
5 | currencyCode | String | Required | ISO currency code |
6 | transactionReference | String | Required | Unique transaction reference. Credit transactions should fail when reference is a duplicate |
7 | channelCode | String | Required | Channel ID. Identifies transaction channel. See Channel Appendix below for channel definitions. |
8 | requestTime | String | Required | dd-MM-yyyy HH:mm:ss For security, it is advised that this value is taken into consideration before onward processing of a request. |
9 | Signature | String | Required | HmacSHA1(nonce+accountName+accountNumber+transactionAmount+currencyCode+transRef+destinationInstitutionCode+channelCode) This request parameter is contained in the header of the request and is to be validated by the bank. The HMAC key is to be provided and verified by the bank for the UAT and Production environment. The Nonce and Algorithm values are also provided in the request header. |
10 | transactionLocation | String | Required | Transaction Location |
11 | additionalInfo | String | Optional | Additional information about the transaction. |
12 | settlementAccount | String | Optional | Sent in FX transactions. Helps the remote institution identify the TSS Account such transactions will be settled to. |
Response Message field description
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | responseCode | String | Required | TS response code. See Response Code Appendix below for response code mapping |
2 | institutionResponseMessage | String | Required | Response message of the core banking application |
3 | transactionReference | String | Required | Unique transaction reference sent in the transfer request |
4 | institutionReference | String | Optional | This is the transaction reference by the core banking application (CBA) of the institution |
5 | institutionProcessingTime | String | Required | Date the request was processed. This can be in the format “dd-MM-yyyy HH:mm:ss” |
6 | action | String | Required | Indicates status of credit; could be SUCCESS or FAILURE |
7 | institutionResponseCode | String | Required | Response code from Institution CBA before mapping to TS Response Code |
This is what a typical successful or failed response would look like
{
"institutionResponseMessage": "Success",
"institutionResponseCode": "00",
"transactionReference": "CR|ZIB|FBN|150120211439|402452",
"institutionReference": "85856FA886B34B63AA7FA315B1650D81",
"institutionProcessingTime": "15-01-2021 14:39:56",
"action": "SUCCESS",
"responseCode": "00"
}
{
"institutionResponseMessage": "FAILURE",
"institutionResponseCode": "98",
"transactionReference": "CR|ZIB|FBN|150120211439|402452",
"institutionReference": "85856FA886B34B63AA7FA315B1650D81",
"institutionProcessingTime": "15-01-2021 14:39:56",
"action": "FAILURE",
"responseCode": "98"
}
{
"response": "hQEMAxpO4GU1IXNDAgf+LivjQxi6OXHLNCu6UiB23rkw8vcUFF6ZCIvTivQSUHi7gwp4fDkYhhAD2uYI66g03KpB5mAezku/+XADPbhGpnUBJIL+KraISsLpiTh3DQBkmVcskshHDS4qHcS7pvK1lmwHGSe438bvmi59s8i/nfzW6Qy2l+IOGmu+iB9QfTmwUJtID1DxzmS2DCGgGfcB5T0nGZMbH3jFW9Fw7deXZscHFVCu3Vp/CY6HJH4isau3a69GkAUIqL8DCmE9PfoHwIRX7NFoWsE9CyB2HN6+NZBBg6bo+K6q4g8Zlx0h9+kVM9OGsC40thbgut/yUensr0FpGNlOtTtqt3M3r+RC48nAHlWjtPgf3ZlXHfYdRQhyixLqKE7JB0H3c72uJd9J1nOPfLaGLa7RJgzkQBQ+dniUEjRUDHqrqdo+q/eCjt8Gm1GZkCepKBcNVFYWOFGIQcic0XoazX2k+hVU070MuQjSZTwni5RcOsmzNJ3mpTKJCxbmpOIOdkMzPL0qCp0jE6/bASTAQkSNukDWyhI2/+c37CXy8wBtEyjxQiWLHHOwRw9rkcpjcaiB9DWxS00yKYsKUWhaAild9Eth0oZkGk9OZyCp1QEsrEv2fpJxCnE8ac0nlsm0MzY3H8CYDTNhuw=="
}
Step 3 - Make an API call to Interswitch's transaction query endpoint
The credit status confirmation API enables the bank or financial institution to query transactions the transfer service sends for credit before the beneficiary is credited. The transaction query endpoint will return the status of the transaction. Requery can be initiated either by using the client's unique reference or the transaction reference returned by the Transfer service platform
Note: This endpoint is used to confirm the final status of a transaction.
Endpoint
/transfers/transaction/status
Headers:
- Authorization: Bearer {Passport Access Token}
- Content-Type: application/json
Body Parameters
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | transactionReference | String | Required | Unique transaction reference generated by TS and used in the original request. |
A typical request will look like these
{
"transactionReference": "CR|SUN|FBP|310520202047|226464"
}
Response Parameters
Field# | Field Name | Data Type | Required | Description |
---|---|---|---|---|
1 | responseCode | String | Required | Response code of the transaction in TS. Find more information here |
2 | responseMessage | String | Optional | Response message of the transaction in TS |
3 | transactionReference | String | Required | Unique transaction reference sent in the transfer request. |
4 | status | String | Required | Status of transaction in TS. Could be SUCCESS or |
This is what a typical successful or failed response would look like
{
"responseCode": "00",
"transactionReference": "CR|SUN|FBP|310520202047|226464",
"responseMessage": "Approved or completed successfully",
"status": "SUCCESS"
}
{
"responseCode": "91",
"transactionReference": "CR|SUN|FBP|310520202047|226464",
"responseMessage": "Approved or completed successfully",
"status": "FAILURE"
}
PGP ENCRYPTION/DECRYPTION
For data confidentiality and security, Account Validation and Credit Instruction request and response data should be encrypted using the PGP Encryption/Decryption model.
The public key generated by the Transfer Service has the following properties:
Name | Value |
---|---|
Encryption Program | PGP (Pretty Good Privacy) |
Key Size | 2048 |
Key Expiry | Never |
Keys for encryption would be generated and shared during integration.
NOTE: THERE SHOULD BE A SERVICE LEVEL AGREEMENT BETWEEN INTERSWITCH AND THE BANKS FOR THE TIME IT WILL TAKE FOR THE BANK TO PROCESS A CREDIT AFTER THE TRANSACTION HAS BEEN ENQUEUED ON THEIR END. THIS IS TO ENSURE RAPID FINALITY FOR TRANSACTIONS ESPECIALLY WHEN EDGE CASES/NEGATIVE SCENARIOS OCCUR
How to Get Institution Code
This endpoint allows you to fetch the list of banks and their institution codes .
Endpoint
GET <base URI> /transfers/institutions
Headers
Authorization – Bearer {Passport Access Token}
Content-Type: application/json
Query Parameters
Field# | Field name | Data type | Option | Description |
---|---|---|---|---|
1 | perPage | Integer | Optional | The number of institutions per page. The default value is 30 and the maximum value is 200 |
2 | page | Integer | Optional | The page number of the institutions to fetch. |
GET host /transfers/institutions?perPage=200&page=1
The response will look like this :
{
"total": 515,
"perPage": 200,
"page": 1,
"institutions": [
{
"institutionId": "1",
"institutionCode": "AAB",
"institutionName": "Actual African Bank"
},
{
"institutionId": "2",
"institutionCode": "AGB",
"institutionName": "Actual Global Bank"
},
...
]
}
Updated 3 months ago