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 AlternativePayment class provides support for various alternative payment methods across Africa, including Nigerian USSD, Ghana Mobile Money, and Kenya M-Pesa.

​
Supported Payment Methods

Nigerian USSD

GTBank and Zenith Bank USSD payments

Ghana Mobile Money

MTN, Vodafone, AirtelTigo, and Tigo mobile money

Kenya M-Pesa

Safaricom M-Pesa payments

​
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

​
Nigerian USSD

USSD payments allow customers to complete transactions by dialing a code on their mobile phone. This method works with GTBank and Zenith Bank.

​
Parameters

​
accountnumber
string
required
Customer’s account number
​
accountbank
string
required
Bank short code (“058” for GTBank, “057” for Zenith)
​
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
​
pin
string
required
Customer’s account PIN
​
IP
string
required
Customer’s IP address
​
currency
string
default:"NGN"
Currency code (must be “NGN”)
​
country
string
default:"NG"
Country code (must be “NG”)

​
Example

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

public class UssdPaymentExample {
    public static void main(String[] args) {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        AlternativePayment ch = new AlternativePayment();
        ch.setAccountnumber("0690000004")
            .setAccountbank("044")
            .setCurrency("NGN")
            .setCountry("NG")
            .setAmount("6000")
            .setFirstname("John")
            .setLastname("Doe")
            .setPin("3310")
            .setEmail("customer@example.com")
            .setIP("103.238.105.185")
            .setTxRef("MXX-ASC-4578");
        
        JSONObject chargeUssd = ch.chargeNigerianUssd();
        System.out.println(chargeUssd);
    }
}
The customer will receive a USSD code to dial on their phone to complete the payment. The payment type is automatically set to "ussd".

​
Ghana Mobile Money

Accept payments from major Ghanaian mobile money networks including MTN, Vodafone, AirtelTigo, and Tigo.

​
Parameters

​
orderRef
string
required
Unique reference for the mobile money transaction (merchant-provided)
​
network
string
required
Mobile money network provider (e.g., “MTN”, “VODAFONE”, “TIGO”)
​
phonenumber
string
required
Customer’s mobile money phone number
​
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
​
pin
string
required
Customer’s mobile money PIN
​
IP
string
required
Customer’s IP address
​
currency
string
default:"GHS"
Currency code (must be “GHS”)
​
country
string
default:"GH"
Country code (must be “GH”)

​
Example

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

public class MobileMoneyExample {
    public static void main(String[] args) {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        AlternativePayment ch = new AlternativePayment();
        ch.setOrderRef("0690000")
            .setNetwork("MTN")
            .setCurrency("GHS")
            .setCountry("GH")
            .setAmount("4000")
            .setFirstname("John")
            .setLastname("Doe")
            .setPin("3310")
            .setEmail("customer@example.com")
            .setIP("103.238.105.185")
            .setTxRef("MXX-90-49578")
            .setPhonenumber("08020000000");
        
        JSONObject chargeGh = ch.chargeGhanaMobileMoney();
        System.out.println(chargeGh);
    }
}
Ensure the phone number format matches the network provider’s requirements and that the customer has sufficient balance in their mobile money account.

​
Supported Networks

  • MTN: "MTN"
  • Vodafone: "VODAFONE"
  • AirtelTigo: "AIRTELTIGO"
  • Tigo: "TIGO"

​
Kenya M-Pesa

Accept payments via Safaricom M-Pesa, Kenya’s leading mobile money platform.

​
Parameters

​
orderRef
string
required
Unique reference for the M-Pesa transaction (merchant-provided)
​
phonenumber
string
required
Customer’s M-Pesa phone number (format: 0XXXXXXXXX)
​
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
​
pin
string
required
Customer’s M-Pesa PIN
​
IP
string
required
Customer’s IP address
​
currency
string
default:"KES"
Currency code (must be “KES”)
​
country
string
default:"KE"
Country code (must be “KE”)

​
Example

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

public class MpesaPaymentExample {
    public static void main(String[] args) {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        AlternativePayment ch = new AlternativePayment();
        ch.setCurrency("KES")
            .setCountry("KE")
            .setAmount("6000")
            .setFirstname("John")
            .setLastname("Doe")
            .setPin("3310")
            .setEmail("customer@example.com")
            .setIP("103.238.105.185")
            .setTxRef("MXX-ASC-4578")
            .setOrderRef("y77yy")
            .setPhonenumber("0903672978");
        
        JSONObject chargeMpesa = ch.chargeKenyaMpesa();
        System.out.println(chargeMpesa);
    }
}
The customer will receive an M-Pesa prompt on their phone to authorize the payment. They must enter their M-Pesa PIN on their phone to complete the transaction.

​
Verifying Transactions

For all alternative payment methods, you should verify the transaction status after charging: 
import com.github.theresasogunle.Transaction;

// After charging
Transaction t = new Transaction();
t.setFlwref("FLW-MOCK-d310263f5f73e51d01e6dab32c893679")
    .setTxRef("MXX-ASC-4578");

// Use xrequery for alternative payment methods
JSONObject response = t.verifyTransactionXrequery();
System.out.println("Transaction Status: " + response);
1

Initiate Payment

Call the appropriate charge method (chargeNigerianUssd(), chargeGhanaMobileMoney(), or chargeKenyaMpesa())
2

Get Reference

Extract the flwRef from the charge response
3

Customer Completes Payment

Customer dials USSD code or authorizes payment on their mobile device
4

Verify Transaction

Use the Transaction class to verify the payment status with verifyTransactionXrequery()

​
Method Reference

MethodPayment TypeReturnsDescription
chargeNigerianUssd()Nigerian USSDJSONObjectCharges via GTB/Zenith USSD
chargeGhanaMobileMoney()Ghana Mobile MoneyJSONObjectCharges via Ghanaian mobile networks
chargeKenyaMpesa()Kenya M-PesaJSONObjectCharges via Safaricom M-Pesa

​
Payment Type Indicators

Each method automatically sets the appropriate payment type:
  • Nigerian USSD: payment_type: "ussd"
  • Ghana Mobile Money: payment_type: "mobilemoneygh", is_mobile_money_gh: "1"
  • Kenya M-Pesa: payment_type: "mpesa", is_mpesa: "1"

​
Best Practices

  • Clearly display the USSD code to the customer
  • Provide instructions on how to dial the code
  • Set appropriate timeout periods (USSD sessions can expire)
  • Implement webhook handlers for async updates

​
Troubleshooting

​
Common Issues

Transaction Pending
  • Customer hasn’t completed the payment on their device
  • Use verifyTransactionXrequery() to check current status
  • Wait for webhook notification if configured
Invalid Network/Provider
  • Verify the network name is correct and supported
  • Ensure currency and country match the payment method
Phone Number Format
  • Ghana Mobile Money: Include country code if required
  • Kenya M-Pesa: Use format 0XXXXXXXXX (not +254XXXXXXXXX)

​
Next Steps

Card Payments

Accept credit and debit card payments

Account Payments

Charge customer bank accounts directly

Build docs developers (and LLMs) love

Get started for freeTalk to us