Card Payments

Accept card payments with Mastercard, Verve, Visa, and international cards

The CardCharge class enables you to process payments from various card types including Mastercard, Verve, Visa, and international cards. The library supports both PIN-based and redirect-based authentication flows.

Supported Card Types

• Mastercard & Verve: PIN-based authentication
• Visa (Local): Redirect-based authentication
• International Cards: Redirect-based authentication

Setting Up a Card Charge

Use the fluent API to configure your card charge:

cardno · string · required

The card number

cvv · string · required

The card CVV/CVC code

expirymonth · string · required

Card expiry month (e.g., “09”)

expiryyear · string · required

Card expiry year (e.g., “19”)

amount · string · required

Transaction amount

email · string · required

Customer’s email address

txRef · string · required

Your unique transaction reference

currency · string · default: "NGN"

Currency code (defaults to NGN)

country · string · default: "NG"

Country code (defaults to NG)

pin · string

Customer’s card PIN (required for Mastercard/Verve)

suggested_auth · string

Suggested authentication method (e.g., “PIN”)

redirect_url · string

Redirect URL for Visa/International cards

device_fingerprint · string

Device fingerprint for fraud detection (optional)

Charging Methods

Mastercard & Verve Cards

Use the chargeMasterAndVerveCard() method for Mastercard and Verve cards with PIN authentication:

RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
RaveConstant.ENVIRONMENT = Environment.STAGING; // or Environment.LIVE

CardCharge payload = new CardCharge();
payload.setCardno("4187427415564246")
    .setCvv("828")
    .setCurrency("NGN")
    .setCountry("NG")
    .setAmount("9000")
    .setExpiryyear("19")
    .setExpirymonth("09")
    .setEmail("[e-mail]")
    .setIP("103.238.105.185")
    .setTxRef("MXX-ASC-4578")
    .setDevice_fingerprint("69e6b7f0sb72037aa8428b70fbe03986c")
    .setPin("3310")
    .setSuggested_auth("PIN");

JSONObject charge = payload.chargeMasterAndVerveCard();
System.out.println(charge);

For Mastercard and Verve cards, you must provide the customer’s PIN and set suggested_auth to “PIN”.

Polling for Timeout

If the charge request times out, use the polling variant:

JSONObject poll = payload.chargeMasterAndVerveCard(true);

Visa & International Cards

Use the chargeVisaAndIntl() method for Visa and international cards with redirect authentication:

CardCharge payload = new CardCharge();
payload.setCardno("4187427415564246")
    .setCvv("828")
    .setCurrency("NGN")
    .setCountry("NG")
    .setAmount("9000")
    .setExpiryyear("19")
    .setExpirymonth("09")
    .setEmail("[e-mail]")
    .setIP("103.238.105.185")
    .setTxRef("MXX-ASC-4578")
    .setDevice_fingerprint("69e6b7f0sb72037aa8428b70fbe03986c")
    .setRedirect_url("http://www.yourdomain.com/callback");

JSONObject chargeVisa = payload.chargeVisaAndIntl();
System.out.println(chargeVisa);

For Visa and international cards, you must provide a redirect_url where users will complete their authentication.

Polling for Timeout

JSONObject pollVisa = payload.chargeVisaAndIntl(true);

Validation Methods

PIN Validation (Mastercard & Verve)

After initiating a charge, validate it using the OTP sent to the customer:

payload.setOtp("12345")
    .setTransaction_reference("FLW-MOCK-75dd012dc6c6b58807d69d0e89432e9f");

JSONObject validateCharge = payload.validateCardCharge();
System.out.println(validateCharge);

1. Initiate Charge

   Call chargeMasterAndVerveCard() with customer’s card details and PIN

2. Retrieve Transaction Reference

   Extract the flwRef from the charge response

3. Get OTP

   Customer receives OTP via SMS or email

4. Validate

   Call validateCardCharge() with the OTP and transaction reference

Polling for Timeout

JSONObject validatePoll = payload.validateCardCharge(true);

Redirect Validation (Visa & International)

For redirect-based authentication, open the auth URL returned in the charge response:

payload.setAuthUrl("https://api.ravepay.co/flwv3-pug/getpaid/api/validate");
payload.validateCardChargeVB();

The validateCardChargeVB() method opens a browser window for card validation. This is suitable for desktop applications but not for server-side implementations.

Authentication Flows

PIN Authentication

Used for Mastercard and Verve cards:

1. Customer provides card details and PIN
2. System sends charge request with PIN and suggested_auth: "PIN"
3. Customer receives OTP
4. Validate with OTP to complete transaction

Response AuthMode: "PIN"

Redirect Authentication

Used for Visa and International cards:

1. Customer provides card details
2. System sends charge request with redirect_url
3. Customer is redirected to issuer’s authentication page
4. Customer completes 3D Secure or VBV authentication
5. Customer is redirected back to your redirect_url

Response AuthMode: "VBVSECURE" or "AVS_VBVSECURECODE"

Complete Example

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

public class CardPaymentExample {
    public static void main(String[] args) {
        // Configure Rave
        RaveConstant.PUBLIC_KEY = "FLWPUBK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.SECRET_KEY = "FLWSECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-X";
        RaveConstant.ENVIRONMENT = Environment.STAGING;
        
        CardCharge payload = new CardCharge();
        
        // For Mastercard/Verve
        payload.setCardno("4187427415564246")
            .setCvv("828")
            .setCurrency("NGN")
            .setCountry("NG")
            .setAmount("9000")
            .setExpiryyear("19")
            .setExpirymonth("09")
            .setEmail("[e-mail]")
            .setIP("103.238.105.185")
            .setTxRef("MXX-ASC-4578")
            .setPin("3310")
            .setSuggested_auth("PIN");
            
        JSONObject charge = payload.chargeMasterAndVerveCard();
        
        // Validate with OTP
        payload.setOtp("12345")
            .setTransaction_reference(charge.getJSONObject("data").getString("flwRef"));
            
        JSONObject validateCharge = payload.validateCardCharge();
        System.out.println("Payment Status: " + validateCharge.getString("status"));
    }
}

Method Reference

Method	Parameters	Returns	Description
chargeMasterAndVerveCard()	-	JSONObject	Charges Mastercard and Verve cards with PIN
chargeMasterAndVerveCard(boolean polling)	polling	JSONObject	Charges with polling for timeout
chargeVisaAndIntl()	-	JSONObject	Charges Visa and international cards
chargeVisaAndIntl(boolean polling)	polling	JSONObject	Charges with polling for timeout
validateCardCharge()	-	JSONObject	Validates Mastercard/Verve charge with OTP
validateCardCharge(boolean polling)	polling	JSONObject	Validates with polling for timeout
validateCardChargeVB()	-	void	Opens browser for redirect validation

Next Steps

Account Payments

Learn how to charge customer bank accounts

Preauthorization

Hold funds with pre-authorization