Getting Started

Use our library to integrate the Cashfree Payment Gateway directly into your app using CashfreeSDK for Android. CashfreeSDK has been designed to offload the complexity of handling and integrating payments in your app.

The CashfreeSDK is available at a publicly hosted github repo as an AAR (link below). Instructions on importing the lib is also provided.

CashFree Android SDK V0

The installation section lists all the prerequisits for using the SDK.

Checkout Integration

This is the standard integration for Cashfree SDK. With this integration you can load a webview which will then render cashfree payment page where the customer will fill in the details and complete the payment. After completing payment they will be redirected back to your app and you will get a callback. Please follow these steps to complete:

Step 1: Download Library

Download cashfreeSDK.aar. The Cashfree SDK is bundled as an AAR file according to the latest Android standards. Please include this library as a dependency in your app. Read more here: https://developer.android.com/studio/projects/android-library#AddDependency

Step 2: Add dependencies

The CashfreeSDK requires that you add the permissions shown below in your Android Manifest file. We support integration from API level 15. Do ensure that the minSdkVersion in the build.gradle of your app is equal(or greater) than that.

<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application ...>

Add Volley dependency in your build.gradle

dependencies {
    ...
    compile 'com.android.volley:volley:1.1.0'
}


Step 3: Implement Interface

Implement the CFClientInterface in the calling activity. Invoke the payment gateway with a couple of lines of code from your activity.

public interface CFClientInterface {
    // The Payment succeeded
    void onSuccess(Map<String, String> params);

    // Payment did not succeed 
    void onFailure(Map<String, String> params);

    // The user navigated back from payment activity
    void onNavigateBack();
}


Step 4: Generate Token (From Backend)

You will need to generate a token and pass it to SDK while initiating payments for security reasonse. For generating token you need to use our token generation API. Please take care that this API is called only from your backend as it uses secretKey. Thus this API should never be called from App.

For production/live usage set the endpoint will be: https://api.cashfree.com/api/v2/cftoken/order
For testing the endpoint will be: https://test.cashfree.com/api/v2/cftoken/order

You need to send orderId, orderCurrency and orderAmount as a JSON object to the API endpoint and in response a token will received. Please see the description of request below.

Request Description

For production/live usage set the endpoint will be: https://api.cashfree.com/api/v2/cftoken/order
For testing the endpoint will be: https://test.cashfree.com/api/v2/cftoken/order

curl -XPOST -H 'Content-Type: application/json' 
-H 'x-client-id: <YOUR_APP_ID>' 
-H 'x-client-secret: <YOUR_SECRET_KEY>' 
-d '{
  "orderId": "<ORDER_ID>",
  "orderAmount":<ORDER_AMOUNT>,
  "orderCurrency": "INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'


Request Example

curl -XPOST -H 'Content-Type: application/json' -H 'x-client-id: 275432e3853bd165afbf5272' -H 'x-client-secret: 2279c0ffb9550ad0f9e0652741c8d06a49409517' -d '{
  "orderId": "Order0001",
  "orderAmount":1,
  "orderCurrency":"INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'


Response Example

{
"status": "OK",
"message": "Token generated",
"cftoken": "v79JCN4MzUIJiOicGbhJCLiQ1VKJiOiAXe0Jye.s79BTM0AjNwUDN1EjOiAHelJCLiIlTJJiOik3YuVmcyV3QyVGZy9mIsEjOiQnb19WbBJXZkJ3biwiIxADMwIXZkJ3TiojIklkclRmcvJye.K3NKICVS5DcEzXm2VQUO_ZagtWMIKKXzYOqPZ4x0r2P_N3-PRu2mowm-8UXoyqAgsG"
}

The “cftoken” attribute is the token that needs to be used to secure your request. We will cover in next step

Step 5: Initiate Payment

The token generated in the last step needs to be sent back to your app. This token will be used as a parameter in the initiation of payment. If you are doing standard payment gateway integration you need to call the CFPaymentService.doPayment() method next. If you want to initiate UPI Intent payment then call CFPaymentService.upiPayment(). Eiher way this will take in all the parameters related to order and the token generated in the last step and initiate the payment. Use this table to see all the avaialable parameters you can send.

Step 6: Receive Callback

Once the payment is done you will receive the callback on the appropriate method of CFClientInterface implementation. In the params map you will receive a set of response parameters which you can use to determine if the transaction was successful.





