Transfer Service

API Documentation
Overview
The Transfer Service is a mediating service that receives inter bank transfer requests from a source
and routes it to the intended institution(s). This service will expose 3 APIs to handle 3 classes of
transactions ( a Credit transaction, a Debit Transaction and a Credit and Debit transaction), a
Transfer Inquiry API (to either the Source Institution, Destination Institution or both as the
case may be) ,a Transaction Query API (to either the Source Institution, Destination Institution
or both as the case may be) and a Reversal API to the Source Institution.It is, thus necessary to
consider the service as serving two set of endpoints, Downstream (Source) and the Upstream
(Destination).

Thus there are 6 API calls to the Transfer Service and these calls are redirected as Middleware
API calls made out by the Transfer Service to be implemented by services in the destination
bank.

NOTE: All date formats are in the format dd-MM-yyyy HH:mm:ss.

Base URI for requests to Transfer Service : /api/v1/transfers/

1. Credit Inquiry Request

This endpoint receives a request to confirm if an account specified in accountNumber can be

credited with a specified amount .

In the response received from the inquiry, the account details are to be returned and status of the
account for the credit.
The accountNumber is the account number to be confirmed as allowed to be credited. The inquiry
request is thus routed to the destination institution middleware and processed accordingly. In the
response received from the inquiry, the account details are to be returned and status of the account
for the credit(i.e if the account can be credited with the amount or not).

The processing within the service and at the destination institution is timed and after a configured
period of time if the processing is not done, the request is timed out and a timed out response is
returned to the caller and this ends the transaction.

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 if one was initially sent.

Headers

Authorization - Passport Access Token, that has resource 'transfer-service-core' and an

'institution_id' and 'core_id' key value pair in it's additional info. The institution id value, must
exist in the ts configuration db.

Request Message description

Field Data Max

Field name Classification Description
# type length
Source Account
1 sourceAccountNumber String 20 Recommended
number
2 sourceAccountName String 200 Recommended Source Account Name
Destination Account
3 destinationAccountNumber String 20 Mandatory
Number
Institution code , one
4 destinationInstitutionCode String 3 Mandatory of the codes assigned
in ISW core
Amount in minor
5 transactionAmount Long MAX Mandatory
denomination
ISO currency code (
6 currencyCode String 3 Mandatory
ISO Numeric Code)
Unique reference per
7 clientRef String 50 Mandatory
institution
 Internationally
8 mobileNumber String 20 Optional formatted mobile
number
Customer Email
9 emailAddress String 100 Optional
Address
10 paymentLocation String MAX Optional Payment Location
11 channelCode Integer MAX Mandatory Channel ID
12 terminalId String 8 Mandatory TerminalID

Response Message description

Field Data
Field name Description
# type
1 responseCode String Response Code
2 responseMessage String Response Message
3 accountName String Account Name
4 accountNumber String Account Number
Initial reference sent by client if sent, or one
5 clientRef String
auto generated by system
6 transactionReferenceNumber 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
Receiver’s address. At present this attribute
11 address String
will not be used for any further processing.
Country code of the transaction. This is the
12 countryCode String
ISO country code.
If the account validation is successful for
13 canCredit Boolean
credit this will be true
Endpoint
POST <base URI>/inquiries/credit
Headers
Content-Type: application/json

Sample Request

Sample request
{
"destinationAccountNumber " : "0123456789",
"sourceAccountNumber": "8096080",
"sourceAccountName": "Tolani Moshood",
"destinationInstitutionCode":"FBN",
"amount": 300000,
"currencyCode": "566",
"clientRef" : "abc1222223knkj",
"mobileNumber":"2348089546016",
"emailAddress" : "siryaya@gmail.com",
"channelCode":2
}

Sample Response (success)

HTTP Status: 200

{
"responseCode":"00",
"accountName": "Tomi Peters",
"canCredit": true,
"responseMessage":"Successful",
"accountNumber":"0123456789",
"transactionReference":"CR|APP|FBN|14062018184103|189"
}

Sample Response (disabled initiating institution )

HTTP Status: 400

{
"responseCode":"INITIATING_INSTITUTION_NOT_ENABLED",
"responseMessage":" This institution is not enabled to initiate this
transaction",
"transactionReference":"CR|APP|FBN|14062018 184103|189"
}

Sample Response (account cannot be credited)

HTTP Status: 400

{
"responseCode":"50",
"responseMessage":"The specified account does not exist",
"transactionReference":"CR|APP|FBN|14062018 184103|189"
}
2. Account Credit Request With Credit Inquiry Ref

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. The amount 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 to a queue for processing and a
'Submitted' response is sent back to the calling app. The destination institution middleware, listens
on the queue for credit requests,processes them in turn and writes responses back to the queue.
The transfer service, listens on the queue as well for credit transaction responses and completes
the transaction in it's DB.

Request Message description

Field Data Max

