Android Integration

Cashfree’s Integrity Standards

Before proceeding with the SDK integration, please ensure that your application complies with Cashfree’s Integrity. Applications that don’t meet the required integrity standards may be restricted from using production services.For further guidance, refer to the Cashfree Integrity.

Setting Up SDK

implementation 'com.cashfree.pg:api:2.2.8'

Step 1: Creating an Order

The first step in the Cashfree Payment Gateway integration is to create an Order. You need to do this before any payment can be processed. You can add an endpoint to your server which creates this order and is used for communication with your frontend.

Order creation must happen from your backend (as this API uses your secret key). Please do not call this directly from your mobile application.

API Request for Creating an Order

Here’s a sample request for creating an order using your desired backend language. Cashfree offers backend SDKs to simplify the integration process. You can find the SDKs here.

import { Cashfree, CFEnvironment } from "cashfree-pg";

const cashfree = new Cashfree(
	CFEnvironment.PRODUCTION,
	"{Client ID}",
	"{Client Secret Key}"
);

function createOrder() {
	var request = {
		order_amount: "1",
		order_currency: "INR",
		customer_details: {
			customer_id: "node_sdk_test",
			customer_name: "",
			customer_email: "example@gmail.com",
			customer_phone: "9999999999",
		},
		order_meta: {
			return_url:
				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
		},
		order_note: "",
	};

	cashfree
		.PGCreateOrder(request)
		.then((response) => {
			var a = response.data;
			console.log(a);
		})
		.catch((error) => {
			console.error("Error setting up order request:", error.response.data);
		});
}

After successfully creating an order, you will receive a unique order_id and payment_session_id that you need for subsequent steps. You can view all the complete api request and response for /orders here.

Step 2: Opening the Payment Page

Once the order is created, the next step is to open the payment page so the customer can make the payment. Cashfree Android SDK offer below payment flow.

Web Checkout

In this flow, SDK provides a webview based checkout implementation to facilitate a quick integration with our payment gateway. Your customers can fill in the necessary details in the web page and complete the payment. This mode also handles all the business logic and UI Components to make the payment smooth and easy to use.

UPI Intent Checkout

This flow is for merchants who wants to quickly provide UPI Intent functionality using cashfree’s mobile SDK. In this flow, SDK provides a pre-built native Android screen to facilitate a quick integration with our payment gateway. Your customers will see a list of UPI apps installed in their phone which they can select to initiate payment. This mode handles all the business logic and UI Components to make the payment smooth and easy to use. The SDK allows the merchant to customize the UI in terms of color coding, fonts.

To complete the payment, we can follow the following steps:

Create a CFSession object.
Create a CFTheme object.
Create a CFWebCheckoutPayment/CFUPIIntentCheckoutPayment object.
Set payment callback.
Initiate the payment using the payment object created from [step 3]

We go through these step by step below.

Create a Session

This object contains essential information about the order, including the payment session ID (payment_session_id) and order ID (order_id) obtained from Step 1. It also specifies the environment (sandbox or production).

CFSession cfSession = new CFSession.CFSessionBuilder()
        .setEnvironment(CFSession.Environment.SANDBOX)
        .setPaymentSessionID("paymentSessionID")
        .setOrderId("orderID")
        .build();

Customize Theme (Optional)

You can customize the appearance of the checkout screen using CFTheme. This step is optional but can help maintain consistency with your app’s design.

Web Checkout

CFWebCheckoutTheme cfTheme = new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
    .setNavigationBarBackgroundColor("#6A3FD3")
    .setNavigationBarTextColor("#FFFFFF")
    .build();

UPI Intent Checkout

CFIntentTheme cfTheme = new CFIntentTheme.CFIntentThemeBuilder()
    .setPrimaryTextColor("#000000")
    .setBackgroundColor("#FFFFFF")
    .build();

Create Checkout Payment Object

Web Checkout

This object combines all the configurations (session, theme) into a single checkout configuration. Finally, call doPayment() to open the Cashfree web checkout screen. This will present the user with the payment options and handle the payment process.

CFWebCheckoutPayment cfWebCheckoutPayment = new CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
    .setSession(cfSession)
    .setCFWebCheckoutUITheme(cfTheme)
    .build();