Seamless Integration

Seamless integration can be used when there is a requirement of a more customized payment flow. In seamless integration you can implement the payment page yourself and then use our SDK to authorize the payment. Once the payment details are collected the OTP/2FA page will open in a webview. After the payment is confirmed the webview closes and you will get a callback.

Please note that seamless integration will require an activation from our end. Also the integration tends to be longer because the payment page needs to be implemented by you. We recommend that you do Checkout integration unless you are certain that seamless integration is required.

How to integrate

All the steps are exactly similar to checkout integration except step 5. Please follow steps 1 to 4 as listed in the Checkout integration. In the 5th step you need to invoke the doPayment() method. However, there are a few extra parameters you need to add to invoke payment depending on the payment method. The following sections describe these parameters for each of the payment methods.

After payment you will get a callback exactly as in step 6 of Checkout Integration.

Credit/Debit Card

Add the following parameters to params map as illustrated before invoking doPayment() for initiating a seamless card transaction.

params.put(PARAM_PAYMENT_OPTION, "card");
params.put(PARAM_CARD_NUMBER, "4434260000000008");//Replace Card number
params.put(PARAM_CARD_MM, "05"); // Card Expiry Month in MM 
params.put(PARAM_CARD_YYYY, "2021"); // Card Expiry Year in YYYY 
params.put(PARAM_CARD_HOLDER, "John Doe"); // Card Holder name
params.put(PARAM_CARD_CVV, "123"); // Card CVV


Net Banking

Add the following parameters to params map as illustrated before invoking doPayment() for initiating a seamless net banking transaction.

params.put(PARAM_PAYMENT_OPTION, "nb");
params.put(PARAM_BANK_CODE, "3333");// Put correct bank code here

All valid Bank Code could can be seen here.

Wallet

Add the following parameters to params map as illustrated before invoking doPayment() for initiating a seamless wallet transaction.

params.put(PARAM_PAYMENT_OPTION, "wallet");
params.put(PARAM_BANK_CODE, "4001");// Put correct wallet code here

All valid Wallet Codes could can be seen here.

UPI

Add the following parameters to params map as illustrated before invoking doPayment() for initiating a seamless UPI transaction.

params.put(PARAM_PAYMENT_OPTION, "upi");
params.put(PARAM_UPI_VPA, "testsuccess@gocash");// Put correct upi vpa here


Paypal

Add the following parameter to params map as illustrated before invoking doPayment() for initiating a seamless Paypal transaction.

params.put(PARAM_PAYMENT_OPTION, "paypal");


CFPaymentService Methods

The CFPaymentService is the primary class which is invoked for all the interactions with the Cashfree SDK. In this section we list all the relevant public methods available on CFPaymentService.

doPayment

public void doPayment(Context context, Map<String, String> params, String token, CFClientInterface callback, String stage)

Initiate the payment in a webview. The customer will be taken to the payment page on cashfree server where they will have the option of paying through any payment option that is activated on their account. Once the payment is done the webview will close and the “callback” object’s onSuccess() or onFailure() method is invoked.

Parameters:

  • context: Context object of the calling activity is required for this method. In most of the cases this will mean sending the instance of the calling activity (this).
  • params: A map of all the relevant parameters described here
  • token: The token generated here
  • callback: An instance of class which has implemented CFClientInterface. This will be used to invoke callback after payment.
  • stage: Value should be either "TEST" or "PROD" for testing server or production server respectively.

upiPayment

public void upiPayment(Context context, Map<String, String> params, String token, CFClientInterface callback, String stage)

Payment done through a UPI intent. When the method is invoked the customer will be presented with a list showing all the installed UPI Apps on their device. If instead you want to preselect the client that should be chosen for payment use this method. Once the customer selects their preffered app, the payment confirmation page on the app will open. Once the payment is done on their UPI App the “callback” object’s onSuccess() or onFailure() method is invoked.

Parameters:

  • context: Context object of the calling activity is required for this method. In most of the cases this will mean sending the instance of the calling activity (this).
  • params: A map of all the relevant parameters described here
  • token: The token generated here
  • callback: An instance of class which has implemented CFClientInterface. This will be used to invoke callback after payment.
  • stage: Value should be either "TEST" or "PROD" for testing server or production server respectively.

selectUpiClient

