DocumentationAPI ReferencesSupportBlogAsk AI
Documentation

Nigeria Account Charge

Learn how to collect payment directly from your Nigerian customer’s bank accounts.

Suggest Edits

📘

Getting Started

We recommend checking out the introductory section to understand the basics of direct charge first. This guide assumes you’ve read that.

The Nigeria Account Charge method allows you to collect payments directly from a customer’s Nigerian bank account through a direct debit authorization. With this payment flow, the customer grants permission for funds to be automatically debited from their account once they approve the transaction.

This method provides a secure and reliable way to accept payments from Nigerian customers without requiring card details. It is commonly used for one-time payments, subscriptions, and other recurring billing scenarios.

Bank Account Debit Process

Charging a Nigerian bank account involves three main steps:

  1. Initiate the Payment: You send the payment details to the bank account charge endpoint.
  2. Authorize the Charge: The customer authorizes the payment with their bank. The means of authorization will depend on the bank.
  3. Verify the Payment: As a failsafe, you'll call our API to verify that the payment was successful before giving value (via the verify transaction endpoint).

Step 1: Initiating the Payment

To initiate a Nigerian Account Charge, you need to collect the customer’s bank details and basic transaction information.

Required parameters:

  • account_number : The customer’s bank account number.
  • bank_code : The code of the customer’s bank. You can retrieve this using the get bank branches API.
  • email : The customer’s email address.
  • fullname: The customer’s full name.
  • currency: The transaction currency (e.g., NGN).
  • tx_ref: A unique transaction reference for this payment.

You can also specify more details, such as the customer's phone_number and custom meta information. Refer to the reference documentation for details.

📘

Supported Currency

The currency you specify must match the account's currency. This is currently restricted to NGN accounts.

Send these payment details to the charge NG bank accounts endpoint. Here are some examples of using our SDKs:


// Install with: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);

const payload = {
amount: 7500,
currency: 'NGN',
email: '[email protected]',
fullname: 'Flutterwave Developers',
phone_number: '+2349012345678',
tx_ref: 'UNIQUE_TRANSACTION_REFERENCE'
}
await flw.Charge.ng(payload);


// Installation: composer require flutterwavedev/flutterwave-v3

use Flutterwave\Util\Currency;

$data = [
    "amount" => 7500,
    "currency" => Currency::NGN,
    "tx_ref" => "UNIQUE_TRANSACTION_REFERENCE",
    "redirectUrl" => "https://example_company.com/success",
    "additionalData" => [
        "account_details" => [
            "account_bank" => "044",
            "account_number" => "0690000034",
            "country" => "NG"
        ]
    ],
];

$accountpayment = \Flutterwave\Flutterwave::create("account");
$customerObj = $accountpayment->customer->create([
    "email" => "[email protected]",
    "full_name" => "Flutterwave Developers",
    "phone" => "+2349012345678"
]);

$data['customer'] = $customerObj;
$payload  = $accountpayment->payload->create($data);
$result = $accountpayment->initiate($payload);

# Install with: gem install flutterwave_sdk

require './flutterwave_sdk'

flw = Flutterwave.new(ENV["FLW_PUBLIC_KEY"], ENV["FLW_SECRET_KEY"], ENV["FLW_ENCRYPTION_KEY"])
account_payment = AccountPayment.new(flw)
payload = {
    "account_bank": "044",
    "account_number": "0690000037",
    "amount": "7500",
    "currency": "NGN",
    "email": "[email protected]",
    "fullname": "Flutterwave Developers",
    "phone_number": "+2349012345678",
    "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
    "redirect_url": "https://example_company.com/success"
}
# Automatically uses the right endpoint based on the currency
response = account_payment.initiate_charge(payload)