UPI Intent Checkout

This flow is for merchants who wants to quickly provide UPI functionality using cashfree’s mobile SDK without handling other modes like Cards or Net banking.

CFUPIIntentCheckout cfupiIntentCheckout = new CFUPIIntentCheckout.CFUPIIntentBuilder()
        // Use either the enum or the application package names to order the UPI apps as per your needed
        // Remove both if you want to use the default order which cashfree provides based on the popularity
        // NOTE - only one is needed setOrder or setOrderUsingPackageName
        .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
        .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
        .build();

CFUPIIntentCheckoutPayment cfupiIntentCheckoutPayment = new CFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder()
        .setSession(cfSession)
        .setCfUPIIntentCheckout(cfupiIntentCheckout)
        .setCfIntentTheme(cfTheme)
        .build();

Setup payment callback

The SDK exposes an interface CFCheckoutResponseCallback to receive callbacks from the SDK once the payment journey ends. This interface consists of 2 methods:

public void onPaymentVerify(String orderID)
public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID)

Make sure to set the callback at activity’s onCreate as this also handles the activity restart cases.

public class YourActivity extends AppCompatActivity implements CFCheckoutResponseCallback {
    ...
    @Override
    public void onPaymentVerify(String orderID) {

    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {

    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_upi_intent_checkout);
        try {
          // If you are using a fragment then you need to add this line inside onCreate() of your Fragment
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }
    }
    ...

}

Open Checkout Screen

Finally, call doPayment() to open the Cashfree checkout screen. This will present the user with the payment options and handle the payment process.

Web Checkout

// replace the WebCheckoutActivity class with your class name
CFPaymentGatewayService.getInstance().doPayment(WebCheckoutActivity.this, cfWebCheckoutPayment);

UPI Intent Checkout

// replace the UPIIntentCheckoutActivity class with your class name
CFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);

Step 3: Sample Code

Web Checkout Sample code

package com.cashfree.sdk_sample;

import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.cashfree.pg.api.CFPaymentGatewayService;
import com.cashfree.pg.core.api.CFSession;
import com.cashfree.pg.core.api.webcheckout.CFTheme;
import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;
import com.cashfree.pg.core.api.exception.CFException;
import com.cashfree.pg.core.api.utils.CFErrorResponse;
import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutPayment;
import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;

public class WebCheckoutActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

    String orderID = "ORDER_ID";
    String paymentSessionID = "TOKEN";
    CFSession.Environment cfEnvironment = CFSession.Environment.PRODUCTION;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_drop_checkout);
        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onPaymentVerify(String orderID) {
        Log.e("onPaymentVerify", "verifyPayment triggered");
       // Start verifying your payment
    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
        Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
    }

    public void doWebCheckoutPayment() {
        try {
            CFSession cfSession = new CFSession.CFSessionBuilder()
                    .setEnvironment(cfEnvironment)
                    .setPaymentSessionID(paymentSessionID)
                    .setOrderId(orderID)
                    .build();
            // Replace with your application's theme colors
            CFWebCheckoutTheme cfTheme = new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
                    .setNavigationBarBackgroundColor("#fc2678")
                    .setNavigationBarTextColor("#ffffff")
                    .build();
            CFWebCheckoutPayment cfWebCheckoutPayment = new CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
                    .setSession(cfSession)
                    .setCFWebCheckoutUITheme(cfTheme)
                    .build();
            CFPaymentGatewayService.getInstance().doPayment(WebCheckoutActivity.this, cfWebCheckoutPayment);
        } catch (CFException exception) {
            exception.printStackTrace();
        }
    }

}

UPI Intent Checkout Sample code

package com.cashfree.sdk_sample;

import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.cashfree.pg.api.CFPaymentGatewayService;
import com.cashfree.pg.core.api.CFSession;
import com.cashfree.pg.core.api.CFTheme;
import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;
import com.cashfree.pg.core.api.exception.CFException;
import com.cashfree.pg.core.api.utils.CFErrorResponse;
import com.cashfree.pg.ui.api.upi.intent.CFIntentTheme;
import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckout;
import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckoutPayment;

