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
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
{ "error": "invalid_request", "error_description": "Missing grant type" }
Transfer API
Base URI: https://sandbox.interswitchng.com
1. Credit Inquiry Request
This endpoint receives a request to confirm if an account specified in destinationAccountNumbercan 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.
Institution code , one of the codes assigned in ISW core
5
transactionAmount
Long
MAX
Optional
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
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
2. 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. If the source institution transaction limit is exceeded the request will fail and return a transaction limit exceeded response.
Version 1
Endpoint
POST <base URI>/transfers/accounts/credits/completion
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.
6
sourceAccountName
String
200
Mandatory (If not provided in Credit Inquiry request)
Source Account Name
7
sourceAccountNumber
String
50
Mandatory (If not provided in Credit Inquiry request)
Source Account Number
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.
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.
6
sourceAccountName
String
200
Mandatory (If not provided in Credit Inquiry request)
Source Account Name
7
sourceAccountNumber
String
50
Mandatory (If not provided in Credit Inquiry request)
Source Account Number
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
8
remoteTransactionReference
Transaction reference returned by the destination institution CBA
The status should be used to interpret 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 real-time
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
EXPIRED
Transaction Inquiry has been terminated as Credit Request was not received within the configured retention period. This is a final state which will not be settled
OFFLINE_APPROVAL
Credit to CBA for transaction was not confirmed successfully, however Transaction will be SETTLED and treated as SUCCESSFUL. Introduced to cater to isw-agency-banking transactions and other transactions that might fall into the use-case
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
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 BVNmaintained
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.