Getting Started

This mode provides you a JavaScript implementation to integrate with the Cashfree Payment Gateway. With this your customers can provide the payment details on your website, without you worrying about PCI compliance, and don’t need to navigate away from your website.

If you'd rather not include our payment form on your page, consider using our Checkout Form product which offers a much simpler way of integrating with Cashfree.
  1. Checkout Form

Merchant Hosted

This integration mode allows customers to provide their card/bank details on the merchant’s website itself. Unlike Checkout form/API based integration, users never need to navigate away from your website, thus providing a richer user flow experience.

Customer card details are accepted inside a cashfree-managed iframe. You do not have to work on securing the details yourself and you can use this mode without worrying about PCI compliances as we take care of it on your behalf.

Step 1: Cashfree JavaScript

Cashfree.js is our key JavaScript library for you to start building a payment flow customized to your requirements. You will need to include Cashfree’s javascript library in your page.

<script src="https://www.cashfree.com/assets/cashfree.sdk.v1.2.js" type="text/javascript"></script>

Step 2: Initialize Cashfree Config

Ideally your customers will be making a transaction for a particular order. To identify this particular order in your system you’ll use an identifier aka orderId. As your payments are processed by Cashfree you’ll need to send us the orderId and the corresponding orderAmount. In return after the payment is done we will inform you about the status of the payment corresponding to this orderId.
There are other details also which you need to send to us for processing a payment. You can take a look at all the request parameters below.

Every request must contain a valid signature. See here on how to generate a valid signature.

There are two ways to use the Merchant Hosted integration inside your website: an Inline mode or a Pop-up mode.

Inline Mode

In this mode the Cashfree payment form will be embedded in your web-page.

Example Screenshot

View Code

The payment form in this mode will be overlayed on your webpage and you don’t need to make any changes to your page layout.

Example Screenshot

View Code

We allow you to modify the look and feel of the payment form in both these modes.

Step 3: Checksum Generation

Every request to Cashfree must contain authentication information to establish the identity of the user making the request. We use a digital signature (aka a digital thumbprint) to validate each transaction. A digital signature helps us in verifying the originator of the message and also ensures integrity of the signed data against tampering.

In the sample form above you need to generate a signature for every checkout. Technically, the signature is generated as the HMAC value of the data being passed. Generated using SHA256 hash function in combination with merchant’s API secret key (Your API secret key can be retrieved from “Settings -> API Access” tab). We will generate a signature at our end and expect you to do the same with the posted data and match it with the passed argument.

Checksum generation varies across integration methods, please verify if you are using the right signature generation method.

<?php
   $appId = "APP_ID"; 
   $secretKey = "SECRET_KEY";
   $orderId = "ORDER_ID";
   $orderAmount = "ORDER_AMOUNT";
   $returnUrl = "RETURN_URL"; 
   $paymentModes = ""; //keep it blank to display all supported modes
   $tokenData = "appId=".$appId."&orderId=".$orderId."&orderAmount=".$orderAmount."&returnUrl=".$returnUrl."&paymentModes=".$paymentModes;
   $token = hash_hmac('sha256', $tokenData, $secretKey, true);
   $paymentToken = base64_encode($token); 
 ?>

import hashlib
import hmac
import base64

data = "appId=" + appId + "&orderId=" + orderId + "&orderAmount=" + orderAmount + "&returnUrl=" + returnUrl + "&paymentModes=" + paymentModes;
message = bytes(data).encode('utf-8')
secret = bytes(secretKey).encode('utf-8')
paymentToken = base64.b64encode(hmac.new(secret, message,digestmod=hashlib.sha256).digest())

String data = "appId=" + appId + "&orderId=" + orderId + "&orderAmount=" + orderAmount + "&returnUrl=" + returnUrl + "&paymentModes=" + paymentModes;
  Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
  SecretKeySpec skspec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
  sha256_HMAC.init(skspec);
  paymentToken = Base64.encodeBase64String(sha256_HMAC.doFinal(data.getBytes()));

