The Cashfree Xamarin Forms SDK allows you to integrate Cashfree Payment Gateway into your application and collect payments from your customers. It opens the payment page in a webview.
The Cashfree SDK has been designed to minimise the complexity of handling and integrating payments in your Xamarin project. The Cashfree Xamarin Forms SDK is available at the NuGet Gallery as a NuGet package.
The Xamarin Forms SDK is available here.
To integrate Cashfree Xamarin Forms SDK with your application,
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 - We recommend you to verify the payment response using webhooks and by checking the signature value returned in the payment response.
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 Xamarin Forms SDK.
Go to the Xamarin Forms project and right-click on Packages and click Manage NuGet Packages.
Browse for Cashfree.Forms.Payment.SDK and select the latest version of the package and click Add Package.
Add the following Dependency to the same project.
Xamarin.Forms;
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. To generatecftoken
you need to use our token generation API.
Request Description to Generate Token
Production - set the URL tohttps://api.cashfree.com/api/v2/cftoken/order
Testing - set the 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. 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.s79BTM0AjNwUDN1EjOiAHelJCLiIlTJJiOik3YuVmcyV3QyVPRu2mowm-8UXoyqAgsG"}
This API should be called from your server (backend) only, and never from your Xamarin Forms application as it uses the secretKey.
After generating the order token, the payment gets initiated when the payment API DoPayment is called.
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 Forms application and response is received on IPaymentResult
implementation.
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 an 'Invalid token' error.
After the payment is complete you will receive the response on the IPaymentResult.OnComplete()
function of the invoking Screen. In the result string, you will receive a set of response parameters which is used to determine if the transaction was successful or not.
public void OnComplete(string result){// verify the transaction here.}
We recommend you to verify the payment response using webhooks. You can also verify the response by checking the signature in the payment response.
Checkout is the standard flow for Cashfree Xamarin Forms SDK. In this flow, SDK loads a webview which renders the Cashfree's payment page. Customers can fill the required details here and complete 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 the 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 the two-factor authentication.
Web checkout supports payment through Google pay, Amazon pay, PhonePe and UPI payment modes.
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: Add this package in your class. using Com.Cashfree.PG;
DoPayment(Dictionary<string, string> InputParams, string Token, string Environment,IPaymentResult Result);
Returns a ContentPage which opens 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 IPaymentResult.OnComplete()
Parameters:
InputParams: 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.
Result: IPaymentResult implementation.
When you have a requirement for a customised payment flow, you can use the 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 do Web Checkout using Cashfree UI integration unless you are certain that you require a customised payment flow.
The following sections describe the additional parameters for each of the payment methods:
Add the following parameters to the params map before invoking DoPayment() method to initiate a seamless card transaction.
params[PARAM_PAYMENT_OPTION] = "card";params[PARAM_CARD_NUMBER] = "4434260000000008";//Replace Card numberparams[PARAM_CARD_MM] = "05"; // Card Expiry Month in MMparams[PARAM_CARD_YYYY] = "2021"; // Card Expiry Year in YYYYparams[PARAM_CARD_HOLDER] = "John Doe"; // Card Holder nameparams[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 the params map before invoking DoPayment() method to initiate a seamless Paypal transaction.
params[PARAM_PAYMENT_OPTION] = "paypal";
var page = CFPaymentService.DoPayment(Params, Token, Environment, this);if (page != null){await Navigation.PushAsync(page);}
It is recommended to verify the payment response from the SDK using one of the following methods.
We send a notification from Cashfree backend to your backend whenever a payment is successful for an order. This is useful for users in cases when the internet connection is not stable after payment. This will allow you to reconcile all the successful orders at your end. The notification will be sent to notifyUrl which is specified during order creation. The parameters sent in notification are described here.
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 rarely can take 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.
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 this received signature at your end. This will verify if the response has tampered. This verification has to be done on your server as it will involve 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 hashlibimport hmacimport 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 configsecret = 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 = newSecretKeySpec(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);}}}
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. |
These parameters are sent as extras to the onActivityResult(). They contain the details of the transaction.
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. |
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. Follow the steps available here to get the app ID and secret key.
When calling doPayment() ensure that the stage parameter is "PROD".
When calling doPayment() 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. Follow the steps available here to get the app ID and secret key from
the "Sandbox" section.
When calling doPayment() ensure that the stage parameter is "TEST".
When calling doPayment() ensure the params map is sent to your appId. Ensure it is the correct test appId.