Introduction

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
5	channelCode	Integer	Required	Channel ID. Identifies transaction chanelSee Channel Appendix below for channel definitions
6	requestTime	String	Required	Transaction request time in the format dd-MM-yyyy HH:mm
7	institutionCode	String	Required	TS Institution code for destination institution
8	initiatingInstitutionCode	String	Required	TS Institution code for initiating institution

Endpoint

url /endpoint goes here

Headers

"Content-Type":"application/json"

Sample Plain Request

Sample request

{"requestTime": "15-06-2020 14:39","institutionCode": "FBN","transactionReference": "CR|ZIB|FBN|150620201439|402452","transactionAmount": 3250000,"initiatingInstitutionCode": "ZIB","accountNumber": "3059198727","currencyCode": "NGN","channelCode": "2"}

Sample Encrypted Request

Sample request

{"request":"hQEMA0DlRChs2dNlAQf/WL0gFBvazSpeU+hGCBK7MZxRJyaRMeZxL443IS1vLET1iYMMPnET4T/FseWTuIOj9LS86a+y1U3TfL/r+P0Wjs/B9QDL7Vfx8ahBv7yOJGdcYUR3Rtrt7B1ybdEWpq3kw81pAwqIJNOlUnksncQnsPozsr2Ogh/YF9wevOODgvRyyKYcWxVhBku8cF5AyWicsjNqnShYZbk9r0sjt6aqKa0VGbddcT6zdA3aOYLSeIFEsmT/CtFglHZB1fJlaYlKQ460cQqOKasZIERy9hWECB/trNyf0wDTvVkdtL6Bhp/w5jvySoWnnXZmryChYFMmK5r+9INNFC8GGTVGkfG9XsnAI8p8gUCgmkYshElC53asGos5BlI0tg+VYgO2xqGaxqooSvrppm5q/Nf9e6ZcaerUeWFMfgIXvW0ZcuSfYEAZbXdcnm/zNJbVZHiQZ50tGr/Om1uEtD+iiKfoaxkfZbC1WHQl8wMW+6qn1RpsaV6Ia+AtM5t7SdWqN1fK3RXyzQanvxDFUzyvlbykfsFmWnaN9HMYQ6n4o9kyKD+QmXFFvtYDroQB1JsIk0Ge94KvqVzKsC9oWWMDGobuJyJyAGpplovxbm/4ZAWDWnP+EzZHWdC9cTWE1XKb7rC7VNMVtwZexHH6""request":"hQEMA0DlRChs2dNlAQf/WL0gFBvazSpeU+hGCBK7MZxRJyaRMeZxL443IS1vLET1iYMMPnET4T/FseWTuIOj9LS86a+y1U3TfL/r+P0Wjs/B9QDL7Vfx8ahBv7yOJGdcYUR3Rtrt7B1ybdEWpq3kw81pAwqIJNOlUnksncQnsPozsr2Ogh/YF9wevOODgvRyyKYcWxVhBku8cF5AyWicsjNqnShYZbk9r0sjt6aqKa0VGbddcT6zdA3aOYLSeIFEsmT/CtFglHZB1fJlaYlKQ460cQqOKasZIERy9hWECB/trNyf0wDTvVkdtL6Bhp/w5jvySoWnnXZmryChYFMmK5r+9INNFC8GGTVGkfG9XsnAI8p8gUCgmkYshElC53asGos5BlI0tg+VYgO2xqGaxqooSvrppm5q/Nf9e6ZcaerUeWFMfgIXvW0ZcuSfYEAZbXdcnm/zNJbVZHiQZ50tGr/Om1uEtD+iiKfoaxkfZbC1WHQl8wMW+6qn1RpsaV6Ia+AtM5t7SdWqN1fK3RXyzQanvxDFUzyvlbykfsFmWnaN9HMYQ6n4o9kyKD+QmXFFvtYDroQB1JsIk0Ge94KvqVzKsC9oWWMDGobuJyJyAGpplovxbm/4ZAWDWnP+EzZHWdC9cTWE1XKb7rC7VNMVtwZexHH6"}

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 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

Sample Plain Response (success)

