Register

Debit Wallet API

Make fund transfers from customized wallets/accounts (source).

Test Source Account: 0410530975

Test Destination Account: 0280100171

How does it work?

The Debit Wallet API allows clients to make fund transfers from customized wallets/accounts generated by them. This API works as both an intrabank and interbank transfer service; destination accounts can belong to any bank in Nigeria.

  1. The client is profiled to perform a funds transfer. This activity is done in the backend by the bank, and mapped to the clients access(x-api) key.

  2. The client makes an enquiry on the sourceAccountNumber.This is to ensure the client has the permission to debit said wallet/account.

  3. The client makes an enquiry to confirm the destination account information.

  4. Based on the amount band, the client makes an enquiry to confirm NIP charges. This only applies if the destination account number is non-Wema. (Note: This NIP charge will be taken care of by the bank; there is no need to add it to your request.)

  5. The client initiates a payout request and gets a PENDING status.

  6. A callback is made to the client to authorize the transaction - debit to the source account and credit to the destination account/wallet.

  7. The bank proceeds to fulfill the transfer request.

  8. Client receives a notification of transaction status.

Note: You will need to profile your Authentication Callback URL for this endpoint to avoid getting the authentication failed error while testing.

Go Live

Step 1: Name Enquiry - Source Account

Request URL

POST - {baseURL}/debit-wallet/api/Shared/AccountNameEnquiry/Wallet/{accountNumber}

Try it out !

  1. The client is required to pass a valid access(x-api) value in the header of their request. This value would be provided by the bank.

  2. Client validates the source account number using the request URL.

  3. A successful call to this endpoint would return the accountName name of the beneficiary.

Step 2: Get List of Banks

Request URL

GET - {baseURL}/debit-wallet/api/Shared/GetAllBanks

This endpoint returns a list of all banks in Nigeria. Clients are to select destination bank name and code from this list.

Try it out!

Step 3: Name Enquiry - Destination Account

Request URL

GET - {baseURL}/debit-wallet/api/Shared/AccountNameEnquiry/{bankCode}/{accountNumber}[?channelId]

Try it out !

  1. Clients are to pass the bankCode retrieved from the list of banks, along with the destinationAccountNumber, as query parameters to perform a name enquiry on the destination account.

  2. A successful call to this endpoint would return details of the destination account number, as well as a list of charge fees based on amount bands.

Step 4: Get NIP Charges

Request URL

GET - {baseURL}/debit-wallet/api/Shared/GetNIPCharges

This endpoint returns a list of all charges base on transaction type and amount.

Try it out !

Step 5: Process Funds Transfer

Request URL

POST - {baseURL}/debit-wallet/api/Shared/ProcessClientTransfer

Try it out !

  1. The client initiates a request for transfer to destinationAccountNumber, specifying amount and custom transactionReference and narration (set useCustomNarration as true).

  2. The client is expected to pass a securityInfo. This should be an encrypted value whose signature is known only by the client. The client should be the only one with the key to decrypt its value. This value serves as the mandate for authorization of debit.

  3. The bank makes an authentication request to the client's authentication URL to confirm the securityInfo of the transaction. The client is expected to validate this authentication request for the transaction to be executed. Authentication request and response models can be seen below.

  4. The client gets a PENDING transaction status while the transaction is being executed.

  5. Client receives final transaction status via a callback URL.

Note: Transaction statuses are PENDING, SUCCESSFUL or FAILED.

Note: Your security information is unique to you and can be an alphanumeric string of any length. It helps secure your transactions and authenticate every transaction initiated by you, preventing unauthorized access by third parties.

Authentication Model

Request Model

  1. The bank makes this request to the client to authorize this transaction request.

  2. The authorization callback URL is profiled by the bank and mapped to the client's access(x-api) key.

  3. The bank makes an authentication request to the client by passing the securityInfo and custom transactionReference specified in the payout request.

  4. Clients should ensure that the encryption used for the securityInfo parameter is highly secure, dynamic, and unique to each transaction request.

  5. This endpoint should not take any headers as it is generic to all clients using this service.

Expected Response Model

  1. Client responds with the transactionReference and authorized status of the authentication request.

  2. Authentication status

    • authorized = true; if securityInfo is valid

    • authorized = false; if securityInfo could not be validated.

The Callback Model

Clients are to build their callback following the specification below. Your callback URL would be profiled to your assigned channelId.