1. Authentication API

---

This API handles obtaining an access token for authentication

URL

base URI : https://sandbox.interswitchng.com/transfers

Access tokens for all grant types can be obtained from the following URL:

https://sandbox.interswitchng.com/passport/oauth/token

HTTP Verb: POST

Headers

The Authentication API endpoints require a Basic authorization header. In addition, the request body is sent as a URL encoded form. As a result, the following headers would be set:

Authorization: Basic <Base64Encoded string of client_id:client_secret>

Content-Type: application/x-www-form-urlencoded

Client Credentials Grant Type

Use this endpoint to get an access token using client credentials

Request Body

Field	Type	Required
grant_type	String	Required
scope	String	Optional

Sample Request Body

grant_type=client_credentials&scope=profile

Response

Field	Description
access_token	The access token that would be used to consume the secure apis
expires_in	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"}

2. Credit Inquiry Request

---

This endpoint receives a request to confirm if an account specified in destinationAccountNumber can be credited with a specified amount . 

On the successful completion of a credit inquiry, the transaction is logged in Transfer service and awaits a completion update with the same client reference sent in the inquiry or the transaction reference returned in the inquiry response.

Endpoint

POST <base URI>/inquiries/credit

Headers

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

Request Message description

Field #	Field name	Data type	Max length	Classification	Description
1	sourceAccountNumber	String	50	Mandatory	Source Account number
2	sourceAccountName	String	200	Mandatory	Source Account Name
2	sourceBankVerificationNumber	String	100	Recommended	Source Customer Bank Verification Number
3	destinationAccountNumber	String	20	Mandatory	Destination Account Number
4	destinationInstitutionCode	String	3	Mandatory	Institution code , one of the codes assigned in ISW core
5	transactionAmount	Long	MAX	Mandatory	Amount in minor denomination
6	currencyCode	String	3	Mandatory	ISO currency code ( ISO Numeric Code)
7	clientRef	String	50	Mandatory	Unique reference per transaction
8	mobileNumber	String	20	Optional	Internationally formatted mobile number
9	emailAddress	String	100	Optional	Customer Email Address
10	paymentLocation	String	MAX	Optional	Payment Location
11	channelCode	Integer	MAX	Mandatory	Channel ID. Channel Appendix below for channel definitions
12	terminalId	String	8	Optional	TerminalID
13	destinationInstitutionAlias	String	–	Optional	Institutions Alias. Can be used instead of destinationInstitutionCode
14	mcc	String	4	Optional	The classification of the merchant’s type of business product or service.
14	rrn	String	12	Optional	A reference number supplied by the system retaining the original source information and used to assist in locating that information or a copy thereof.
15	paymentLocation	String	40	Optional	The name and location of the card acceptor (such as a merchant or an ATM).

Response Message description

Field #	Field name	Data type	Description
1	responseCode	String	Response Code
2	responseMessage	String	Response Message
3	accountName	String	Account Name
4	accountNumber	String	Account Number
5	clientRef	String	Initial reference sent by client if sent, or one auto generated by system
6	transactionReference	String	Unique transaction reference
7	bankVerificationNumber	String	Bank Verification Number
8	kycLevel	String	KYC Level
9	accountType	String	Current, Savings or Credit
10	accountCurrency	String	ISO currency
11	address	String	Receiver’s address.   At present this attribute will not be used for any further processing.
12	countryCode	String	Country code of the transaction. This is the ISO country code.
13	canCredit	Boolean	If the account validation is successful for credit this will be true. Note: If true allow customer to proceed to complete the credit otherwise, fail the transaction. This is usually because the account is dormant, or the account cannot receive the amount specified.
14	systemResponseCode	String	System Response code that is sometimes included in response in case of exceptions in the system. This helps with issue resolution.
15	action	String	Action on transaction as received from the middleware
16	settlementStatus	Status	Settlement status of  inquiry transaction. Default settlement status for Inquiry is NEW

Sample request

{ "destinationAccountNumber " : "0123456789", "sourceAccountNumber": "8096080", "sourceAccountName": "Tolani Moshood", "destinationInstitutionCode":"ABP", "transactionAmount": 300000, "currencyCode": "566", "clientRef" : "abc1222223knkj", "mobileNumber":"2348089546016", "emailAddress" : "siryaya@gmail.com", "channelCode":2,    "paymentLocation": "PBL,T,10360057075012,Adubiaro, DeborLaNG"}

Sample Response (success)

HTTP Status: 200  {"accountType": "SAVINGS","accountCurrency": "NGN","address": "1 AYANBOYE STREET ANTHONY KOSOFE LAGOS","responseCode": "00","responseMessage": "Approved or completed successfully","transactionReference": "CR|SUN|ABP|250720201707|237233","bankVerificationNumber": "1234565667","kycLevel": "1","canCredit": true,"settlementStatus": "NEW","action": "SUCCESS"}

Sample Response (invalid account)

HTTP Status: 409 Conflict{ "clientRef": "abc1222223knkj", "responseCode": "39", "responseMessage": "Invalid Account", "transactionReference": "CR|SUN|ABP|231120201142|244092", "canCredit": false, "action": "FAILURE" }

3. Account Credit Request With Credit Inquiry Reference or Transaction Reference

---

This endpoint receives a request to close an open credit inquiry by performing the credit transaction. The credit inquiry to be closed is contained in the clientRef field or transactionReference field. The transactionAmount to be credited is also included in the request.The request is processed and routed to the destination institution to effect the credit. The credit request is pushed for processing and a response is sent back to the calling application.