public class UPIIntentCheckoutActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

    String orderID = "ORDER_ID";
    String paymentSessionID = "PAYMENT_SESSION_ID";
    CFSession.Environment cfEnvironment = CFSession.Environment.SANDBOX;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_upi_intent_checkout);
        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onPaymentVerify(String orderID) {
        Log.e("onPaymentVerify", "verifyPayment triggered");
        // Start verifying your payment
    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
        Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
    }

    public void doUPIIntentCheckoutPayment() {
        try {
            CFSession cfSession = new CFSession.CFSessionBuilder()
                    .setEnvironment(cfEnvironment)
                    .setOrderToken(token)
                    .setOrderId(orderID)
                    .build();
            // Replace with your application's theme colors
            CFIntentTheme cfTheme = new CFIntentTheme.CFIntentThemeBuilder()
                    .setButtonBackgroundColor("#6A3FD3")
                    .setButtonTextColor("#FFFFFF")
                    .setPrimaryTextColor("#000000")
                    .setSecondaryTextColor("#000000")
                    .build();

            CFUPIIntentCheckout cfupiIntentCheckout = new CFUPIIntentCheckout.CFUPIIntentBuilder()
                    // Use either the enum or the application package names to order the UPI apps as per your needed
                    // Remove both if you want to use the default order which cashfree provides based on the popularity
                    // NOTE - only one is needed setOrder or setOrderUsingPackageName
                    .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
                    .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
                    .build();

            CFUPIIntentCheckoutPayment cfupiIntentCheckoutPayment = new CFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder()
                    .setSession(cfSession)
                    .setCfUPIIntentCheckout(cfupiIntentCheckout)
                    .setCfIntentTheme(cfTheme)
                    .build();
            CFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);
        } catch (CFException exception) {
            exception.printStackTrace();
        }
    }

}

Github Sample

Step 4: Confirming the Payment

After the payment is completed, you need to confirm whether the payment was successful by checking the order status. Once the payment finishes, the user will be redirected back to your activity to your implementation of the CFCheckoutResponseCallback interface.

You must always verify payment status from your backend. Before delivering the goods or services, please ensure you call check the order status from your backend. Ensure you check the order status from your server endpoint.

To verify an order you can call our /pg/orders endpoint from your backend. You can also use our SDK to achieve the same.

version := "2023-08-01"
response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
if err != nil {
	fmt.Println(err.Error())
} else {
	fmt.Println(httpResponse.StatusCode)
	fmt.Println(response)
}

Testing

You should now have a working checkout button that redirects your customer to Cashfree Checkout. If your integration isn’t working:

Open the Network tab in your browser’s developer tools.
Click the button and check the console logs.
Use console.log(session) inside your button click listener to confirm the correct error returned.

Error Codes

To confirm the error returned in your android application, you can view the error codes that are exposed by the SDK.

Error Codes

ERROR CODES	MESSAGE
MISSING_CALLBACK	The callback is missing in the request.
ORDER_ID_MISSING	The “order_id” is missing in the request.
CARD_EMI_TENURE_MISSING	The “emi_tenure” is missing or invalid (It has to be greater than 0).
INVALID_UPI_APP_ID_SENT	The id sent is invalid. The value has to be one of the following: “tez://”,“phonepe://”,“paytm://”,“bhim://. Please refer the note in CFUPI class for more details
INVALID_PAYMENT_OBJECT_SENT	The payment object that is set does not match any payment mode. Please set the correct payment mode and try again.
WALLET_OBJECT_MISSING	The CFWallet object is missing in the request
NETBANKING_OBJECT_MISSING	The CFNetbanking object is missing in the request.
UPI_OBJECT_MISSING	The CFUPI object is missing in the request.
CARD_OBJECT_MISSING	The CFCard object is missing in the request.
INVALID_WEB_DATA	The url seems to be corrupt. Please reinstantiate the order.
SESSION_OBJECT_MISSING	The “session” is missing in the request
PAYMENT_OBJECT_MISSING	The “payment” is missing in the request
ENVIRONMENT_MISSING	The “environment” is missing in the request.
ORDER_TOKEN_MISSING	The “order_token” is missing in the request.
CHANNEL_MISSING	The “channel” is missing in the request.
CARD_NUMBER_MISSING	The “card_number” is missing in the request.
CARD_EXPIRY_MONTH_MISSING	The “card_expiry_mm” is missing in the request.
CARD_EXPIRY_YEAR_MISSING	The “card_expiry_yy” is missing in the request.
CARD_CVV_MISSING	The “card_cvv” is missing in the request.
UPI_ID_MISSING	The “upi_id” is missing in the request
WALLET_CHANNEL_MISSING	The “channel” is missing in the wallet payment request
WALLET_PHONE_MISSING	The “phone number” is missing in the wallet payment request
NB_BANK_CODE_MISSING	The “bank_code” is missing in the request
WRONG_CALLING_CONTEXT	Calling context must be activity or fragment
NO_UPI_APP_AVAILABLE	You don’t have any UPI apps installed or ready for payment.
NO_EMI_PLAN_AVAILABLE	This account does not have EMI plans configured, or the order amount is less than 2499

