NGN Bank Transfers - Direct Charge

This is one of the ways to process NGN payments using bank transfers. The section below will guide you through the process of accepting NGN payments using the direct API method.

Workflow Overview

Study this diagram below to understand the customer journey workflow

1. When your customer is ready to make an NGN payment, you can make the initial collection API request to the gateway, for which an acknowledgement will be done with 202 HTTP response code (you can optionally store the references). Show the customer a loading screen.

2. If there are no issues with the request, the DusuPay platform will proceed to obtain virtual bank details and trigger the transaction.processing event callback/webhook as described in the steps below. Details (charge information + account details) from this payload can be displayed to the customer.

3. As a precaution, listen to the request.failed and transaction.failed event callbacks just in case the request fails before obtaining the bank details. The reason for failure would be part of the callback payload and it's recommended that it's displayed to the customer.

4. If there was no error, the customer can follow the instructions to transfer funds to the account.

5. On success, the bank would notify the DusuPay platform, which would in turn notify you the merchant via your configured callback URL. The customer can be show the success screen.

We recommend that this activity is tracked in your local/platform databases and poll for transaction status from your own data store and update the user interface accordingly. The DusuPay platform automatically retries callbacks if your platform doesn't respond as expected.

Step 1: Obtain the required data for the payment request

The table below describes the request parameters that are used for the collection/charge request. Most/all will be collected from the paying customer.

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. It must be at least 8 characters long. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API
transaction_method	String	true	The transaction method to be used. This will be BANK for this request
currency	String	true	The 3-character ISO currency code for the request currency
amount	Number	true	The amount being requested
provider_code	String	true	The provider code as obtained from the payment options list
customer_name	String	false	The name of the customer
customer_email	String	false	The email of the customer
description	String	true	The description/narration for the transaction. Between 10-30 characters
charge_customer	Boolean	false	Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge
allow_final_status_change	Boolean	false	Whether or not the final transaction status can be altered as described here. By default, this is true to mean DusuPay will alter the final transaction status under the circumstances described.

After collecting the necessary bank payment information from your customer, prepare your request payload as demonstrated below.

{
	"merchant_reference": "auto",
	"transaction_method": "BANK",
	"currency": "NGN",
	"amount": 4000,
	"provider_code": "bank_ng",
	"customer_email": "[email protected]",
	"customer_name": "JOHN DOE",
	"description": "Test Collection",
	"charge_customer": false,
	"allow_final_status_change": true
}

POST https://sandboxapi.dusupay.com/collections/initialize

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://sandboxapi.dusupay.com/collections/initialize" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "BANK",
        "currency": "NGN",
        "amount": 4000,
        "provider_code": "bank_ng",
        "customer_email": "[email protected]",
        "customer_name": "JOHN DOE",
        "description": "Test Collection",
        "charge_customer": false,
        "allow_final_status_change": true
    }'

202: Accepted - Request acknowledged for processing

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "DUSUPAYZAERK2SBE6WJAG",
        "merchant_reference": "MCTREFQSSBHMHU3RCTLA"
    }
}

400: Bad Request - Request is not formed as expected

Step 2: Handle the payment instructions webhook

If the request in step 1 is successful and responds with an acknowledgement (HTTP code 202), you should listen and handle the payment instructions webhook/callback. This will be sent to the collection callback URL that's configured on your merchant account. The callback is sent as a JSON POST request and the payload will help you determine the next course of action. Sample payloads below.

Instructions Payload

{
  "event": "transaction.processing",
  "payload": {
    "id": 14848,
    "merchant_reference": "MCTREFQSSBHMHU3RCTLA",
    "internal_reference": "DUSUPAYZAERK2SBE6WJAG",
    "transaction_type": "COLLECTION",
    "request_currency": "NGN",
    "request_amount": 4000,
    "transaction_currency": "NGN",
    "transaction_amount": 4000,
    "transaction_charge": 80,
    "charge_customer": false,
    "total_credit": 3920,
    "transaction_account": "1771825717058",
    "customer_name": "JOHN DOE",
    "provider_code": "bank_ng",
    "transaction_status": "PROCESSING",
    "status_message": "Transaction Initiated successfully. Deposit funds to the account",
    "payment_instructions": "<p>Please make a payment of <b> NGN 4,000 </b> to the following account.</p><p><table><tr><td>Account number:</td><td></td><td></td><td><b>2121562123</b></td></tr><tr></tr><tr></tr><tr></tr><tr><td>Bank Name:</td><td></td><td></td><td> DUSUPAY</td</tr><tr></tr><tr></tr><tr></tr><tr></tr><tr><td>Beneficiary:</td><td></td><td></td><td> <b> Dusupay Account</b></td></tr><tr></tr></table></p><p><b>Reminder: Use this account only for this transaction, and make sure to complete the payment before the time specified above expires. </b></p>",
    "sub_account_details": {
      "account_name": "DUSUPAY",
      "account_no": "2121562123",
      "bank_name": "WEMA",
      "amount": 4000
    },
    "authorization": {}
  }
}

Request Failed

Transaction Failed

Details from the payload need to be displayed for the customer so they can execute the fund to the transfer. A few things to note;

1. You could directly display the content of the payment_instructions parameter OR implement a custom display using content in the sub_account_details object.

2. If the customer is bearing the transaction charge (charge_customer=true), we recommend that you display the value in the transaction_charge so that the customer is aware of surcharge.

Step 3: Handle the final status webhook

Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Bank Transfer

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFQSSBHMHU3RCTLA",
        "internal_reference": "DUSUPAYZAERK2SBE6WJAG",
        "transaction_type": "COLLECTION",
        "request_currency": "NGN",
        "transaction_amount": 4000,
        "transaction_currency": "NGN",
        "transaction_charge": 80,
        "transaction_account": "2121562123",
        "charge_customer": false,
        "total_credit": 3920,
        "provider_code": "bank_ng",
        "request_amount": 4000,
        "customer_name": "JOHN DOE",
        "institution_name": "GUARANTY TRUST BANK",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Failed Request

We recommend that the webhook/callback requests are verified for authenticity using any of the described signature verification methods.