Transfers

Get Bank List

GET /v1/api/banks

This endpoint is used to retrieve the details of all Nigerian commercial and micro-finance banks.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made

Sample Request

curl --location '{BASE_URL}/v1/api/banks' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": [
				{
            "name": "AMEGY MFB (9jaPay)",
            "code": "090629"
        },
				{
            "name": "Access Bank",
            "code": "044"
        },
				{
            "name": "United Bank For Africa",
            "code": "033"
        },
        {
            "name": "Zenith Bank",
            "code": "057"
        }
		]
}

Name Enquiry

POST /v1/api/transfers/name-enquiry

This endpoint is used to validate that a bank account is valid. Before initialising a funds transfer, the recipient account must be validated using this endpoint.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
bankCode	Yes	Body	String	The beneficiary’s bank code as seen in the banks list endpoint
accountNumber	Yes	Body	String	The beneficiary’s bank account number

Sample Request

curl --location '{BASE_URL}/v1/api/transfers/name-enquiry' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "bankCode": "090629", "accountNumber": "2000011041" }'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Account Details retrieved",
    "statusCode": "00",
    "data": {
        "accountName": "Michael Onyirimba",
        "accountNumber": "2000011041",
        "bankCode": "090629",
        "nameEnquiryReference": "366207243720113708AWG5gOTppVaj"
    }
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "Account Number must be 10 digits",
    "statusCode": "09"
}

Transfer

POST /v1/api/transfers

This endpoint is used to initiate a funds transfer from a non-virtual account.

POST /v1/api/transfers/virtual-account

This endpoint is used to initiate a funds transfer from a virtual account.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
paymentReference	Yes	Body	String	The unique identifier for the transaction. This is generated by the client and will be used to query the transaction status.
senderAccountNumber	Yes	Body	String	The account number to be debited
senderAccountName	Yes	Body	String	The account name of the debit account
recipientAccountNumber	Yes	Body	String	The beneficiary’s account number
recipientAccountName	Yes	Body	String	The beneficiary’s account name
recipientBankCode	Yes	Body	String	The beneficiary’s bank code
amount	Yes	Body	String	The amount (in Kobo) that is to be transferred
nameEnquiryReference	Yes	Body	String	TThe reference gotten from the name enquiry which must be unique per transaction
narration	Yes	Body	String	The narration of the transfer

Sample Request

curl --location '{BASE_URL}/v1/api/transfers' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "paymentReference": "00000001", "senderAccountNumber": "9000002140", "senderAccountName": "TOBI ADELAJA 29", "recipientAccountNumber": "2000011041", "recipientAccountName": "Michael Onyirimba", "recipientBankCode": "090629", "amount": "100000", "nameEnquiryReference": "366207243720113708AWG5gOTppVaj", "narration": "test transfer" }'

Sample Response (200 - OK, Success)

{
    "status": "SUCCESS",
    "message": "Your transfer of ₦1,000.00 to Michael Onyirimba is successful",
    "statusCode": "00",
    "data": {
        "id": "b4a48d6f-cb8c-47df-a174-0ae0b2924ab5"
    }
}

Sample Response (200 - OK, Procesing)

{
    "status": "PROCESSING",
    "message": "Your transfer is being processed.",
    "statusCode": "01",
    "data": {
        "id": "b5783cf1-f139-4d2c-9260-446574cd90ff"
    }
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "Duplicate payment reference.",
    "statusCode": "26"
}

Transaction Status Query (TSQ)

GET /v1/api/transfers/tsq/{reference}

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
reference	Yes	Path	String	The transaction reference

Sample Request

curl --location '{BASE_URL}/v1/api/transfers/tsq/{reference}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK, Successful Transaction)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "id": "b4a48d6f-cb8c-47df-a174-0ae0b2924ab5",
        "paymentReference": "00000002",
        "sessionId": "999999240226070016257381097481",
        "amount": 100000,
        "status": "Success",
        "transferDate": "2024-02-20T12:37:32.42989Z"
    }
}

Sample Response (200 - OK, Failed Transaction)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "id": "b5783cf1-f139-4d2c-9260-446574cd90ff",
        "paymentReference": "00000003",
        "amount": 100000,
        "status": "Failed",
        "transferDate": "2024-02-20T12:40:03.691565Z"
    }
}

Note

Please note that the outer status field only signifies whether TSQ request is successful or not (request status). The status field in the data object contains the final status of a transaction (transaction status).