{"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}

Sample Plain Response (failure)

{  "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}

Sample Encryped Response (success)

{"response":"hQEMAxpO4GU1IXNDAgf/f+Nj1AHkFZiYJ38H8kQX9IPyMrkqdqw8LvuQAjPT4oHi36xnrllQpOcwAwc4aTmImky2SovEGt3ZoUSSX57C6mwBbRo0N57bb/TSK000oqtIvgq2eWdqhhqM5xsOR2h5vIHEYFbFo6ZkA0NyOVSCzIbFuVe0HodXRbpDLrLlbduRol0h007s4Gw+moz+Dsdrb2EnGBjvhdpuxd7dD7im8HiFS3vrf1Lu6N5Mg76xFk+gSTDTgqlvLUzOoLDpZHUMsl5DsVDhPMNs6oIMiuFSi7fTVK412uMb222zq/DvrdEFcvjy9n55fNLxyEh8nDIx32mXNzoCIYnk+w7ewGrdJ8nAmo/BcX/s2l/DxFNB/u7bCYoV4QjgaNNZO+X4B+KoygGS5cM3xk26/A3cf2TmJZnvz90S6tsaSD31jRTfE6T+kHdTZiuLtz6T0E3oToO4kib2Gw6izijDqNyUmR+XDKGg41rJARScAwAkV7378Ye1pUXqBPCqXjP/jH5VNMig6jEoxKUaQ0KoIGrXztvf1a8ZVnC5asZq0iw7AhTzGmv9PBknRMymdtJ2C+rIiLwxXhSxn2WXqbT2ZTArrga95Mgm4dLOErEaOmCzQfbpkq3kZgWIMBAlgK2cgzSSBSsmidhaTgTbaKx57SA+x2WQ35jZ2mICFtfG2J1jaSUGy64ybyLh/FPMnREAXKs95LLtlgfCTXaRQdnOujmwj77+rjNBO9MXJ7E/l8WSqVpMrpI70nyp2mzxspuZI/ltV+7BW7mArK1DM8KR5x4shHKaIrmhGju5WJw/3+6xYC0="}

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

Endpoint

url /endpoint goes here

Headers

"Content-Type":"application/json"

Sample Plain Request

Sample request

{"transactionLocation": "IRO,T,17190001059661,myself, myself,LaNG","transactionReference": "CR|ZIB|FBN|150620201439|402452","destinationAccountNumber": "3059198727","sourceAccountNumber": "1015179455","destinationAccountName": "BAKARE KAMORUDEEN ADEWALE","debitSourceInstitutionAccount": true,"requestTime": "15-06-2020 14:39:56","destinationInstitutionCode": "FBN","transactionAmount": 3250000,"narration": "IRO,T,17190001059661,myself, myself,LaNG","sourceInstitutionCode": "TAM","currencyCode": "NGN","sourceAccountName": "628051********7958","channelCode": "2","additionalInfo":"{"rrn":"3345322009", "stan":"443554338","maskedPan":"563546****8778"}"}

Sample Encrypted Request

Sample request

{"request":"hQEMA0DlRChs2dNlAQf/bR3OdTWmgvB1tWgZ5Oq/ZAGss2inQFvktQmkVOb0C4QEFVTLYNM4CV22Fs0Qx4/AXCFWDLBme0kxVhElAV/mVzwSAuh0tZCg25HtvOVnbDUpius2ydQTvzJPaDE7hL0RJTKEa9141Rjd1VyKwY1FILnBysJLLtX3/IkPAA5qoUD+jibO9mBzfa9OyWk3SwIY82BAsSeVvIglSRC7C6fzG68Aw/S1LbdHmuaW/cQDgxOoAPmkNb2GS6hhfag+VAhrtlBbwSjT13JV5HuFk0X9yp+d9nsAQCY+4YfK2JSA3P9KL9dlqEFH4dkvGBwFTW8YZ916tiN62M8LDssF+pb8OcnAlyduuaMr6Q0P93dibTO5nlPAxjU82ugUJ7wpgK+22a7r4Je5NC4mvdBundbxyKpJ+iDknreZSfSkdjudMyF9YcmMLurD788XQOfbbGnGfqS7xUT69d1VxeMQZgttvPs7LWqNETttkH2aCn+9xxZzzXEZ5aAmWxAJYMa/ZNxbjQWbQ6+oJjSFx/JIQBSLhWw2YabhgnEPRYlKMKGJ3grXYi+dO1t3B8kejpe+ChmXiOk1R9gJ+UoC9ruK2s5uaDZtnrm6lKnHO2vnBHVQOmpDrkEzpg7776BTfDAGqT2oLU2uzPT5E7oOEZq5z3lSFAnEOD+rh5i4S8wLy+IRg/trs/UJzD6p8Ru5HzotKLB5u2VpzjolQ9D05enIpmRbVQ4j06XmFDxwpy1Hoy1xttu3PulMdYTgSc9MWVLQKUmgjB9LmhSAcrB0aadynR//mh9qiGpEr4L4uUQ="}

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 insititution.
5	institutionProcessingTime	String	Required	Date the request was processedThis 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

Sample Plain Response (success)

{"institutionResponseMessage": "Success","institutionResponseCode": "00","transactionReference": "CR|ZIB|FBN|150120211439|402452","institutionReference": "85856FA886B34B63AA7FA315B1650D81","institutionProcessingTime": "15-01-2021 14:39:56","action": "SUCCESS","responseCode": "00"}

Sample Plain Response (failure)

{"institutionResponseMessage": "FAILURE","institutionResponseCode": "98","transactionReference": "CR|ZIB|FBN|150120211439|402452","institutionReference": "85856FA886B34B63AA7FA315B1650D81","institutionProcessingTime": "15-01-2021 14:39:56","action": "FAILURE","responseCode": "98"}

Sample Encrypted Response (success)

{"response":"hQEMAxpO4GU1IXNDAgf+LivjQxi6OXHLNCu6UiB23rkw8vcUFF6ZCIvTivQSUHi7gwp4fDkYhhAD2uYI66g03KpB5mAezku/+XADPbhGpnUBJIL+KraISsLpiTh3DQBkmVcskshHDS4qHcS7pvK1lmwHGSe438bvmi59s8i/nfzW6Qy2l+IOGmu+iB9QfTmwUJtID1DxzmS2DCGgGfcB5T0nGZMbH3jFW9Fw7deXZscHFVCu3Vp/CY6HJH4isau3a69GkAUIqL8DCmE9PfoHwIRX7NFoWsE9CyB2HN6+NZBBg6bo+K6q4g8Zlx0h9+kVM9OGsC40thbgut/yUensr0FpGNlOtTtqt3M3r+RC48nAHlWjtPgf3ZlXHfYdRQhyixLqKE7JB0H3c72uJd9J1nOPfLaGLa7RJgzkQBQ+dniUEjRUDHqrqdo+q/eCjt8Gm1GZkCepKBcNVFYWOFGIQcic0XoazX2k+hVU070MuQjSZTwni5RcOsmzNJ3mpTKJCxbmpOIOdkMzPL0qCp0jE6/bASTAQkSNukDWyhI2/+c37CXy8wBtEyjxQiWLHHOwRw9rkcpjcaiB9DWxS00yKYsKUWhaAild9Eth0oZkGk9OZyCp1QEsrEv2fpJxCnE8ac0nlsm0MzY3H8CYDTNhuw=="}

ISW API(s)

Credit Status Confirmation

The credit status confirmation API enables the bank query transactions sent by the transfer service for credit, before the beneficiary is credited

Request Message description

Field#	Field name	Data type	Required	Description
1	transactionReference	String	Required	Unique transaction reference generated by TS and used in the original request.

Endpoint

POST /transfers/transaction/status

Headers

Authorization - Bearer {Passport Access Token}Content-Type: application/json

Sample Request

Sample request

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

Response Message  field description

Field#	Field name	Data Type	Required	Description
1	responseCode	String	Required	Response code of the transaction in TS
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 FAILURE

Sample Response (success)

HTTP Status: 200{"responseCode": "00","transactionReference": "CR|SUN|FBP|310520202047|226464","responseMessage": "Approved or completed successfully","status": "SUCCESS}

Sample Response (failure)

HTTP Status: 503{"responseCode": "91","transactionReference": "CR|SUN|FBP|310520202047|226464","responseMessage": "Approved or completed successfully","status": "FAILURE"}

Authentication (Token Generation) API

The authentication API enables the bank generate access tokens for authentication purposes.

In addition, the request body is sent as a URL encoded form. As a result, the following request parameters would be set:

Request Message description

Field#	Field name	Value	Data type	Required
1	grant_type	client_credentials	String	Required
2	Scope	profile	String	Required

Endpoint

Endpoint

POST /passport/oauth/token

Headers

Headers

Authorization - Basic <Base64Encoded string of 'client_id:client_secret'>Content-Type: application/x-www-form-urlencoded

Sample Request

Sample request

grant_type=client_credentials&scope=profile

Response Message  field description

Field#	Field name	Data Type	Description
1	access_token	String	The access token that would be used to consume the secure apis
2	expires_in	String	The time this token will expire in seconds. Ensure that the token is renewed at least 30 seconds before the token expires to prevent expiry in flight

Sample Response (success)

{ "access_token":"eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsicGFzc3BvcnQiXSwic2NvcGUiOlsicHJvZmlsZSJdLCJleHAiOjMwMTg1Mjk4ODksImp0aSI6IjBlYWYwMWIzLTM4M2QtNDFkNi1hOTgzLWI3OTIwNDU3ODBjMyIsImNsaWVudF9pZCI6InRlc3RjbGllbnQifQ.OaLlGSTLFHGu7553HNhzuBOIiQvdiNVNPAm5-opCq7JPugEG2ubPtLZLu2znr0aJkHR0BGiV2e9ZSrkp6cxYoT74SvY9b-2AE9giNdWpPgWMO6HqadL9re6ojkl9YU9uW_okjYUhTa-P_jOtWYUhbqi02SyUrN8m-SNI29IZPS-Q2J9Aq9zARiW7dVZWMBC8GHR_IL8V-GozaG782kIEUcBNfDGRnttV5qJwVpXomzyKlZDwEZKPOewh_1NVPvv7hDi79OfN63PiENvM4XLzDW9rFgKrRb6x43dpLfnoie1Id39eiCLGKX8ykrVEFg94jp1JCDpEDaexCcf05Dz5ag","token_type": "bearer","expires_in": 43199,"scope": "profile","jti": "0eaf01b3-383d-41d6-a983-b792045780c3"}

Sample Response (failure)

{ "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
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
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.	Transfer frequency reached

Channel Codes

Channel Code	Description
1	BANK BRANCH
2	WEB
3	DIRECT DEBIT
4	ATM
5	POS
6	MOBILE