Skip to main content

​
Process your first payment

This guide will walk you through creating your first card charge using the Rave Java Library. You’ll learn how to configure the library, create a card charge, and execute the payment.
This quickstart uses test credentials in the staging environment. No real money will be charged.

​
Before you begin

Make sure you have:

​
Step-by-step guide

1

Configure RaveConstant

First, set up your API credentials and environment. Add this configuration at the beginning of your application:
import com.github.theresasogunle.*;
import org.json.JSONObject;

public class Main {
    public static void main(String[] args) throws Exception {
        // Configure Rave with your API keys
        RaveConstant.PUBLIC_KEY = "FLWPUBK-8ba286388b24dbd6c20706def0b4ea23-X";
        RaveConstant.SECRET_KEY = "FLWSECK-c45e0f704619e673263844e584bba013-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        // Your payment code will go here
    }
}
Replace the test keys with your actual Flutterwave API keys. Never commit your secret key to version control.
2

Create a CardCharge object

Create a new CardCharge instance and set the card details using method chaining:
CardCharge ch = new CardCharge();

ch.setCardno("4187427415564246")
    .setCvv("828")
    .setAmount("3000")
    .setExpiryyear("19")
    .setExpirymonth("09")
    .setEmail("flamekeed@gmail.com")
    .setTxRef("MXX-ASC-4578")
    .setSuggested_auth("PIN")
    .setPin("3310");
The setTxRef() should be a unique transaction reference for each payment. Use a UUID or timestamp-based reference in production.
3

Execute the charge

Call the appropriate charge method based on the card type. For Mastercard and Verve cards:
JSONObject charge = ch.chargeMasterAndVerveCard();
System.out.println(charge);
The response will contain the charge status and any required next steps (like OTP validation).
4

Handle the response

The charge method returns a JSON object with the transaction details. Check the response:
JSONObject charge = ch.chargeMasterAndVerveCard();

System.out.println("Status: " + charge.getString("status"));
System.out.println("Message: " + charge.getString("message"));
System.out.println("Transaction Reference: " + charge.getJSONObject("data").getString("flwRef"));

​
Complete example

Here’s the complete code for a simple card charge:
Main.java
import com.github.theresasogunle.*;
import org.json.JSONObject;

public class Main {
    public static void main(String[] args) throws Exception {
        // Step 1: Configure RaveConstant
        RaveConstant.PUBLIC_KEY = "FLWPUBK-8ba286388b24dbd6c20706def0b4ea23-X";
        RaveConstant.SECRET_KEY = "FLWSECK-c45e0f704619e673263844e584bba013-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        // Step 2: Create CardCharge object
        CardCharge ch = new CardCharge();
        
        // Step 3: Set card details
        ch.setCardno("4187427415564246")
            .setCvv("828")
            .setAmount("3000")
            .setExpiryyear("19")
            .setExpirymonth("09")
            .setEmail("flamekeed@gmail.com")
            .setTxRef("MXX-ASC-4578")
            .setSuggested_auth("PIN")
            .setPin("3310");
        
        // Step 4: Execute charge
        JSONObject charge = ch.chargeMasterAndVerveCard();
        
        // Step 5: Handle response
        System.out.println(charge);
    }
}

​
Advanced card charge example

For a more complete implementation with additional fields:
AdvancedCardCharge.java
import com.github.theresasogunle.*;
import org.json.JSONObject;

public class AdvancedCardCharge {
    public static void main(String[] args) throws Exception {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        CardCharge ch = new CardCharge();
        
        // Set comprehensive card details
        ch.setCardno("4187427415564246")
            .setCvv("828")
            .setCurrency("NGN")
            .setCountry("NG")
            .setAmount("9000")
            .setExpiryyear("19")
            .setExpirymonth("09")
            .setEmail("sogunledolapo@gmail.com")
            .setIP("103.238.105.185")
            .setTxRef("MXX-ASC-4578")
            .setDevice_fingerprint("69e6b7f0sb72037aa8428b70fbe03986c");
        
        // For Mastercard and Verve cards
        ch.setPin("3310")
            .setSuggested_auth("PIN");
        
        JSONObject charge = ch.chargeMasterAndVerveCard();
        System.out.println(charge);
        
        // If timeout occurs, use polling
        JSONObject poll = ch.chargeMasterAndVerveCard(true);
        System.out.println(poll);
    }
}

​
Charging Visa and international cards

Visa and international cards require a redirect URL instead of a PIN:
VisaCardCharge.java
import com.github.theresasogunle.*;
import org.json.JSONObject;

public class VisaCardCharge {
    public static void main(String[] args) throws Exception {
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        CardCharge ch = new CardCharge();
        
        ch.setCardno("4187427415564246")
            .setCvv("828")
            .setCurrency("NGN")
            .setCountry("NG")
            .setAmount("9000")
            .setExpiryyear("19")
            .setExpirymonth("09")
            .setEmail("sogunledolapo@gmail.com")
            .setIP("103.238.105.185")
            .setTxRef("MXX-ASC-4578")
            .setDevice_fingerprint("69e6b7f0sb72037aa8428b70fbe03986c")
            .setRedirect_url("http://www.google.com");
        
        // Charge Visa and international cards
        JSONObject chargeVisa = ch.chargeVisaAndIntl();
        System.out.println(chargeVisa);
        
        // If timeout, poll
        JSONObject pollVisa = ch.chargeVisaAndIntl(true);
        System.out.println(pollVisa);
    }
}
The setRedirect_url() should point to a page on your website where the user will be redirected after completing 3D Secure authentication.

​
Understanding the response

A successful charge response looks like this: 
{
  "status": "success",
  "message": "Charge successful",
  "data": {
    "id": 1234567,
    "txRef": "MXX-ASC-4578",
    "flwRef": "FLW-MOCK-REFERENCE",
    "orderRef": "URF_1234567_8901234",
    "amount": 3000,
    "charged_amount": 3000,
    "currency": "NGN",
    "chargeMessage": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
    "authModelUsed": "PIN",
    "status": "success-pending-validation"
  }
}

​
Next steps

Validate charges

Learn how to validate OTP and complete the payment flow

Account payments

Accept payments directly from bank accounts

Configuration

Learn more about API keys and environment settings

Error handling

Handle common errors and edge cases

​
Test cards

Use these test cards in the staging environment:
Card NumberCVVExpiryPINType
418742741556424682809/193310Mastercard
543889801456022978909/193310Mastercard
553188665214295056409/193310Verve
Never use real card details in the staging environment. Always use the test cards provided by Flutterwave.