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.
import{Cashfree}from"cashfree-pg";Cashfree.XClientId={ClientID};Cashfree.XClientSecret={ClientSecretKey};Cashfree.XEnvironment=Cashfree.Environment.PRODUCTION;functioncreateOrder(){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("2023-08-01", 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 /ordershere.
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.
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.
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]
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).
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.
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 =newCFUPIIntentCheckout.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 =newCFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder().setSession(cfSession).setCfUPIIntentCheckout(cfupiIntentCheckout).setCfIntentTheme(cfTheme).build();
Make sure to set the callback at activity’s onCreate as this also handles the activity restart cases.
publicclassYourActivityextendsAppCompatActivityimplementsCFCheckoutResponseCallback{...@OverridepublicvoidonPaymentVerify(String orderID){}@OverridepublicvoidonPaymentFailure(CFErrorResponse cfErrorResponse,String orderID){}@OverrideprotectedvoidonCreate(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 FragmentCFPaymentGatewayService.getInstance().setCheckoutCallback(this);}catch(CFException e){ e.printStackTrace();}}...}
Finally, call doPayment() to open the Cashfree checkout screen. This will present the user with the payment options and handle the payment process.
// replace the WebCheckoutActivity class with your class nameCFPaymentGatewayService.getInstance().doPayment(WebCheckoutActivity.this, cfWebCheckoutPayment);
// replace the UPIIntentCheckoutActivity class with your class nameCFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);
packagecom.cashfree.sdk_sample;importandroid.content.Intent;importandroid.os.Bundle;importandroid.util.Log;importandroidx.appcompat.app.AppCompatActivity;importcom.cashfree.pg.api.CFPaymentGatewayService;importcom.cashfree.pg.core.api.CFSession;importcom.cashfree.pg.core.api.CFTheme;importcom.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;importcom.cashfree.pg.core.api.exception.CFException;importcom.cashfree.pg.core.api.utils.CFErrorResponse;importcom.cashfree.pg.ui.api.upi.intent.CFIntentTheme;importcom.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckout;importcom.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckoutPayment;publicclassUPIIntentCheckoutActivityextendsAppCompatActivityimplementsCFCheckoutResponseCallback{String orderID ="ORDER_ID";String paymentSessionID ="PAYMENT_SESSION_ID";CFSession.Environment cfEnvironment =CFSession.Environment.SANDBOX;@OverrideprotectedvoidonCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);setContentView(R.layout.activity_upi_intent_checkout);try{CFPaymentGatewayService.getInstance().setCheckoutCallback(this);}catch(CFException e){ e.printStackTrace();}}@OverridepublicvoidonPaymentVerify(String orderID){Log.e("onPaymentVerify","verifyPayment triggered");// Start verifying your payment}@OverridepublicvoidonPaymentFailure(CFErrorResponse cfErrorResponse,String orderID){Log.e("onPaymentFailure "+ orderID, cfErrorResponse.getMessage());}publicvoiddoUPIIntentCheckoutPayment(){try{CFSession cfSession =newCFSession.CFSessionBuilder().setEnvironment(cfEnvironment).setOrderToken(token).setOrderId(orderID).build();// Replace with your application's theme colorsCFIntentTheme cfTheme =newCFIntentTheme.CFIntentThemeBuilder().setButtonBackgroundColor("#6A3FD3").setButtonTextColor("#FFFFFF").setPrimaryTextColor("#000000").setSecondaryTextColor("#000000").build();CFUPIIntentCheckout cfupiIntentCheckout =newCFUPIIntentCheckout.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 =newCFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder().setSession(cfSession).setCfUPIIntentCheckout(cfupiIntentCheckout).setCfIntentTheme(cfTheme).build();CFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);}catch(CFException exception){ exception.printStackTrace();}}}
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.
To confirm the error returned in your android application, you can view the error codes that are exposed by the SDK.
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
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.