curl --request POST \
   --url https://api.flutterwave.com/v3/charges?type=debit_ng_account \
   --header 'Authorization: Bearer FLW_SECRET_KEY' \
   --header 'content-type: application/json' \
   --data '{
     "amount": 7500,
     "currency": "NGN",
     "account_bank": "044",
     "account_number": "0690000037",
     "email": "[email protected]",
     "fullname": "Flutterwave Developers",
     "phone_number": "+2349012345678",
     "tx_ref": "UNIQUE_TRANSACTION_REFERENCE"
}'

Step 2: Handling the Response

If the request goes well, you'll get a successful response that gives you the details of the created transaction and information on how to authorize it.

// Typically used by FirstBank and GTB
{
	"status": "success",
	"message": "Charge initiated",
	"data": {
		"id": 862960580,
		"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
		"flw_ref": "MPOG80201678720780553218",
		"device_fingerprint": "N/A",
		"amount": 7500,
		"charged_amount": 7500,
		"app_fee": 105,
		"merchant_fee": 0,
		"processor_response": "Pending validation",
		"auth_model": "INTERNET_BANKING",
		"currency": "NGN",
		"ip": "N/A",
		"narration": "Flutterwave Developers",
		"status": "pending",
		"auth_url": "https://api.ravepay.co/flwv3-pug/getpaid/api/short-url/SCN0eHPMN-",
		"payment_type": "account",
		"fraud_status": "ok",
		"created_at": "2023-03-13T15:19:40.000Z",
		"account_id": 35308,
		"customer": {
			"id": 407680026,
			"phone_number": "2349012345678",
			"name": "Flutterwave Developers",
			"email": "[email protected]",
			"created_at": "2022-08-11T15:32:30.000Z"
		},
		"meta": {
			"authorization": {
				"mode": "redirect",
				"redirect": "https://api.ravepay.co/flwv3-pug/getpaid/api/short-url/SCN0eHPMN-",
				"validate_instructions": ""
			}
		}
	}
}

Below are some key details to note in the response:

  • status is "success", meaning that the charge was initiated successfully.

  • data.status is "pending", meaning that the customer needs to authorize the transaction with their bank.

  • meta.authorization contains the important details to authorize the payment:

  • The mode is "redirect", which means the customer should be redirected to their bank for authorization.

  • You'll have a redirect field, which is where you should redirect your customer to.

Step 3: Authorizing the Transaction

To authorize the payment, you need to redirect the customer to the URL in the redirect field:

if (transaction.meta.authorization.mode == 'redirect') {
	return res.redirect(transaction.meta.authorization.redirect);
}

if ($transaction["meta"]["authorization"]["mode"] == "redirect") {
  return redirect($transaction["meta"]["authorization"]["redirect"]);
}

if transaction["meta"]["authorization"]["mode"] == "redirect"
  return redirect to: transaction["meta"]["authorization"]["redirect"]
end

Wehooks

When the customer makes the payment, we'll send you a webhook notification. Here's what the payload looks like:

{
	"event": "charge.completed",
	"data": {
		"id": 862960580,
		"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
		"flw_ref": "MPOG80201678720780553218",
		"device_fingerprint": "N/A",
		"amount": 7500,
		"currency": "NGN",
		"charged_amount": 7500,
		"app_fee": 105,
		"merchant_fee": 0,
		"processor_response": "Approved by Financial Institution",
		"auth_model": "INTERNET_BANKING",
		"ip": "N/A",
		"narration": "Flutterwave Developers",
		"status": "successful",
		"payment_type": "account",
		"created_at": "2023-03-13T15:19:40.000Z",
		"account_id": 35308,
		"customer": {
			"id": 407680026,
			"name": "Flutterwave Developers",
			"phone_number": "2349012345678",
			"email": "[email protected]",
			"created_at": "2022-08-11T15:32:30.000Z"
		},
		"account": {
			"account_name": "undefined undefined"
		}
	}
}

Now, your webhook endpoint can handle the event and complete the customer's order. For help setting up webhooks, see our guide on webhooks.

In your webhook handler, you can then verify the payment and credit your customers with whatever they paid for. See our guide to transaction verification for details.

Updated 17 days ago