using System;
using System.Security.Cryptography;

namespace HttpUtils
{
  public class CashFreeToken
  {
     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 appId = "<Your_APP_ID>";
       String orderId = "<Your_Order_ID>";
       String orderAmount = "<Order_amount>";
       String returnUrl = "<return_url>";
       String paymentModes = "";
       String secret = "<secret_key>";

       String data = "appId=" + appId + "&orderId=" + orderId + "&orderAmount=" + orderAmount + "&returnUrl=" + returnUrl + "&paymentModes=" + paymentModes;

       CashFreeToken n = new CashFreeToken();
       String signature = n.CreateToken(data, secret);
       Console.WriteLine(signature);
     }
  }
}

Step 4: Trigger Payment

To trigger payment from your webpage you need to prepare the payment details and send them to us using the same javascript library. You just need to call the CashFree.makePayment(data, callback) method in your javascript to process the payment.

Every request to Cashfree must contain authentication information to establish the identity of the user making the request, we use the `signature` field for this authentication. See here on how to generate a valid signature for Checkout integration.
Code snippet just before the closing </body> tag of your html page.

You’ll need to fill in the correct credentials for appId (You can find your appId from the merchant dashboard). The returnUrl is your webpage where the customer will be redirected to post payment on Cashfree, we will post the response parameters to this page.

Cashfree posts form variables to a URL notifyUrl you specify that runs a program to process these variables. Checkout the Response parameters which Cashfree will post to these URLs.

Request Parameters

You must send us the below JSON data parameters for us to process your request. The required fields below are necessary for us to process any request.

Parameter Required Description
appId Yes Your app id
orderId Yes Order/Invoice Id
orderAmount Yes Bill amount of the order
orderCurrency No Currency for the order. INR if left empty. See the Currency Codes for a list of available currencies. Please contact care@cashfree.com to enable new currencies
orderNote No A help text to make customers know more about the order
customerName Yes Name of the customer
customerPhone Yes Phone number of customer
customerEmail Yes Email id of the customer
returnUrl Yes Return URL to which user will be redirected after the payment
notifyUrl No Notification URL for server-server communication. Useful when user’s connection drops while notifyUrl should be an https URL
paymentModes No Allowed payment modes for this order. Available values: cc, dc, nb, paypal, wallet. Leave it blank if you want to display all modes
paymentToken Yes signature. More here

Configuration Parameters

The following Configuration parameters are used when initalizing the Cashfree Config.

Parameter Required Description
mode Yes Integration stage. Values could be TEST or PROD
layout Yes javascript object to define layout
layout.view Yes (i) “inline” for inline view (ii) “popup” for popup (iii) “page” for standard redirect flow
layout.width No Width of payment form. Value should be a number. Could be in range of 500 to 700.
layout.container Yes Applicable(and mandatory) for inline view. Id of a html div/section into which payment form will be rendered.

Test Card

You can use these cards in your test suite.

Response parameters

Cashfree will return details about every transaction to the methods you implement. The response parameters will be sent to the javascript callback method. We will also post the same details from our servers to your notify_url. You should process these details accordingly. Do checkout the code below to verify the response that we send.

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. More here
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
signature Response signature, more here. It is mandatory to verify the signature.

Response Verification

IMPORTANT: Verify the response signature to check the authenticity of transaction response. Don't forget to follow the steps mentioned below.

Similar to every request (request checksum) we also send a digital signature in our response message. We strongly recommend you to verify this received signature at your end as well. This will verify if the response has not been tampered with.


<?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
 }
 ?>

import 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 = ""
 for key in postData.keys():
   signatureData += postData[key];

 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);
    }
  }
}

Test Checksum

Use the below form to confirm if you are generating the correct checksum. To understand the logic behind generating the checksum, see here.

Please verify if you are generating the correct checksum.


App Id: Secret Key: Order Id: Order Amount: Return URL: Payment Modes:

Checksum: Checksum