Xamarin Android Support SDK
The Cashfree Xamarin Android Support SDK allows you to integrate Cashfree Payment Gateway into your application and start collecting payments from your customers.
The Cashfree SDK has been designed to minimise the complexity of handling and integrating payments in your application. The Cashfree Xamarin Android Support SDK is available at the NuGet Gallery as a NuGet package.
Cashfree Xamarin Android Support SDK is available here.
Watch the video to know how to integrate Cashfree Xamarin Android SDK with your Android application:
This SDK is not applicable for newly onboarded merchants.
Integration Steps
To integrate Cashfree Android Support SDK with your Android application,
- Create an account with Cashfree and get the API keys
- Integrate the Cashfree SDK into your application
- Generate Token - From Backend
- Initiate payment - Invoke a payment API from the Cashfree SDK with the token generated when the customer initiates payment for an order from your application. Cashfree SDK displays appropriate screens to the customer for the payment.
- Receive and handle response - Cashfree SDK returns the payment result for the order which should be handled in your application.
- Verify response - It is mandatory to verify the payment response by checking the signature value returned in the payment response. It is also highly recommended to implement webhook notifications to receive a notification from the Cashfree backend to your backend whenever a payment is successful for an order.
Step 1: Create Account and Get API Keys
- Go to Cashfree website and create an account. Click here for detailed steps on how to create and activate your account.
- Log in to your Merchant Dashboard using the same credentials.
- Click Payment Gateway section View Dashboard click Credentials. For security purposes, you need to enter your password for verification.
- Copy the app ID and the secret key. These values are required to create the order token from your server. Order tokens are used to authenticate the API calls made from Cashfree Android SDK.
Step 2: Integrate SDK
The Cashfree SDK is bundled as an AAR file according to the latest Android standards. We support integration from API level 16. Ensure that the minSdkVersion in the build.gradle of your app is equal to or greater than that.
To integrate the SDK, follow the steps below:
Step 2.1: Add Cashfree maven repository to your module's build.gradle file.
Gradle Script
repositories
{
maven
{
url 'https://maven.cashfree.com/release'
}
}
Step 2.2: Gradle Changes
Step 2.2.1 Open the build.gradle file of your module and add the Cashfree SDK in the dependency section.
For the android support library version, add the following:
implementation 'com.cashfree.pg:android-support-sdk:1.4.2.2'
For the latest androidX library version, add the following:
implementation 'com.cashfree.pg:android-sdk:1.7.8'
Step 2.2.2 Add other dependencies
You need to add a few additional dependencies to the build.gradle file depending on the payment type.
Click the links below to know more about what dependencies need to be added:
Step 2.3: Android Manifest Changes
The Cashfree SDK requires you to add the permissions shown below in your Android Manifest file.
<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application ...>
Add android.useAndroidX=true in gradle.properties file.
- Set the tools:node attribute to "merge" in the definition of your application element in the Android Manifest file.
- If the OTP auto-read-submit feature is enabled for your account add the Google Play services version meta-data.
<application
...
tools:node="merge">
<!--Only add it if you need Auto OTP reading feature is enabled-->
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
</application>
Step 3: Generate Token (From Backend)
The cftoken is used to authenticate the payment requests made from SDK. It has to be generated for every payment attempt made for an order. Pass this token to the SDK while initiating the payment for that order. For generating a cftoken you need to use our token generation API.
Request Description to Generate Token
Production - set the URL to https://api.cashfree.com/api/v2/cftoken/order
Testing - set the action URL to 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, you will receive a token. Please see the description of the request below.
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: Replace YOUR_APP_ID and YOUR_SECRET_KEY with actual values.
curl -XPOST -H 'Content-Type: application/json' -H 'x-client-id: YOUR_APP_ID' -H 'x-client-secret: YOUR_SECRET_KEY' -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"
}
This API should be called from your server (backend) only, and never from your Android application as it uses the secretKey.
Step 4: Initiate Payment
After generating the order token, the payment gets initiated when the payment APIs are called (doPayment, doUPIPayment, doGPayPayment, doAmazonPayment).
For payment, your application passes the order info and the cftoken to the SDK. The relevant payment screen is displayed to the customer where they enter the required information and make the payment. After the payment is complete the customers are redirected to the Android application and a response is received on onActivityResult().
- The order details passed during the token generation and the payment initiation should match. Else, you will get an
Invalid order details
error.- Wrong appId and token will result in
Unable to authenticate merchant
error. The token generated for payment is valid for 5 minutes within which the payment has to be initiated. Else, you will get anInvalid token
error.
Step 5. Receive and Handle Response
After the payment is complete you will receive the response on the onActivityResult() function of the invoking activity. In the intent extras, you will receive a set of response parameters which is used to determine if the transaction was successful or not. Request code will always be equal to CFPaymentService.REQ_CODE.
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
//Same request code for all payment APIs.
Log.d(TAG, "ReqCode : " + CFPaymentService.REQ_CODE);
Log.d(TAG, "API Response : ");
//Prints all extras. Replace with app logic.
if (data != null) {
Bundle bundle = data.getExtras();
if (bundle != null)
for (String key : bundle.keySet()) {
if (bundle.getString(key) != null) {
Log.d(TAG, key + " : " + bundle.getString(key));
}
}
}
}
Step 6. Verify Response
Once the SDK returns a response to the application, it is mandatory to verify the payment response by verifying the signature value returned in the payment response. It is also highly recommended to implement webhook notification to receive a notification from Cashfree backend to your backend whenever a payment is successful for an order.
Click here to know about the implementation details.
Sample Application
Click here to view the sample application.
Checkout
Checkout is the standard flow for Cashfree Android SDK. In this flow, SDK loads a webview which renders Cashfree's payment page. Customers can fill in the details here and complete the payment.
There are two types of Web Checkout methods. You can select the required method based on your business need.
- Web Checkout with Cashfree UI - Customer selects the payment mode and enters the payment details within Cashfree's web payment page to complete the payment.
- Seamless Web Checkout - Customer selects the payment mode and enters payment details in your application. These details are then passed on to the Cashfree SDK. Webview is launched only for two-factor authentication.
Web checkout supports payment through Google pay, Amazon pay, PhonePe and UPI payment modes.
Web Checkout Using Cashfree UI
Web checkout uses webview to process payment hence the name. For both Web Checkout and Seamless Web Checkout you need to invoke the DoPayment() method. However, there are a few extra parameters you need to pass for seamless integration method.
doPayment
CFPaymentService.CFPaymentServiceInstance.DoPayment(Context context,
Dictionary<String, String> params, String token, String stage);
Initiates the payment in a webview. The customer will be taken to the payment page on the Cashfree server where they have the option to pay through any payment option that is activated on their account. Once the payment is done the webview will close and the response will be delivered in the responseData as a callback as JsonString.
Parameters:
- Context: Context of the calling activity.
- Params: A map of all the relevant parameters described here.
- Token: The token generated here.
- Environment: Value should be either "TEST" for testing server, or "PROD" for production server respectively.
CFPaymentService.CFPaymentServiceInstance.DoPayment(Context context,
Dictionary<String, String> params, String token, String stage,
String color1, String color2)
Additional Parameters:
- color1: Toolbar background color.
- color2: Toolbar text and back arrow color.
If you want to hide the order ID, add another parameter hideOrderID as shown below:
CFPaymentService.CFPaymentServiceInstance.DoPayment(Context context,
Dictionary params, String token, String stage, bool hideOrderId)
If you want to customise the toolbar colour and also hide the order ID in the toolbar, add the parameters as shown below:
CFPaymentService.CFPaymentServiceInstance.DoPayment(Context context,
Dictionary params, String token, String stage,
String color1, String color2, bool hideOrderId)
Seamless Web Checkout
When you have a requirement for a customised payment flow, you can use seamless integration. You can implement the payment page as per your requirement and then use our SDK to authorise the payment. Once the payment details are collected the OTP or the two-factor authentication page will open in a webview. After the payment is confirmed the webview closes and you will receive a response.
We recommend that you use the Checkout integration method unless you are certain that you require a customised payment flow.
The following sections describe the additional parameters for each of the payment methods:
Credit/Debit Card
Add the following parameters to the params map before invoking the doPayment() method to initiate a seamless card transaction.
params[PARAM_PAYMENT_OPTION] = "card";
params[PARAM_CARD_NUMBER] = "4434260000000008";//Replace Card number
params[PARAM_CARD_MM] = "05"; // Card Expiry Month in MM
params[PARAM_CARD_YYYY] = "2021"; // Card Expiry Year in YYYY
params[PARAM_CARD_HOLDER] = "John Doe"; // Card Holder name
params[PARAM_CARD_CVV] = "123"; // Card CVV
Net Banking
Add the following parameters to the params map before invoking doPayment() method to initiate a seamless net banking transaction. All valid bank codes are available here.
params[PARAM_PAYMENT_OPTION] = "nb";
params[PARAM_BANK_CODE] = "3333";// Put correct bank code here
Wallet
Add the following parameters to the params map before invoking doPayment() method to initiate a seamless wallet transaction. All valid wallet codes are available here.
params[PARAM_PAYMENT_OPTION] = "wallet";
params[PARAM_BANK_CODE] = "4001";// Put correct wallet code here
UPI
Add the following parameters to the params map before invoking doPayment() method to initiate a seamless UPI transaction.
params[PARAM_PAYMENT_OPTION = "upi";
params[PARAM_UPI_VPA] = "testsuccess@gocash";// Put correct upi vpa here
Paypal
Add the following parameters to params map before invoking doPayment() method to initiate a seamless Paypal transaction.
params[PARAM_PAYMENT_OPTION] = "paypal";
Other Common SDK Functions
SetOrientation
public void setOrientation(Context context, int val)
Choose the orientation (portrait or landscape) of the payment page. By default, the payment page is shown in portrait orientation.
Parameters:
- val: If the integer value is zero the orientation will be in portrait mode. Else, it will be landscape mode.
- context: Context of the calling activity.
SetConfirmOnExit
By default, a confirmation dialog is displayed when the users press back in the payment screen. You have the option to disable the confirmation dialog.
public void setConfirmOnExit(Context context, boolean confirmOnExit)
Parameters:
- context: Context of the calling activity.
- confirmOnExit: Value should be true if you want to show a confirmation popup on pressing back in the payment screen.
Sample Code
CFPaymentService.CFPaymentServiceInstance.DoPayment(this, Pairs, Token, Environment);
Verify Response
Once the SDK returns a response to the application, it is mandatory to verify the payment response by verifying the signature value returned in the payment response and it also highly recommended to implement webhook notification.
Webhook Notifications
Webhooks are events that notify you about the payment. We send a notification from Cashfree backend to your backend whenever a payment is successful for an order. The notification will be sent to notifyUrl which is specified during order creation.
To specify notifyUrl, add it with other parameters (orderId, orderAmount etc.) as shown below:
params.put(PARAM_NOTIFY_URL, "https://example.com/path/to/notify/url/")
- Notifications are usually instant but in some rare cases it can take up to a minute to hit your server. Make sure that your URL supports https. Notifications are sent only in the case of successful payments.
- Sometimes you may receive the same notification two or more times. It is recommended to ensure that your implementation of the webhook is idempotent.
- Ensure that you verify the signature in the webhook response.
- This also handles scenarios for users in cases like the internet connection lost after payment, or user closing the application after payments, etc. It helps to reconcile all the successful orders at your end.
The parameters sent in notification are described here.
Verify Signature
Verify the signature value in the payment response to check the authenticity of the transaction response. In every response, we add a digital signature to establish the authenticity of the message. We require you to verify the signature received at your end to ensure that the response has not been tampered. This verification has to be done on your server as involves secretKey which should not be exposed on the client side.
<?php
$orderId = $_POST["orderId"];
$orderAmount = $_POST["orderAmount"];
$referenceId = $_POST["referenceId"];
$txStatus = $_POST["txStatus"];
$paymentMode = $_POST["paymentMode"];
$txMsg = $_POST["txMsg"];
$txTime = $_POST["txTime"];
$signature = $_POST["signature"];
$data = $orderId.$orderAmount.$referenceId.$txStatus.$paymentMode.$txMsg.$txTime;
$hash_hmac = hash_hmac('sha256', $data, $secretkey, true) ;
$computedSignature = base64_encode($hash_hmac);
if ($signature == $computedSignature) {
// Proceed
} else {
// Reject this call
}
?>
iimport hashlib
import hmac
import base64
@app.route('/notify_url/', methods=["POST"])
def notify_url_process():
postData = {
"orderId" : request.form['orderId'],
"orderAmount" : request.form['orderAmount'],
"referenceId" : request.form['referenceId'],
"txStatus" : request.form['txStatus'],
"paymentMode" : request.form['paymentMode'],
"txMsg" : request.form['txMsg'],
"txTime" : request.form['txTime'],
}
signatureData = postData["orderId"] + postData["orderAmount"] + postData["referenceId"] + postData["txStatus"] + postData["paymentMode"] + postData["txMsg"] + postData["txTime"]
message = bytes(signatureData).encode('utf-8')
#get secret key from your config
secret = bytes(secretKey).encode('utf-8')
signature = base64.b64encode(hmac.new(secret,
message,digestmod=hashlib.sha256).digest())
LinkedHashMap<String, String> postData = new LinkedHashMap<String, String>();
postData.put("orderId", ORDERID);
postData.put("orderAmount", ORDERAMOUNT);
postData.put("referenceId", REFERENCE_ID);
postData.put("txStatus", TXN_STATUS);
postData.put("paymentMode", PAYMENT_MODE);
postData.put("txMsg", TX_MSG);
postData.put("txTime", TX_TIME);
String data = "";
Set<String> keys = postData.keySet();
for (String key : keys) {
data = data + postData.get(key);
}
String secretKey = "" // Get secret key from config;
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key_spec = new
SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
sha256_HMAC.init(secret_key_spec);
String signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
using System;
using System.Security.Cryptography;
using System.Collections.Generic;
namespace Rextester {
public class Program {
private string CreateToken(string message, string secret){
secret = secret ?? "";
var encoding = new System.Text.ASCIIEncoding();
byte[] keyByte = encoding.GetBytes(secret);
byte[] messageBytes = encoding.GetBytes(message);
using (var hmacsha256 = new HMACSHA256(keyByte))
{
byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
return Convert.ToBase64String(hashmessage);
}
}
public static void Main(string[] args) {
string secret = "<your_secret_key>";
string data = "";
data = data + "FEX101";
data = data + "10.00";
data = data + "19992";
data = data + "SUCCESS";
data = data + "pg";
data = data + "payment done";
data = data + "2018-02-02 17:29:12";
Program n = new Program();
string signature = n.CreateToken(data, secret);
Console.WriteLine(signature);
}
}
}
Request and Response Parameters
Request Parameters
Parameter | Required | Description |
---|---|---|
appId | Yes | Your app ID |
orderId | Yes | Order or Invoice ID |
orderCurrency | Yes | Currency code for the order. |
orderAmount | Yes | Bill amount of the order |
orderNote | No | Help text to provide customers with more information about the order. |
customerName | No | Name of the customer |
customerPhone | Yes | Phone number of the customer |
customerEmail | Yes | Email ID of the customer |
notifyUrl | No | Notification URL for server-server communication. Useful when a user's connection drops after completing the 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
Parameter | Description |
---|---|
orderId | Order id for which transaction has been processed. Example, GZ-212. |
orderAmount | Order amount. Example, 256.00 |
paymentMode | Payment mode of the transaction. |
referenceId | Cashfree generated unique transaction ID. Example, 140388038803. |
txStatus | Payment status for that order. Values can be, SUCCESS, FLAGGED, PENDING, FAILED, CANCELLED. |
paymentMode | Payment mode used by customers to make the payment. Example, DEBIT_CARD, MobiKwik. |
txMsg | Message related to the transaction. Will have the reason, if payment failed. |
txTime | Time of the transaction. |
type | Fixed value : CashFreeResponse. To identify the response is from Cashfree SDK. |
signature | Response signature, more here. |
- There can be scenarios where the SDK is not able to verify the payment within a short period of time. The status of such orders will be PENDING.
- If the Webview closes immediately after it is opened then it could be because of some issues with the input that is passed to the SDK. Check the inputs passed and if you still need further help reach out to us at [email protected].
- If you are getting INCOMPLETE as the transaction status please reach out to your account manager or [email protected]. To know more about the transaction statuses, click here.
Checklist
Checklist to Go Live
- Ensure you trigger https://api.cashfree.com/api/v2/cftoken/order endpoint to generate the Token.
- Pass the production appId/secretKey in the x-client-id and x-client-secret of the token request API.
- When calling doPayment() or upiPayment() ensure that the stage parameter is "PROD".
- When calling doPayment() or upiPayment() ensure the params map is sent to your appId. Ensure it is the correct production appId.
Checklist to Test the Integration
- Ensure you trigger https://test.cashfree.com/api/v2/cftoken/order endpoint to generate the token.
- Pass the Test app ID and secret key in the x-client-id and x-client-secret of the token request API.
- When calling doPayment() or upiPayment() ensure that the stage parameter is "TEST".
- When calling doPayment() or upiPayment() ensure the params map is sent to your appId. Ensure it is the correct test appId.
Updated about 1 year ago