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

Response Message field description

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

Response Message field description

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

A typical request will look like these

{
  "transactionReference": "CR|SUN|FBP|310520202047|226464"
}

Response Parameters

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:

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

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"
    },
    ...
  ]
    }