Register

Debit Wallet API

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

How does it work?

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

  1. The client is profiled to perform funds transfer. This activity is done backend by the bank, and mapped to the clients access 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 destination account number is non-Wema.

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

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

  7. The bank proceeds to fulfill transfer request.

  8. Client receives a notification of transaction status.

Go Live

Step 1: Name Enquiry - Source Account

Request URL

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

Try it out !

  1. Client is required to pass a valid access 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 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 list of banks, along with the destinationAccountNumber as query parameters to perform name enquiry on destination account.

  2. A successful call to this endpoint would return details of the destination account number, as well as a list of chargeFee 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. Client initiates request for transfer to destinationAccountNumber, specifying amount and custom transactionReference and narration (set useCustomNarration as true).

  2. 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 using the securityInfo to confirm 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 status are PENDING, SUCCESSFUL or FAILED.

Authentication Model

Request Model

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

  2. Authorization callbackURL is profiled by the bank, and mapped to the clients access key.

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

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

  5. This endpoint should not take any header 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.