Transfer Service Core API

Transfer service core API also known as Outbound service: This API allows banks or other financial institutions to transfer money to other banks or financial Institutions

In this section, we have outlined the steps needed for an efficient integration.

Step 1 - Make a call to the credit Inquiry request API

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 the 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 /inquiries/credit

Body Parameters

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. This is obtained when you fetch a bank list. Find more information here
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. Read more here
12	terminalId	String	8	Optional	TerminalID
13	destinationInstitutionAlias	–	-	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 retains the original source information and is 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 JSON request

{
"destinationAccountNumber " : "0123456789",
"sourceAccountNumber": "8096080",
"sourceAccountName": "Tolani Moshood",
"destinationInstitutionCode":"ABP",
"transactionAmount": 300000,
"currencyCode": "566",
"clientRef" : "abc1222223knkj",
"mobileNumber":"2348089546016",
"emailAddress" : "[email protected]",
"channelCode":2,    "paymentLocation": "PBL,T,10360057075012,Adubiaro, DeborLaNG"}

This is what a typical successful or invalid response would look like

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

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

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

Endpoint

{
  "endpoint": "POST <base URI>/accounts/credits/completion",
  "headers": {
    "Authorization": "Bearer {Passport Access Token}",
    "Content-Type": "application/json"
  }
}

Body Parameters

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

This is what a typical successful response would look like

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

Step 3 - Query the transaction

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

Endpoint

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

Headers

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

Body Parameters

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

Using either the transactionReference or clientRef

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

{
  "clientRef": "SUN|ITF|NA|FBP|1235645654|98776"
}

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. Use the status mappings to determine if the transaction succeeded or not. Read more on status here
5	clientRef	The clientRef of the transaction
6	settlementStatus	Settlement status of the credit transaction

Sample Response (success)

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

How to fetch a List of banks/Institutions

This endpoint allows you to fetch the list of banks which you can send money to

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.

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

The response will look like this :

{
  "total": 515,
  "perPage": 200,
  "page": 1,
  "institutions": [
    {
      "institutionId": "1",
      "institutionCode": "AAB",
      "institutionName": "Actual African Bank"
    },
    {
      "institutionId": "2",
      "institutionCode": "AGB",
      "institutionName": "Actual Global Bank"
    },
    ...
  ]
    }