Getting Started

Seamless Basic integration allows you to provide your own payment form to your customers. With this you can collect all payment details on your webpage and safely send them to Cashfree for processing. You do not have to worry about PCI compliance as we take care of it on your behalf.

If you'd rather not build your own payment form you can consider using our Checkout Form product which offers a much simpler way of integrating with Cashfree or a pre-built payment form.
  1. Checkout Form
  2. Embedded

Step 1: Preparing payment form

You first need to prepare a basic payment form on your webpage (see a basic payment form below). We’ve also added some simple javascript methods to capture the submitted payment details in the below code snippet, these methods will be filled in Step 3.

Step 2: Cashfree Javascript

Once you have the basic html form ready, include Cashfree’s javascript library in your page. We will use this js sdk to send payment details to Cashfree and make the payment.

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

Step 3: Initializing 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 completed 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. See here to view all the request parameters you need to send.

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 below code on how to generate a valid signature for Checkout integration.


There are two ways to use Seamless integration inside your website: a re-direct mode or a pop-up mode.
  • Popup Mode In this mode you the customer will enter their two-factor authentication details on the same page and will land back on the same page post payment completion.

View Code

  • Redirect Mode In this mode the customer will be redirected to another page post payment completion. The return url should be specified by you when using this mode.

View Code

We have filled in the javascript methods you’ll need when accepting payments in either of the two methods.

Step 4: 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.
Sample code for you to generate a valid `signature`.

<?php
   $appId = "<your_app_id>"; //replace it with your appId
   $secretKey = "<your_secret_key">; //replace it with your secret key
   $orderId = "1234";
   $orderAmount = 450;
   $customerEmail = test@gmail.com
   $customerPhone = 9900012345;
   $tokenData = "appId=".$appId."&orderId=".$orderId."&orderAmount=".$orderAmount."&customerEmail=".$customerEmail."&customerPhone=".$customerPhone."&orderCurrency=".$orderCurrency;
   $token = hash_hmac('sha256', $tokenData, $secretKey, true);
   $paymentToken = base64_encode($token);
 ?>

import hashlib
import hmac
import base64

data = "appId=" + appId + "&orderId=" + orderId + "&orderAmount=" + orderAmount + "&customerEmail=" + customerEmail + "&customerPhone=" + customerPhone + "&orderCurrency=" + orderCurrency;
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 + "&customerEmail=" + customerEmail + "&customerPhone=" + customerPhone + "&orderCurrency=" + $orderCurrency;
  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 customerEmail = "<return_url>";
       String customerPhone = "";
       String secret = "<secret_key>";

       String data = "appId=" + appId + "&orderId=" + orderId + "&orderAmount=" + orderAmount + "&customerEmail=" + customerEmail + "&customerPhone=" + customerPhone + "&orderCurrency=" + $orderCurrency;

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

Step 5: Trigger Payment

Once you have the basic elements in place - the payment form, Cashfree.js and the config object, you can start accepting payments from your customers - we do this using the CashFree.paySeamless(data, callback) javascript method.

Parameter Description
data A simple JS Object containing all the data related to transaction. All possible parameters are listed below
paymentCallback (Optional) A callback method of the form paymentCallback(event). Event object is described here. This is not required for redirect option.

paymentCallback as mentioned above is a javascript method of the form paymentCallback(event). This method will be called once to report the status of the Payment. The event parameter will have details of the transaction. Here are the various possible values of the event parameter.

Case event.name event.status
Successful Payment PAYMENT_RESPONSE SUCCESS
Payment Failed PAYMENT_RESPONSE FAILED
Pending Payment PAYMENT_RESPONSE PENDING
Payment cancelled by user PAYMENT_RESPONSE CANCELLED
Payment successful but kept on hold by risk system PAYMENT_RESPONSE FLAGGED
Invalid inputs VALIDATION_ERROR -
`CashFree.initPopup()` is required for the popup to work even in case of callback.

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
data.appId Yes Your app id
data.orderId Yes Order/Invoice Id
data.orderAmount Yes Bill amount of the order
data.orderCurrency Yes Currency for the order. See the Currency Codes for a list of available currencies. Please contact care@cashfree.com to enable new currencies
data.orderNote No A help text to make customers know more about the order
data.customerName Yes Name of the customer
data.customerPhone Yes Phone number of customer.
data.customerEmail Yes Email id of the customer.
data.notifyUrl No Notification URL for server-server communication. Useful when user’s connection drops while re-directing. notifyUrl should be an https URL
data.returnUrl Yes - Redirect NA - Popup Return url for redirecting once payment is completed.
data.paymentToken Yes Request signature, more here
data.pc No Partner Code

Configuration Parameters

CREDIT CARD

These parameters are available only for Credit Card Payments

Parameter Required Description
data.card.num Yes Credit Card Number. Sixteen digits only. No spaces or Hyphens
data.card.expiryMonth Yes Expiration Month for the Credit Card. In MM format
data.card.expiryYear Yes Expiration Year for the Credit Card. In YYYY format
data.card.cvv Yes CVV number of the Credit Card
data.card.holder Yes Name of the Card Holder
data.paymentOption Yes card for Debit/Credit Cards

NET BANKING

These parameters are available only for Credit Card Payments

Parameter Required Description
data.nb.code Yes Code for the Bank See the list below
data.paymentOption Yes nb for Net banking

WALLET

These parameters are available only for Wallets

Parameter Required Description
data.wallet.code Yes Code for the Wallet See the list below
data.paymentOption Yes wallet for Wallet

UPI

These parameters are available only for UPI

Parameter Required Description
data.upi.vpa Yes UPI VPA for triggering UPI payment
data.paymentOption Yes upi for UPI

Paypal

These parameters are available only for UPI

Parameter Required Description
data.paymentOption Yes paypal for Paypal

Test Card

You can use these cards in your test suite.

Response parameters

CashFree will post details about every transaction to both the callback method and the notify_url. These parameters will be posted to the services you host on these urls. You should use these details accordingly.

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

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.
App Id: Secret Key: Order Id: Order Amount: Customer Email: Customer Phone: Order Currency:

Checksum: checksum