Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theresasogunle/Fintech-flutterwave-Java-Library/llms.txt

Use this file to discover all available pages before exploring further.

The AccountCharge class enables direct bank account payments in Nigeria. This payment method requires customers to provide their account details and validate the transaction with an OTP.

​
Overview

Account payments follow a two-step flow:
  1. Charge: Initiate the payment with account details
  2. Validate: Complete the payment with OTP verification

​
Configuration

First, configure your Rave credentials: 
RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
RaveConstant.ENVIRONMENT = Environment.STAGING; // or Environment.LIVE

​
Account Charge Parameters

​
accountnumber
string
required
Customer’s bank account number
​
accountbank
string
required
Bank short code (e.g., “044” for Access Bank)
​
amount
string
required
Transaction amount
​
email
string
required
Customer’s email address
​
txRef
string
required
Your unique transaction reference
​
firstname
string
required
Customer’s first name
​
lastname
string
required
Customer’s last name
​
IP
string
required
Customer’s IP address
​
currency
string
default:"NGN"
Currency code (defaults to NGN)
​
country
string
default:"NG"
Country code (defaults to NG)
​
phonenumber
string
Customer’s phone number (optional)
​
passcode
string
Account passcode (optional)
​
device_fingerprint
string
Device fingerprint for fraud detection (optional)

​
Charging a Bank Account

1

Create Account Charge

Initialize an AccountCharge object and set the required parameters:
AccountCharge ch = new AccountCharge();
ch.setAccountnumber("0690000031")
    .setAccountbank("044")
    .setAmount("1000")
    .setCountry("NG")
    .setCurrency("NGN")
    .setLastname("Theresa")
    .setFirstname("Sogunle")
    .setIP("1.3.4.4")
    .setPayment_type("account")
    .setTxRef("MX-678DH")
    .setEmail("customer@example.com");
2

Initiate Charge

Call the chargeAccount() method to initiate the payment:
JSONObject result = ch.chargeAccount();
System.out.println(result);
The response will contain a flwRef (transaction reference) that you’ll need for validation.
3

Receive OTP

The customer will receive an OTP via SMS or email to authorize the transaction.
4

Validate with OTP

Complete the payment by validating with the OTP:
ch.setTransaction_reference("ACHG-1520028650995")
    .setOtp("12345");

JSONObject val = ch.validateAccountCharge();
System.out.println(val);

​
Complete Example

import com.github.theresasogunle.*;
import org.json.JSONObject;

public class AccountPaymentExample {
    public static void main(String[] args) {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        // Create account charge
        AccountCharge ch = new AccountCharge();
        ch.setAccountnumber("0690000031")
            .setAccountbank("044")
            .setAmount("1000")
            .setCountry("NG")
            .setCurrency("NGN")
            .setLastname("Theresa")
            .setFirstname("Sogunle")
            .setIP("1.3.4.4")
            .setTxRef("MX-678DH")
            .setEmail("customer@example.com");
        
        // Charge account
        JSONObject result = ch.chargeAccount();
        System.out.println("Charge Response: " + result);
        
        // Extract transaction reference from response
        String flwRef = result.getJSONObject("data").getString("flwRef");
        
        // Validate with OTP (after customer receives it)
        ch.setTransaction_reference(flwRef)
            .setOtp("12345");
        
        JSONObject validation = ch.validateAccountCharge();
        System.out.println("Validation Response: " + validation);
        
        // Check payment status
        if (validation.getString("status").equals("success")) {
            System.out.println("Payment completed successfully!");
        }
    }
}

​
Polling Support

Both the charge and validation methods support polling for handling timeout scenarios.

​
Charge with Polling

If the initial charge request times out, use polling: 
JSONObject poll = ch.chargeAccount(true);
Setting the polling parameter to true enables automatic retry logic for timeout scenarios.

​
Validation with Polling

Similarly, you can poll during validation: 
JSONObject val = ch.validateAccountCharge(true);

​
Bank Codes

Common Nigerian bank codes:
Bank NameBank Code
Access Bank044
GTBank058
Zenith Bank057
First Bank011
UBA033
Fidelity Bank070
FCMB214
Stanbic IBTC221
Sterling Bank232
Union Bank032
Always ensure you’re using the correct bank code for the customer’s bank. Incorrect codes will cause the transaction to fail.

​
Payment Type

The payment type is automatically set to "account" by the setJSON() method in the AccountCharge class. You don’t need to set this manually.

​
Response Handling

​
Charge Response

The chargeAccount() method returns a JSON object with the following structure: 
{
  "status": "success",
  "message": "AUTH_SUGGESTION",
  "data": {
    "flwRef": "ACHG-1520028650995",
    "authModelUsed": "AUTH",
    "authurl": "",
    ...
  }
}

​
Validation Response

The validateAccountCharge() method returns: 
{
  "status": "success",
  "message": "Charge Complete",
  "data": {
    "txRef": "MX-678DH",
    "flwRef": "ACHG-1520028650995",
    "amount": 1000,
    "currency": "NGN",
    "chargedAmount": 1000,
    ...
  }
}

​
Method Reference

MethodParametersReturnsDescription
chargeAccount()-JSONObjectInitiates account charge
chargeAccount(boolean polling)pollingJSONObjectInitiates charge with polling support
validateAccountCharge()-JSONObjectValidates charge with OTP
validateAccountCharge(boolean polling)pollingJSONObjectValidates with polling support

​
Best Practices

  • Never store sensitive account details
  • Always use HTTPS for API calls
  • Validate transaction amounts before processing
  • Implement proper error handling

​
Troubleshooting

​
Common Issues

Invalid Bank Code
  • Ensure you’re using the correct 3-digit bank code
  • Verify the bank code matches the account number
OTP Not Received
  • Verify the customer’s email and phone number are correct
  • Check if the bank account is active and valid
  • Wait a few minutes and retry
Validation Failed
  • Ensure the OTP is entered correctly
  • Check that the transaction reference matches
  • Verify the OTP hasn’t expired

​
Next Steps

Card Payments

Accept credit and debit card payments

Alternative Payments

Support USSD, mobile money, and M-Pesa

Build docs developers (and LLMs) love

Get started for freeTalk to us