Seamless Basic

In this integration method, you can customise the payment form as per your business requirements that work best for your customers. You collect all payment details on your webpage and send these details to Cashfree to process the payment. Cashfree handles the PCI compliance guidelines on your behalf in this integration method.

Steps to Integrate

  1. Prepare Payment Form
  2. Include Javascript Code
  3. Initialise Configuration
  4. Generate Signature
  5. Accept Payment

Prepare Payment Form

Prepare a basic payment form on your webpage. We have also added some simple javascript methods to capture the submitted payment details in the code snippet below, these details will be filled in later as explained in step 3.

Include Javascript Code

Once you have the basic HTML form ready, include Cashfree’s javascript library in your webpage.
Use this js SDK available below to send payment details to Cashfree to make the payment.

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

Initialise Configuration

To track payments against the orders, use an identifier for the orders orderID. Customers make payments against these order IDs. As these payments get processed by Cashfree, you need to send us the orderId and the corresponding orderAmount. We will send you the payment status against each order.

You need to send us a few more details to process the payment. Details required are available in the request parameters here.

There are two ways to use Seamless Basic integration in your website:

  1. Redirect mode
  2. Popup mode

Redirect Mode

In this mode, your customers will be redirected to a different page to enter the two-factor authentication details and will be redirected to the webpage (return URL) you have specified in the order request on completing the payment.

Click here to view the code.

Popup Mode

In this mode, your customers will enter the two-factor authentication details on the same page and will be redirected to the same page on completing the payment.

Click here to view the code.

📘

Required javascript methods are added to the code which you will need while accepting payments for both methods.

Request Parameters

You must send us the below JSON data parameters for us to process your request. Ensure to send us all the required fields mentioned below to process the 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 Currencies Supported for a list of available currencies.

Contact [email protected] 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. Should be a valid email iD, and cannot be from blocked email IDs.

data.notifyUrl

No

Notification URL for server-server communication. Useful when user’s connection drops during redirection. 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. Click here for more information.

Generate Signature

Every request to Cashfree must contain authentication information to establish the identity of the user making the request. We use a digital signature to validate each transaction. A digital signature helps us to verify the originator of the message and also ensure the integrity of the signed data against tampering.

The signature is generated as the HMAC value of the data being passed which uses SHA256 hash function in combination with your API secret key.

We will generate a signature at our end and want you to do the same with the posted data and match it with the passed argument.

You can find your App Id and Secret key in the merchant dashboard here.

📘

Signature generation varies across integration methods, ensure you are using the right signature generation method.

<?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 = [email protected]
   $customerPhone = 99000XXXXX;
   $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);
     }
  }
}

Accept Payment

You can start accepting payments from your customers by using the CashFree.paySeamless(data, callback) javascript method.

Parameter

Description

data

A simple JS Object containing all the data related to the transaction. All possible parameters are listed here.

paymentCallback

(Optional) A callback method of the form paymentCallback(event). This is not required for the 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. Below 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

Payment Parameters

Cards

These parameters are available only for Card Payments.

Parameter

Required

Description

data.card.number

Yes

Card Number. Sixteen digits only. No spaces or Hyphens.

data.card.expiryMonth

Yes

Expiration Month for the Card. In MM format.

data.card.expiryYear

Yes

Expiration Year for the Card. In YYYY format.

data.card.cvv

Yes

CVV number of the 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 net banking.

Parameter

Required

Decription

data.nb.code

Yes

Bank code. 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

Decription

data.upi.vpa

Yes

UPI VPA for triggering UPI payment

data.paymentOption

Yes

'upi' for UPI.

Paypal

Parameter

Required

Description

data.paymentOption

Yes

'paypal' for PayPal.

Webhook Notification

Webhooks are events that notify you about the payment. A notification is sent to your backend from Cashfree when payments are successful. These notifications are useful in cases when the internet connection is unstable or slow while the payment is being processed. This will allow you to reconcile all the successful orders at your end. Notifications will be sent to notifyUrl which is a part of the request parameter specified while creating an order request.

📘

  • Notifications are sent only for successful payments.
    • Sometimes you may receive the same notification more than once. It is recommended to ensure that your implementation of the webhook is idempotent.

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. Example, 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, USER_DROPPED.

paymentMode

Payment mode used by customers to make the payment. Example, DEBIT_CARD, MobiKwik, PREPAID_CARD, etc.

txMsg

Message related to the transaction.

txTime

Time of the transaction

signature

Response signature, refer here. It is recommended to verify the signature at your end.

Response Verification

Similar to every request checksum, we also send a digital signature in our response message. We strongly recommend you to verify this response signature at your end. This will ensure the response has not tampered.

<?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 the Integration

After the integration is complete, you can test the flow of the transaction before you start accepting payments online. Click here to know how to view/generate API keys.

You can make a test transaction using the test card and net banking details available below. You can verify the payment status using the PG Dashboard, APIs, or webhooks. After completing the test, you can start accepting payments from your customers in real-time.

Card Details

Card Number

Expiry

CVV

Name

4444 3333 2222 1111

07/23

123

Test

4111 1111 1111 1111

07/23

123

Test

Net Banking Details

Bank

Payment Code

Test Bank

3333

Test Signature

Generate a signature and verify it using the checksum tool available here.

If you see the message, Failed to verify merchant credentials, check and correct the details you provided in the checksum tool.

Hello!

We have news to share. We have decided to close down our old integration methods. We suggest you head over to the new APIs to complete your integration.

Read more here.

Updated 4 days ago


Seamless Basic


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.