EndpointEndpoint

POST <base URI>/accounts/credits/completion

Headers

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

Request Message description

Field #	Field name	Data type	Max length	Classification	Description
1	transactionAmount	Long	MAX	Mandatory	Amount in minor denomination
2	narration	String	200	Mandatory	Narration
3	clientRef	String	50	Required	Unique reference per client. If present in inquiry, should be the same. N:B: You either client Ref or Transaction Reference in your payload but you cannot use both.
4	additionalInfo	String	MAX	Optional	Additional Information. Could contain initial debit details (e.g mobile app implementation)
5	transactionReference	String	50	Required	Transaction Reference returned from credit inquiry. N:B: You either client Ref or Transaction Reference in your payload but you cannot use both.

Response Message description

Field#	Field name	Description
1	transactionReference	Unique transaction reference
2	responseCode	The response code of the transaction see appendix for response code details
3	responseMessage	The descriptive response message
4	status	The status of the transaction. See transaction status appendix. Use the status mappings to determine if the transaction succeeded or not.
5	clientRef	The clientRef of the transaction
6	systemResponseCode	System Response code that is sometimes included in response in case of exceptions in the system. This helps with issue resolution.
7	settlementStatus	Settlement status of the credit transaction

Sample Request one

{"transactionAmount": 300000,"clientRef" : "abc1222223knkj","additionalInfo":"{\"sourceBvn\":\"1111111\",\"sourceKycLevel\":\"1\"}","narration": "For your wedding"}

Sample Request two

{"transactionAmount": 300000,"transactionReference": "CR|SUN|ABP|250720201707|237233","additionalInfo":"{\"sourceBvn\":\"1111111\",\"sourceKycLevel\":\"1\"}","narration": "For your wedding"}

Sample Response (success)

HTTP Status: 200 {"responseCode": "00","transactionReference": "CR|FBN|DMD|28032019102410|4237","responseMessage": "Approved by financial institution","status": "SUCCESS","clientRef": "1234-5678" ,"settlementStatus": "SUCCESSFUL"}

4. Requery Transfer Request

---

This endpoint queries a transfer using the original clientRef and/or transactionReference returned by the Transfer Service.

EndpointEndpoint

POST <base URI>/transfers/accounts/credits/requery

Headers

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

Request Message description

Field#	Field name	Data type	Max	Classification	Description
1	clientRef	String	50	Optional (if transactionReference is provided)	Unique reference per institution
2	transactionReference	String	16	Optional (if clientRef is provided)	Unique transaction reference across institutions, generated and returned by TS

Response Message  field description

Field#	Field name	Description
1	transactionReference	Unique transaction reference
2	responseCode	The response code of the transaction see appendix for response code details
3	responseMessage	The descriptive response message
4	status	The status of the transaction. See transaction status appendix. Use the status mappings to determine if the transaction succeeded or not.
5	clientRef	The clientRef of the transaction
6	settlementStatus	Settlement status of the credit transaction

Sample Request With Transaction Reference

{ “transactionReference”: “CR|SUN|FBP|310520202047|226464” }

Sample Request With Client Reference

{ “clientRef”: “SUN|ITF|NA|FBP|1235645654|98776” }

Sample Response (success)

HTTP Status: 200{"responseCode": "00","transactionReference": "CR|SUN|FBP|310520202047|226464","responseMessage": "Approved or completed successfully","status": "SUCCESS","clientRef": "SUN|ITF|NA|FBP|1235645654|98776","settlementStatus": "SUCCESSFUL"}

1. 
   

List of Receiving Institutions

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

Sample Request
GET host /transfers/institutions?perPage=200&page=1

Sample Response
HTTP 200 OK
{
“total”: 515,
“perPage”: 200,
“page”: 1,
“institutions”: [
{
“institutionId”: “1”,
“institutionCode”: “AAB”,
“institutionName”: “Actual African Bank”
},
{
“institutionId”: “2”,
“institutionCode”: “AGB”,
“institutionName”: “Actual Global Bank”
},
…
]
}

Request Message description

Field#	Field name	Data type	Max	Classification	Description
1	clientRef	String	50	Required	Unique reference per institution
2	transactionReference	String	16	Optional (if clientRef is provided)	Unique transaction reference across institutions, generated and returned by TS

5. Appendix

---

Transaction Statuses

The status should be used to interprete the transaction response code for simplicity. These can be received during credit completion, requery, and transaction update callback.

Status	Meaning
SUCCESS	Transaction approved and completed successfully. Credit hit beneficiary account realtime
FAILURE	Transaction failed permanently
TRANSACTION_IN_PROGRESS	Transaction status is currently undergoing automated confirmation. Final response will be shared via a call to the requery API
PENDING	Transaction status unknown and cannot be confirmed from remote institution. Transaction will be settled and dealt with through the arbitration process if necessary. Please treat as SUCCESSFUL
NEW	This states that the Inquiry can be retried as the Inquiry request is yet to be completed
OPEN	Transaction Inquiry was successful and transaction is now open for a Credit request
ERROR	Transaction is in a final state and a user is re-attempting to trigger a duplicate credit request. Recheck transaction details and try again

NOTE: The transaction STATUS gives a true picture of the transaction and should be paid attention to mostly. The response codes define the different scenarios that could happen around the transaction processing

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