Other Options

(Optional) Custom Initialisation of the SDK

If you require to initialise the SDK yourself then follow the steps below. Make sure to initialise the SDK in Application class to avoid any Runtime issues.

Add the following to your values.xml file

<bool name="cashfree_pg_core_auto_initialize_enabled">false</bool>

Initialize the SDK yourself before attempting payment

   Executors.newSingleThreadExecutor().execute(() -> { 
        CFPaymentGatewayService.initialize(getApplicationContext());
   });

(Optional) Enable logging to debugging issues

To enable SDK logging add the following to your values.xml file.<integer name="cashfree_pg_logging_level">3</integer>Following are the Logging levels.

VERBOSE = 2
DEBUG = 3
INFO = 4
WARN = 5
ERROR = 6
ASSERT = 7

(Optional) Disable Quick Checkout in Payment Page

If you want to disable quick checkout flow in the payment journey you can add the following to your values.xml file.<bool name="cf_quick_checkout_enabled">false</bool>

(Optional) Disable Encrypted SharedPreference

Add the following to your values.xml file.<bool name="cashfree_pg_core_encrypt_pref_enabled">false</bool>

💻 Quick dev-to-dev talk

You clearly care about building better payment experiences for your clients, here’s a quick tip: Earn additional income doing exactly what you’re doing now!Join the Cashfree Affiliate Partner Program and get rewarded every time your clients use Cashfree.What’s in it for you?

Earn up to 0.25% commission on every transaction
Be more than a dev - be the trusted fintech partner for your clients
Get a dedicated partner manager, your go-to expert

What’s in it for your clients?

Instant activation, go live in minutes.
Industry-best success rate across all payment modes.
Effortlessly accept international payments in 140+ currencies

Ready to push to prod? 👉 Become a Partner now

Payments

Payment Gateway

Checkout

Cross Border Payments

Flowwise

RiskShield

Subscription

Other Products

Developer updates

Android Integration

Cashfree’s Integrity Standards

Setting Up SDK

Step 1: Creating an Order

API Request for Creating an Order

Step 2: Opening the Payment Page

Create a Session

Customize Theme (Optional)

Create Checkout Payment Object

Setup payment callback

Open Checkout Screen

Step 3: Sample Code

Step 4: Confirming the Payment

Testing

Error Codes

Other Options

💻 Quick dev-to-dev talk

Payments

Payment Gateway

Checkout

Cross Border Payments

Flowwise

RiskShield

Subscription

Other Products

Developer updates

​Cashfree’s Integrity Standards

​Setting Up SDK

​Step 1: Creating an Order

API Request for Creating an Order

​Step 2: Opening the Payment Page

​Create a Session

​Customize Theme (Optional)

​Create Checkout Payment Object

​Setup payment callback

​Open Checkout Screen

​Step 3: Sample Code

​Step 4: Confirming the Payment

​Testing

​Error Codes

​Other Options

​💻 Quick dev-to-dev talk

Cashfree’s Integrity Standards

Setting Up SDK

Step 1: Creating an Order

Step 2: Opening the Payment Page

Create a Session

Customize Theme (Optional)

Create Checkout Payment Object

Setup payment callback

Open Checkout Screen

Step 3: Sample Code

Step 4: Confirming the Payment

Testing

Error Codes

Other Options

💻 Quick dev-to-dev talk