Field name Classification Description
# type length
1 transactionAmount Long MAX Mandatory Amount in minor denomination
2 narration String 100 Optional Narration
Unique reference per client. If
present in inquiry, should be the
3 clientRef String 50 Optional same. if absent, transaction
reference must be present in
request
Additional Information. Could
4 additionalInfo String MAX Optional contain initial debit details (e.g
mobile app implementation)
Transaction Reference returned
from credit inquiry. If absent,
5 transactionReference String 50 Optional
credit ref must be present in
request
Endpoint
POST <base URI>/accounts/credits/completion

Response Message description

Field
Field name Description
 #
1 transactionReference Unique transaction reference
The status of the transfer request, one of (SUBMITTED,
2 responseCode
FAILED OR PENDING)

Sample Request

{
"transactionAmount": 300000,
"clientRef" : "abc1222223knkj",
"narration":"For your wedding"
}

Sample Response (success)

HTTP Status: 200

{
"transactionReference":"CR|APP|FBN|14062018 184103|189",
"responseCode": "SUBMITTED"
}

Sample Response (invalid destination institution)

HTTP Status: 400

{
"errorCode":"400",
"errorMessage":"Invalid Amount"

3. Requery Transfer Request

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

Request Message description

Field
Data
Field name Max Classification Description
type
#
1 clientRef String 50 Optional Unique reference per institution
 Unique transaction reference
2 transactionReference String 16 Required across institutions, generated and
returned by TS
Endpoint
POST <base URI>/transfers/accounts/credits/requery
Headers
Content-Type: application/json

Sample Request

{
"transactionReference": "CR|FBN|DMD|12022019133726|50"
}

Response Message field description

Field # Field name Description

1 transactionReference Transaction Reference
2 action Proposed action to be carried out by client
3 status Transaction status

Sample Response (success)

HTTP Status: 200

{
"transactionReference": "CR|FBN|DMD|14022019103041|13",
"action": "SUCCESS",
"status": "SUCCESS"
}

HTTP Status: 200

{
"transactionReference": "CR|FBN|GTB|12022019180100|58",
"action": "FAILURE",
"status": "FAILURE"
}

HTTP Status: 200

{
 "transactionReference": "CR|FBN|GTB|1202201430|158",
"action": "REQUERY",
"status": "PENDING"
}

Sample Response (failure)

HTTP Status: 404

{
"errorCode": "404",
"errorMessage": "Credit transaction with this reference could not be
found"
}

Response Codes
Transfer credit request response codes

Transfer status response codes

Response
Description Response Message
Code
Approved or completed
00 Transaction was successful
successfully
Transaction is in progress at middleware or other
09 Transaction in progress
operational reasons.
Transaction retry limit has been reached. The
Pending transaction retry
middleware will no longer attempt this transaction.
19 limit reached and status
Except a requery and it receives a response code for
unknown
which it can retry.
94 Transaction is a duplicate and is either in progress Duplicate transaction
25 Transaction record not found Transaction not found
Transaction was not queued successfully. A job will
09 Transaction in progress
pick this transaction at a later date to requeue.
09 CBA timeout Transaction in progress
30 Bad request Bad request
 Channel code has not been mapped/setup on the
12 Channel does not exist
middleware or is inactive. No further action was taken.
Destination institution code has not been mapped/setup Destination institution
12
on the middleware or ts or is inactive does not exist
Invalid response received
20 Invalid response received from processor
from CBA
Middlware received a response code that is not in its Response code not
20
mapping configuration table registered
39 The specified account does not exist Invalid account
45 The specified account is closed Account is closed
45 The specified account is dormant Account is dormant
Account balance limit
51 The specified account balance has been reached
reached
The specified account has reached the limit for this Account transaction limit
98
transaction reached
45 The specified account is blocked Account is blocked
12 The account type for this account is invalid Account type is incorrect
Account no bvn
79 Bvn record not maintained
maintained
80 Account name mismatch Account name mismatch
05 Do not honour Do not honour
Transaction failed.
The TSS at the crediting bank is not sufficiently
51 Please contact
funded
administrator
The configured TSS is invalid (does not exist, PND,
81 Invalid TSS account
etc)
39 The sender account is invalid Sender invalid
12 The transaction is invalid Transaction invalid
The transaction is marked as suspected fraud and not Suspected fraud or
59
processed security breach
The transfer rate limit has been reached for the TSS Transfer frequency
98
account. reached
Cannot credit TSS
82 The configured TSS could not be credited
account
91 Middleware could not reach Core Banking Application Could not reach CBA
Middleware did not get a definite response from Core Response timed out at
91
Banking Application CBA
Contact source
01 Source institution should be contacted
institution
Transaction not
58 Transaction not allowed on channel specified
permitted on channel
Source transfer limit
61 Transaction limit exceeded
exceeded
Withdrawal frequency
61 Withdrawal frequency exceeded
exceeded
63 Security has been violated Security Violation
General transaction
06 Transaction failed for arbitrary reasons
failure
An unexpected error occurred with one of the critical
06 General system error
systems. Manual intervention required.