The Interswitch Transfer Service is an initiative for transfers to drive the highest possible success rates in the direct to account categories. The APIs required to be implemented by each participating bank are described in this document.
Server Specification
Servers, are to be load balanced, and should speak directly to the Core Banking Application.
API Specification
The APIs are recommended to be in restful format that supports json data format.
BANK API(s)
Account Validation & Name Lookup API
The account validation and name lookup apis are used to perform the following
1. That the account exists. 2. That the account is active. 3. That the account can receive the funds intended to be transferred (E.g A child savings account may not be able to receive certain amount of funds) 4. In the case of a zero-amount validation, checking that the account exists and is active will suffice.
Request Message description
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 allow the bank do additional checks 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 will be used throughout the entire life of the transaction. This is the transaction reference that would 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 do a new account validation and return the response again
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 KYCLevel of the customer
14
canCredit
Boolean
Required
Account number and transaction amount are validated real-time to ascertain that the account can be credited.Validation checks to set this value include account credit limits, dormancy or inactiveness. (including other checks specific to your bank)
15
canDebit
Boolean
Optional
Account number and transaction amount are validated real-time to ascertain that the account can be debitted.Validation checks to set this value include account debit limits, account balance, minimum balance, dormancy or inactiveness. (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
Credit Instruction API (Funds Transfer Single Credit)
The credit instruction api will be used by the transfer service to credit any beneficiary within the bank.
Request Message description
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 transaction should fail when reference is a duplicate
7
channelCode
String
Required
Channel code
8
requestTime
String
Required
dd-MM-yyyy HH:mm:ssFor the purpose of 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 pertaining to transaction.
12
settlementAccount
String
Optional
Sent in FX transactions. Helps the remote institution identify the TSS Account such transactions will be settled to
{ "error": "invalid_request", "error_description": "Missing grant type" }
API SECURITY
All APIs should ONLY be made available over VPN by the bank to Interswitch.
PGP ENCRYPTION/DECRYPTION
For the purpose of 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 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 OCCURS
Response Codes
Response Code
Description
Response Message
00
Transaction was successful
Approved or completed successfully
01
Source institution should be contacted
Contact source institution
05
Do not honour
Do not honour
06
Transaction failed for arbitrary reasons
General transaction failure
09
Transaction is in progress at middleware or other operational reasons.
Transaction in progress
10
CBA timeout at destination
Transaction in progress
12
The transaction is invalid
Invalid Transaction
13
Invalid Amount
Invalid Amount
14
The account type for this account is invalid
Account type is incorrect
15
No such issuer
Invalid Issuer
17
Middleware error returned for operations relating to customer authenticating the debit
Debit Authentication Error
18
Requery cannot be executed for transactions older than 5 days. This is not confirmation that the transaction failed/ successful
Client requery cannot be executed for transactions older than 5 days
19
Transaction retry limit has been reached. The middleware will no longer attempt this transaction. Except a requery and it receives a response code for which it can retry.
Pending transaction retry limit reached and status unknown
20
Invalid response received from processor
Invalid response received from CBA
21
Middleware received a response code that is not in its mapping configuration table
Response code not registered
25
Transaction record not found
Transaction not found
30
Bad request
Bad request
31
Invalid route configuration for sender
Route configuration error for issuer institution
39
The specified account does not exist
Invalid account
40
The sender account is invalid
Sender invalid
45
The specified account is closed
Account is closed
46
The specified account is dormant
Account is dormant
47
The specified account is blocked
Account is blocked
48
Inquiry Request was processed successfully but Credit Request was not received the configured retention period
Transaction Expired
49
Inquiry Request was not processed successfully within the configured retention period
Transaction Expired
51
The specified account balance has been reached
Account balance limit reached
52
The TSS at the crediting bank is not sufficiently funded
Transaction failed. Please contact administrator
56
Payment instrument not found to complete transaction
Payment Instrument not found
58
Transaction not allowed on channel specified/ Channel code has not been mapped/setup on the middleware or is inactive. No further action was taken.
Transaction not permitted on channel /Channel does not exist
59
The transaction is marked as suspected fraud and not processed
Suspected fraud or security breach
61
Transaction limit exceeded
Source transfer limit exceeded
62
Withdrawal frequency exceeded
Withdrawal frequency exceeded
63
Security has been violated
Security Violation
64
Authentication token is not valid
Authentication token is not valid
79
Bvn record not maintained
Account no bvn maintained
80
Account name mismatch
Account name mismatch
81
The configured TSS is invalid (does not exist, PND, etc)
Invalid TSS account
82
The configured TSS could not be credited
Cannot credit TSS account
91
Middleware could not reach Core Banking Application / Middleware did not get a definite response from Core Banking Application
Could not reach Remote Service / Response timed out while attempting to reach remote service
92
Invalid route configuration for destination
Issue/Error with routing configuration for the receiving institution
94
Transaction is a duplicate and is either in progress
Duplicate transaction
97
A system error occurred. Transaction status not confirmed.
A system error occurred. Transaction status not confirmed.
98
The specified account has reached the limit for this transaction
Account transaction limit reached
99
The transfer rate limit has been reached for the TSS account.