public void selectUpiClient(String upiClientPackage)

When initiating the UPI intent the customer is presented with a list of all the UPI client Apps (BHIM, GPay, PhonePe etc.) on their phone. This allows the customer to choose any UPI App they want to pay with. If instead you want the customer to pay with a particular app you can use this method. After calling this method whenever upiPayment is called the customer will be no longer be shown an App selection screen and instead will be redirected to the App whose package is provided in the argument.

Parameters:

  • upiClientPackage: The string describing the java package of the upi client that is to be selected.

getUpiClient

public String[] getUpiClients(Context context)

Get the packages of all the UPI Clients installed on the device as a string array. These packages can then be passed to selectUpiClient() method to initiate payment.

Parameters:

  • context: Context object of the calling activity is required for this method. In most of the cases this will mean sending the instance of the calling activity (this).

setOrientation

public void setOrientation(int val)

Choose the orientation (portrait or landscape) of the payment page. By default the payment page is shown in portrait orientation.

Parameters:

  • val: An integer value if this is zero the orientation will be portrait. Else it will be landscape

setConfirmOnExit

public void setConfirmOnExit(boolean confirmOnExit)

Choose whether or not the exit confirmation popup is shown when the user presses back on payment page. By default the popup is shown.

Parameters:

  • confirmOnExit: Value should be true if you want to show a confirmation popup on pressing back during payment.



Webhook Notification

We send a notification from our backend to your backend whenever an order is successful. This is useful in cases where the user internet connection breaks after payment. This will allow you to reconcile all the successful orders on your end. The notification will be sent to notifyUrl which is specified at order creation. The parameters sent in notification are described here.

To specify notifyUrl just add it alongside other parameters (orderId, orderAmount etc.) like the following:

params.put(PARAM_NOTIFY_URL, "https://exapmle.com/path/to/notify/url/");

Please make a note of the following:

  • Notification can take upto one minute to hit your server after payment.
  • Notifications are sent only in the case of successful payments. Failed or pending payments wont lead to a notification being sent.
  • There might be cases where we send the same notification two or more times. It is recommended to rely on the first notification for reconciliation and silently ignore any subsequent notifications.

Request Parameters

Parameter Required Description
appId Yes Your app id
orderId Yes Order/Invoice Id
orderAmount Yes Bill amount of the order
orderNote No A help text to make customers know more about the order
customerName No Name of the customer
customerPhone Yes Phone number of customer
customerEmail Yes Email id of the customer
notifyUrl No Notification URL for server-server communication. Useful when user’s connection drops after completing payment.
paymentModes No Allowed payment modes for this order. Available values: cc, dc, nb, paypal, upi, wallet. Leave it blank if you want to display all modes

Response parameters

These parameters are returned to the callback functions you implement (for e.g. params argument of the CFClientInterface onSuccess() method). They contain the details of the transaction.

Parameter Description
orderId Order id for which transaction has been processed. Ex: GZ-212
orderAmount Amount of the order. Ex: 256.00
referenceId Cashfree generated unique transaction Id. Ex: 140388038803
txStatus Payment status for that order. Values can be : SUCCESS, FLAGGED, PENDING, FAILED, CANCELLED.
paymentMode Payment mode used by customer to make the payment. Ex: DEBIT_CARD, MobiKwik, etc
txMsg Message related to the transaction. Will have the reason, if payment failed
txTime Time of the transaction

Going Live

Checklist for going live

  • Ensure you are triggering https://api.cashfree.com/api/v2/cftoken/order endpoint for generating Token
  • Pass the Production appId/secretKey in the x-client-id and x-client-secret of the token request API. Obtain these appId/secretKey from here under the "Production" section.
  • When calling doPayment()/upiPayment() ensure that the stage parameter is "PROD".
  • When calling doPayment()/upiPayment() the params map is sent your appId. Please ensure it is correct production appId.

Checklist for reverting to test

  • Ensure you are triggering https://test.cashfree.com/api/v2/cftoken/order endpoint for generating Token
  • Pass the Test appId/secretKey in the x-client-id and x-client-secret of the token request API. Obtain these appId/secretKey from here under the "Sandbox" section.
  • When calling doPayment()/upiPayment() ensure that the stage parameter is "TEST".
  • When calling doPayment()/upiPayment() the params map is sent your appId. Please ensure it is correct test appId.