Introduction<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

Server Specification<\/h2>\n\n\n\n

Servers, are to be load balanced, and should speak directly to the Core Banking Application.<\/p>\n\n\n\n

API Specification<\/h2>\n\n\n\n

The APIs are recommended to be in restful format that supports json data format.<\/p>\n\n\n\n

BANK API(s)<\/h2>\n\n\n\n

Account Validation & Name Lookup API<\/h3>\n\n\n\n

The account validation and name lookup apis are used to perform the following<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Request Message description<\/h4>\n\n\n\n

Field#<\/th>	Field name<\/th>	Data type<\/th>	Required<\/th>	Description<\/th><\/tr><\/thead>
1<\/td>	accountNumber<\/td>	String<\/td>	Required<\/td>	Beneficiary account number<\/td><\/tr>
2<\/td>	transactionAmount<\/td>	Long (Minor denomination e.g kobo for Naira currency) Can also be a zero amount.<\/td>	Required<\/td>	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<\/strong> should be false in the response body.<\/td><\/tr>
3<\/td>	currencyCode<\/td>	String<\/td>	Required<\/td>	Currency code of the transaction. This is the ISO currency code. e.g  NGN for naira.<\/td><\/tr>
4<\/td>	transactionReference<\/td>	String<\/td>	Required<\/td>	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<\/td><\/tr>
5<\/td>	channelCode<\/td>	Integer<\/td>	Required<\/td>	Channel ID. Identifies transaction chanelSee Channel Appendix below for channel definitions<\/td><\/tr>
6<\/td>	requestTime<\/td>	String<\/td>	Required<\/td>	Transaction request time in the format dd-MM-yyyy HH:mm<\/td><\/tr>
7<\/td>	institutionCode<\/td>	String<\/td>	Required<\/td>	TS Institution code for destination institution<\/td><\/tr>
8<\/td>	initiatingInstitutionCode<\/td>	String<\/td>	Required<\/td>	TS Institution code for initiating institution<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Endpoint<\/strong><\/p>\n\n\n\n url \/endpoint goes here<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Headers<\/strong><\/p>\n\n\n\n \"Content-Type\"<\/code>:<\/code>\"application\/json\"<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Request<\/h5>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n {<\/code> \"requestTime\": \"15-06-2020 14:39\",<\/code> \"institutionCode\": \"FBN\",<\/code> \"transactionReference\": \"CR|ZIB|FBN|150620201439|402452\",<\/code> \"transactionAmount\": 3250000,<\/code> \"initiatingInstitutionCode\": \"ZIB\",<\/code> \"accountNumber\": \"3059198727\",<\/code> \"currencyCode\": \"NGN\",<\/code> \"channelCode\": \"2\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Encrypted Request<\/h4>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n {<\/code> \"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\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Response Message  field description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data Type<\/th> Required<\/th> Description<\/th><\/tr><\/thead> 1<\/td> firstName<\/td> String<\/td> Optional<\/td> Beneficiary first name<\/td><\/tr> 2<\/td> lastName<\/td> String<\/td> Optional<\/td> Beneficiary last name<\/td><\/tr> 3<\/td> accountName<\/td> String<\/td> Required<\/td> Core banking account name<\/td><\/tr> 4<\/td> accountType<\/td> String<\/td> Optional<\/td> Current, Savings, or Credit<\/td><\/tr> 5<\/td> accountCurrency<\/td> String<\/td> Required<\/td> ISO currency<\/td><\/tr> 6<\/td> address<\/td> String<\/td> Optional<\/td> Beneficiary address<\/td><\/tr> 7<\/td> responseCode<\/td> String<\/td> Required<\/td> TS response code.See Response Code Appendix below for response code mapping<\/td><\/tr> 8<\/td> institutionResponseMessage<\/td> String<\/td> Required<\/td> Bank response message<\/td><\/tr> 9<\/td> transactionReferenceNumber<\/td> String<\/td> Required<\/td> The TS transaction reference number sent in request<\/td><\/tr> 10<\/td> processTime<\/td> String<\/td> Required<\/td> Date the request was processed on the bank\u2019s end in dd-MM-yyyy HH:mm:ss format<\/td><\/tr> 11<\/td> institutionReference<\/td> String<\/td> Optional<\/td> Core Banking transaction reference for the account validation request<\/td><\/tr> 12<\/td> bankVerificationNumber<\/td> String<\/td> Optional<\/td> The BVN of the customer<\/td><\/tr> 13<\/td> kycLevel<\/td> String<\/td> Optional<\/td> The KYCLevel of the customer<\/td><\/tr> 14<\/td> canCredit<\/td> Boolean<\/td> Required<\/td> 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)<\/td><\/tr> 15<\/td> canDebit<\/td> Boolean<\/td> Optional<\/td> 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)<\/td><\/tr> 16<\/td> action<\/td> String<\/td> Required<\/td> Indicates status of inquiry could be SUCCESS or FAILURE<\/td><\/tr> 17<\/td> institutionResponseCode<\/td> String<\/td> Required<\/td> Response code from Institution CBA before mapping to TS Response Code<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Response (success)<\/h5>\n\n\n\n {<\/code> \"lastName\": null,<\/code> \"address\": null,<\/code> \"accountName\": \"BAKARE KAMORUDEEN ADEWALE\",<\/code> \"transactionReferenceNumber\": \"CR|ZIB|FBN|150120211439|402452\",<\/code> \"institutionReference\": \"88A402ED5F1744B5A3D7086CC4B8BBD1\",<\/code> \"accountType\": null,\"accountCurrency\": \"NGN\",<\/code> \"canCredit\": true,<\/code> \"processTime\": \"15-06-2020 14:39:56\",<\/code> \"responseCode\": \"00\",<\/code> \"canDebit\": null,<\/code> \"firstName\": null,<\/code> \"kycLevel\": null,<\/code> \"institutionResponseMessage\": \"Success\",<\/code> \"institutionResponseCode\": \"00\",<\/code> \"action\": \"SUCCESS\",<\/code> \"responseMessage\": \"Success\",<\/code> \"bankVerificationNumber\": null<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Response (failure)<\/h5>\n\n\n\n {<\/code> \"transactionReferenceNumber\": \"CR|ZIB|FBN|150120211439|402452\",<\/code> \"institutionReference\": \"88A402ED5F1744B5A3D7086CC4B8BBD1\",<\/code> \"accountType\": null,<\/code> \"canCredit\": false,<\/code> \"processTime\": \"15-06-2020 14:39:56\",<\/code> \"responseCode\": \"39\",<\/code> \"canDebit\": null,<\/code> \"firstName\": null,<\/code> \"kycLevel\": null,<\/code> \"institutionResponseMessage\": \"failed\",<\/code> \"institutionResponseCode\": \"39\",<\/code> \"action\": \"FAILURE\",<\/code> \"responseMessage\": \"failed\",<\/code> \"bankVerificationNumber\": null<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Encryped Response (success)<\/h5>\n\n\n\n {<\/code> \"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=\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Credit Instruction API (Funds Transfer Single Credit)<\/h3>\n\n\n\n The credit instruction api will be used by the transfer service to credit any beneficiary within the bank.<\/p>\n\n\n\n Request Message description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data type<\/th> Required<\/th> Description<\/th><\/tr><\/thead> 1<\/td> destinationAccountName<\/td> String<\/td> Required<\/td> Beneficiary account name<\/td><\/tr> 2<\/td> destinationAccountNumber<\/td> String<\/td> Required<\/td> Beneficiary account number<\/td><\/tr> 3<\/td> transactionAmount<\/td> Long (Minor denomination)<\/td> Required<\/td> Amount to be credited to beneficiary<\/td><\/tr> 4<\/td> narration<\/td> String<\/td> Required<\/td> Transaction narration<\/td><\/tr> 5<\/td> currencyCode<\/td> String<\/td> Required<\/td> ISO currency code<\/td><\/tr> 6<\/td> transactionReference<\/td> String<\/td> Required<\/td> Unique transaction reference. Credit transaction should fail when reference is a duplicate<\/td><\/tr> 7<\/td> channelCode<\/td> String<\/td> Required<\/td> Channel code<\/td><\/tr> 8<\/td> requestTime<\/td> String<\/td> Required<\/td> 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. <\/td><\/tr> 9<\/td> Signature <\/td> String<\/td> Required<\/td> 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 <\/td><\/tr> 10<\/td> transactionLocation<\/td>  String<\/td> Required<\/td> Transaction Location<\/td><\/tr> 11<\/td> additionalInfo <\/td> String<\/td> Optional<\/td> Additional information pertaining to transaction.<\/td><\/tr> 12<\/td> settlementAccount<\/td> String<\/td> Optional<\/td> Sent in FX transactions. Helps the remote institution identify the TSS Account such transactions will be settled to<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Endpoint<\/strong><\/p>\n\n\n\n url \/endpoint goes here<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Headers<\/strong><\/p>\n\n\n\n \"Content-Type\"<\/code>:<\/code>\"application\/json\"<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Request<\/h5>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n {<\/code> \"transactionLocation\": \"IRO,T,17190001059661,myself, myself,LaNG\",<\/code> \"transactionReference\": \"CR|ZIB|FBN|150620201439|402452\",<\/code> \"destinationAccountNumber\": \"3059198727\",<\/code> \"sourceAccountNumber\": \"1015179455\",<\/code> \"destinationAccountName\": \"BAKARE KAMORUDEEN ADEWALE\",<\/code> \"debitSourceInstitutionAccount\": true,<\/code> \"requestTime\": \"15-06-2020 14:39:56\",<\/code> \"destinationInstitutionCode\": \"FBN\",<\/code> \"transactionAmount\": 3250000,<\/code> \"narration\": \"IRO,T,17190001059661,myself, myself,LaNG\",<\/code> \"sourceInstitutionCode\": \"TAM\",<\/code> \"currencyCode\": \"NGN\",<\/code> \"sourceAccountName\": \"628051********7958\",<\/code> \"channelCode\": \"2\",<\/code> \"additionalInfo\":\"{\"rrn\":\"3345322009\", \"stan\":\"443554338\",\"maskedPan\":\"563546****8778\"}\"<\/code> } <\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Encrypted Request<\/h4>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n {<\/code> \"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=\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Response Message  field description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data Type<\/th> Required<\/th> Description<\/th><\/tr><\/thead> 1<\/td> responseCode<\/td> String<\/td> Required<\/td> TS response code.See Response Code Appendix below for response code mapping<\/td><\/tr> 2<\/td> institutionResponseMessage<\/td> String<\/td> Required<\/td> Response message of the core banking application<\/td><\/tr> 3<\/td> transactionReference<\/td> String<\/td> Required<\/td> Unique transaction reference sent in the transfer request.<\/td><\/tr> 4<\/td> institutionReference<\/td> String<\/td> Optional<\/td> This is the transaction reference by the core banking application (CBA) of the insititution.<\/td><\/tr> 5<\/td> institutionProcessingTime<\/td> String<\/td> Required<\/td> Date the request was processedThis can be in the format “dd- MM-yyyy HH:mm:ss”<\/td><\/tr> 6<\/td> action<\/td> String<\/td> Required<\/td> Indicates status of credit could be SUCCESS or FAILURE<\/td><\/tr> 7<\/td> institutionResponseCode<\/td> String<\/td> Required<\/td> Response code from Institution CBA before mapping to TS Response Code<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Response (success)<\/h5>\n\n\n\n {<\/code> \"institutionResponseMessage\": \"Success\",<\/code> \"institutionResponseCode\": \"00\",<\/code> \"transactionReference\": \"CR|ZIB|FBN|150120211439|402452\",<\/code> \"institutionReference\": \"85856FA886B34B63AA7FA315B1650D81\",<\/code> \"institutionProcessingTime\": \"15-01-2021 14:39:56\",<\/code> \"action\": \"SUCCESS\",<\/code> \"responseCode\": \"00\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Plain Response (failure)<\/h5>\n\n\n\n {<\/code> \"institutionResponseMessage\": \"FAILURE\",<\/code> \"institutionResponseCode\": \"98\",<\/code> \"transactionReference\": \"CR|ZIB|FBN|150120211439|402452\",<\/code> \"institutionReference\": \"85856FA886B34B63AA7FA315B1650D81\",<\/code> \"institutionProcessingTime\": \"15-01-2021 14:39:56\",<\/code> \"action\": \"FAILURE\",<\/code> \"responseCode\": \"98\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Encrypted Response (success)<\/h5>\n\n\n\n {<\/code> \"response\":\"hQEMAxpO4GU1IXNDAgf+LivjQxi6OXHLNCu6UiB23rkw8vcUFF6ZCIvTivQSUHi7gwp4fDkYhhAD2uYI66g03KpB5mAezku\/+XADPbhGpnUBJIL+KraISsLpiTh3DQBkmVcskshHDS4qHcS7pvK1lmwHGSe438bvmi59s8i\/nfzW6Qy2l+IOGmu+iB9QfTmwUJtID1DxzmS2DCGgGfcB5T0nGZMbH3jFW9Fw7deXZscHFVCu3Vp\/CY6HJH4isau3a69GkAUIqL8DCmE9PfoHwIRX7NFoWsE9CyB2HN6+NZBBg6bo+K6q4g8Zlx0h9+kVM9OGsC40thbgut\/yUensr0FpGNlOtTtqt3M3r+RC48nAHlWjtPgf3ZlXHfYdRQhyixLqKE7JB0H3c72uJd9J1nOPfLaGLa7RJgzkQBQ+dniUEjRUDHqrqdo+q\/eCjt8Gm1GZkCepKBcNVFYWOFGIQcic0XoazX2k+hVU070MuQjSZTwni5RcOsmzNJ3mpTKJCxbmpOIOdkMzPL0qCp0jE6\/bASTAQkSNukDWyhI2\/+c37CXy8wBtEyjxQiWLHHOwRw9rkcpjcaiB9DWxS00yKYsKUWhaAild9Eth0oZkGk9OZyCp1QEsrEv2fpJxCnE8ac0nlsm0MzY3H8CYDTNhuw==\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n ISW API(s)<\/h2>\n\n\n\n Credit Status Confirmation<\/h3>\n\n\n\n The credit status confirmation API enables the bank query transactions sent by the transfer service for credit, before the beneficiary is credited<\/p>\n\n\n\n Request Message description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data type<\/th> Required<\/th> Description<\/th><\/tr><\/thead> 1<\/td> transactionReference<\/td> String<\/td> Required<\/td> Unique transaction reference generated by TS and used in the original request.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Endpoint<\/strong><\/p>\n\n\n\n POST \/transfers\/transaction\/status<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Headers<\/strong><\/p>\n\n\n\n Authorization: Bearer {Passport Access Token}<\/code> Content-Type: application\/json<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Request<\/h5>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n {<\/code> \"transactionReference\": \"CR|SUN|FBP|310520202047|226464\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Response Message  field description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data Type<\/th> Required<\/th> Description<\/th><\/tr><\/thead> 1<\/td> responseCode<\/td> String<\/td> Required<\/td> Response code of the transaction in TS<\/td><\/tr> 2<\/td> responseMessage<\/td> String<\/td> Optional<\/td> Response message of the transaction in TS<\/td><\/tr> 3<\/td> transactionReference<\/td> String<\/td> Required<\/td> Unique transaction reference sent in the transfer request.<\/td><\/tr> 4<\/td> status<\/td> String<\/td> Required<\/td> Status of transaction in TS. Could be SUCCESS or FAILURE<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Response (success)<\/h5>\n\n\n\n HTTP Status: 200<\/code> {<\/code> \"responseCode\": \"00\",<\/code> \"transactionReference\": \"CR|SUN|FBP|310520202047|226464\",<\/code> \"responseMessage\": \"Approved or completed successfully\",<\/code> \"status\": \"SUCCESS<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Response (failure)<\/h5>\n\n\n\n HTTP Status: 503<\/code> {<\/code> \"responseCode\": \"91\",<\/code> \"transactionReference\": \"CR|SUN|FBP|310520202047|226464\",<\/code> \"responseMessage\": \"Approved or completed successfully\",<\/code> \"status\": \"FAILURE\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Authentication (Token Generation) API<\/h3>\n\n\n\n The authentication API enables the bank generate access tokens for authentication purposes.<\/p>\n\n\n\n In addition, the request body is sent as a URL encoded form. As a result, the following request parameters would be set:<\/p>\n\n\n\n Request Message description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Value<\/th> Data type<\/th> Required<\/th><\/tr><\/thead> 1<\/td> grant_type<\/td> client_credentials<\/td> String<\/td> Required<\/td><\/tr> 2<\/td> Scope<\/td> profile<\/td> String<\/td> Required<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Endpoint<\/h4>\n\n\n\n Endpoint<\/strong><\/p>\n\n\n\n POST \/passport\/oauth\/token<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Headers<\/h4>\n\n\n\n Headers<\/strong><\/p>\n\n\n\n Authorization - Basic <Base64Encoded string of 'client_id:client_secret'><\/code> Content-Type: application\/x-www-form-urlencoded<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Request<\/h5>\n\n\n\n Sample request<\/strong><\/p>\n\n\n\n grant_type=client_credentials&scope=profile<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Response Message  field description<\/h4>\n\n\n\n Field#<\/th> Field name<\/th> Data Type<\/th> Description<\/th><\/tr><\/thead> 1<\/td> access_token<\/td> String<\/td> The access token that would be used to consume the secure apis<\/td><\/tr> 2<\/td> expires_in<\/td> String<\/td> 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<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Response (success)<\/h5>\n\n\n\n {<\/code> \"access_token\":\"eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsicGFzc3BvcnQiXSwic2NvcGUiOlsicHJvZmlsZSJdLCJleHAiOjMwMTg1Mjk4ODksImp0aSI6IjBlYWYwMWIzLTM4M2QtNDFkNi1hOTgzLWI3OTIwNDU3ODBjMyIsImNsaWVudF9pZCI6InRlc3RjbGllbnQifQ.OaLlGSTLFHGu7553HNhzuBOIiQvdiNVNPAm5-opCq7JPugEG2ubPtLZLu2znr0aJkHR0BGiV2e9ZSrkp6cxYoT74SvY9b-2AE9giNdWpPgWMO6HqadL9re6ojkl9YU9uW_okjYUhTa-P_jOtWYUhbqi02SyUrN8m-SNI29IZPS-Q2J9Aq9zARiW7dVZWMBC8GHR_IL8V-GozaG782kIEUcBNfDGRnttV5qJwVpXomzyKlZDwEZKPOewh_1NVPvv7hDi79OfN63PiENvM4XLzDW9rFgKrRb6x43dpLfnoie1Id39eiCLGKX8ykrVEFg94jp1JCDpEDaexCcf05Dz5ag\",<\/code> \"token_type\": \"bearer\",<\/code> \"expires_in\": 43199,<\/code> \"scope\": \"profile\",<\/code> \"jti\": \"0eaf01b3-383d-41d6-a983-b792045780c3\"}<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Sample Response (failure)<\/h5>\n\n\n\n {<\/code> \"error\": \"invalid_request\",<\/code> \"error_description\": \"Missing grant type\"<\/code> }<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n API SECURITY <\/h2>\n\n\n\n All APIs should ONLY be made available over VPN by the bank to Interswitch.<\/p>\n\n\n\n PGP ENCRYPTION\/DECRYPTION<\/strong><\/h2>\n\n\n\n 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.<\/p>\n\n\n\n The public key generated by Transfer Service has the following properties: <\/p>\n\n\n\n name<\/th> value<\/th><\/tr><\/thead> Encryption Program<\/td> PGP (Pretty Good Privacy)<\/td><\/tr> Key Size<\/td> 2048<\/td><\/tr> Key Expiry<\/td> Never<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Keys for encryption would be generated and shared during integration.<\/p>\n\n\n\n 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<\/strong><\/p>\n\n\n\n Response Codes<\/h3>\n\n\n\n Response Code<\/th> Description<\/th> Response Message<\/th><\/tr><\/thead> 00<\/td> Transaction was successful<\/td> Approved or completed successfully<\/td><\/tr> 01<\/td> Source institution should be contacted<\/td> Contact source institution<\/td><\/tr> 05<\/td> Do not honour<\/td> Do not honour<\/td><\/tr> 06<\/td> Transaction failed for arbitrary reasons<\/td> General transaction failure<\/td><\/tr> 09<\/td> Transaction is in progress at middleware or other operational reasons.<\/td> Transaction in progress<\/td><\/tr> 10<\/td> CBA timeout at destination<\/td> Transaction in progress<\/td><\/tr> 12<\/td> The transaction is invalid<\/td> Invalid Transaction<\/td><\/tr> 13<\/td> Invalid Amount<\/td> Invalid Amount<\/td><\/tr> 14<\/td> The account type for this account is invalid<\/td> Account type is incorrect<\/td><\/tr> 15<\/td> No such issuer<\/td> Invalid Issuer<\/td><\/tr> 17<\/td> Middleware error returned for operations relating to customer authenticating the debit<\/td> Debit Authentication Error<\/td><\/tr> 18<\/td> Requery cannot be executed for transactions older than 5 days. This is not confirmation that the transaction failed\/ successful<\/td> Client requery cannot be executed for transactions older than 5 days<\/td><\/tr> 19<\/td> 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.<\/td> Pending transaction retry limit reached and status unknown<\/td><\/tr> 20<\/td> Invalid response received from processor<\/td> Invalid response received from CBA<\/td><\/tr> 21<\/td> Middleware received a response code that is not in its mapping configuration table<\/td> Response code not registered<\/td><\/tr> 25<\/td> Transaction record not found<\/td> Transaction not found<\/td><\/tr> 30<\/td> Bad request<\/td> Bad request<\/td><\/tr> 31<\/td> Invalid route configuration for sender<\/td> Route configuration error for issuer institution<\/td><\/tr> 39<\/td> The specified account does not exist<\/td> Invalid account<\/td><\/tr> 40<\/td> The sender account is invalid<\/td> Sender invalid<\/td><\/tr> 45<\/td> The specified account is closed<\/td> Account is closed<\/td><\/tr> 46<\/td> The specified account is dormant<\/td> Account is dormant<\/td><\/tr> 47<\/td> The specified account is blocked<\/td> Account is blocked<\/td><\/tr> 48<\/td> Inquiry Request was processed successfully but Credit Request was not received the configured retention period<\/td> Transaction Expired<\/td><\/tr> 49<\/td> Inquiry Request was not processed successfully within the configured retention period<\/td> Transaction Expired<\/td><\/tr> 51<\/td> The specified account balance has been reached<\/td> Account balance limit reached<\/td><\/tr> 52<\/td> The TSS at the crediting bank is not sufficiently funded<\/td> Transaction failed. Please contact administrator<\/td><\/tr> 56<\/td> Payment instrument not found to complete transaction<\/td> Payment Instrument not found<\/td><\/tr> 58<\/td> Transaction not allowed on channel specified\/ Channel code has not been mapped\/setup on the middleware or is inactive. No further action was taken.<\/td> Transaction not permitted on channel \/Channel does not exist<\/td><\/tr> 59<\/td> The transaction is marked as suspected fraud and not processed<\/td> Suspected fraud or security breach<\/td><\/tr> 61<\/td> Transaction limit exceeded<\/td> Source transfer limit exceeded<\/td><\/tr> 62<\/td> Withdrawal frequency exceeded<\/td> Withdrawal frequency exceeded<\/td><\/tr> 63<\/td> Security has been violated<\/td> Security Violation<\/td><\/tr> 64<\/td> Authentication token is not valid<\/td> Authentication token is not valid<\/td><\/tr> 79<\/td> Bvn record not maintained<\/td> Account no bvn maintained<\/td><\/tr> 80<\/td> Account name mismatch<\/td> Account name mismatch<\/td><\/tr> 81<\/td> The configured TSS is invalid (does not exist, PND, etc)<\/td> Invalid TSS account<\/td><\/tr> 82<\/td> The configured TSS could not be credited<\/td> Cannot credit TSS account<\/td><\/tr> 91<\/td> Middleware could not reach Core Banking Application \/ Middleware did not get a definite response from Core Banking Application<\/td> Could not reach Remote Service \/ Response timed out while attempting to reach remote service<\/td><\/tr> 92<\/td> Invalid route configuration for destination<\/td> Issue\/Error with routing configuration for the receiving institution<\/td><\/tr> 94<\/td> Transaction is a duplicate and is either in progress <\/td> Duplicate transaction<\/td><\/tr> 97<\/td> A system error occurred. Transaction status not confirmed.<\/td> A system error occurred. Transaction status not confirmed.<\/td><\/tr> 98<\/td> The specified account has reached the limit for this transaction<\/td> Account transaction limit reached<\/td><\/tr> 99<\/td> The transfer rate limit has been reached for the TSS account.<\/td> Transfer frequency reached<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Channel Codes<\/h3>\n\n\n\n Channel Code<\/strong><\/td> Description<\/strong><\/td><\/tr> 1<\/td> BANK BRANCH<\/td><\/tr> 2<\/td> WEB<\/td><\/tr> 3<\/td> DIRECT DEBIT<\/td><\/tr> 4<\/td> ATM<\/td><\/tr> 5<\/td> POS<\/td><\/tr> 6<\/td> MOBILE<\/td><\/tr><\/tbody><\/table><\/figure>\n","protected":false},"author":228,"featured_media":0,"parent":4133,"menu_order":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"spay_email":""},"doc_tag":[],"_links":{"self":[{"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs\/4144"}],"collection":[{"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/users\/228"}],"replies":[{"embeddable":true,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/comments?post=4144"}],"version-history":[{"count":2,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs\/4144\/revisions"}],"predecessor-version":[{"id":4656,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs\/4144\/revisions\/4656"}],"up":[{"embeddable":true,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs\/4133"}],"next":[{"title":"Transfer Service Core API","link":"https:\/\/sandbox.interswitchng.com\/docbase\/docs\/transfer-service-core-api-document\/transfer-service-core-api\/","href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/docs\/4146"}],"wp:attachment":[{"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/media?parent=4144"}],"wp:term":[{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/sandbox.interswitchng.com\/docbase\/wp-json\/wp\/v2\/doc_tag?post=4144"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}