Getting Started

CashFree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to retreive your AppId and SecretKey (API keys).

Endpoints

URL Environment
https://cac-gamma.cashfree.com TEST
https://cac-api.cashfree.com PRODUCTION

Authenticate

Authenticate the user with the Cashfree system and obtain the Authorization Bearer token. All other API calls must have this token as Authorization header in the format ‘Bearer <token>’ (without quotes) for them to be processed.

Caution : Do not store the token in an insecure manner. Regenerating new token does not invalidate the already generated token.But we do have a check where token generated from one IP address cannot be used from a different IP.

In case you are getting an ‘IP not whitelisted’ error, do the following:

  1. Login to merchant dashboard, select Auto Collect
  2. Go to Access Control -> IP Whitelist
  3. Enter Ipv4 address from where you are making API requests and submit

Request

Method URL
POST /cac/v1/authorize

Request Parameters

Type Params Values
HEAD X-Client-Id string
HEAD X-Client-Secret string

Response

Status Response
200 { "status":"SUCCESS", "message":"Token generated", "subCode":"200", "data":{ "token": "4k9JCN4M....H2xyPBe", "expiry":1497637144 } }
401 {"status":"ERROR","message":"Invalid clientId and clientSecret combination","subCode":"401"}

Verify Token

Verify the authentication token generated. Response will be ‘Token is not valid’ if token doesnot exist,invalid or has expired. Regenerate token incase of token expiry for making API calls ( use /cac/v1/authorize for this)

Verify Token Request

Method URL
POST /cac/v1/verifyToken

Verify Token Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Verify Token Response

Status Response
200 {"status":"SUCCESS","message":"Token is valid","subCode":"200"}
403 {"status":"ERROR","subCode":"403","message":"Token is not valid"}

Create Virtual Account

This operation allows you to create a virtual account.

Create Virtual Account Request

Method URL
POST /cac/v1/createVA

Create Virtual Account Request Parameters

Type Params Values
HEAD Authorization String
POST vAccountId¹ String. Alphanumeric. CAPS only. Length between 4 and 8. This is the primary identifier of your virtual account and will be later used to recover details related to your account. Resulting bank account number would be: <your_account_prefix><vAccountId> Ex: CASHFREE1234<vAccountId>
POST virtualVpaId² String. Alphanumeric. Length between 3 and 20. This is the primary identifier of your virtual UPI and will be later used to recover details related to your account. Resulting UPI would be: <CASHME><your_account_prefix><vpa> Ex: CASHME1234<vpa>
POST name* String. Alphanumeric and spaces. You can associate a name with this account. For instance, name of the vendor who will be transferring money to this account (60 character limit)
POST phone* Number (Valid phone number format)
POST email* String (Ex:johndoe_1@cashfree.com ) (50 character limit)
POST notifGroup Alphanumeric. This is the name of the notification group for this virtual account. Has to be an existing virtual account group that is listed in the notifications section of the dashboard(50 character limit)
POST remitterAccount Alphanumeric. When this optional parameter is passed, transfer can be done to the virtual account only from this particular bank account. Transfers from any other bank account will be rejected.
POST remitterIfsc Alphanumeric. Mandatory whenremitterAccount parameter is passed. This will be IFSC code of remitterAccountbeing passed.

From the above parameters, either vAccountId¹ or virtualVpaId² is mandatory to create virtual bank account or VPA respectively. Providing both would result in a error.

Create Virtual Account Response

Status Response
200 Request {"vAccountId":"VATEST", "name":"TestVendor", "phone":"9900111111", "email":"test@gmail.com", "notifGroup":"TestGroup"}
Response{ "status":"SUCCESS", "subCode":"200", "message":"Virtual account added successfully", "data": { "accountNumber": "CASHFREE1234VATEST","ifsc": "YESB0CMSNOC" } }
200 Request {"virtualVpaId":"john", "name":"John Doe", "phone":"9900111111", "email":"test@gmail.com", "notifGroup":"TestGroup"}
Response{ "status":"SUCCESS", "subCode":"200", "message":"Virtual account added successfully", "data": { "vpa": "cashme1234john@yesbankltd" } }
200 Request {"vAccountId":"VATEST1", "name":"TestVendor", "phone":"9900111111", "email":"test@gmail.com", "remitterAccount":"007711300000000762", "remitterIfsc":"YESB0000001"}
Response{ "status":"SUCCESS", "subCode":"200", "message":"Virtual account added successfully", "data": { "accountNumber": "CASHFREE1234VATEST1","ifsc": "YESB0CMSNOC" } }
412 Request {"vAccountId":"VATEST1", "virtualVpaId":"john", "name":"TestVendor", "phone":"9900111111", "email":"test@gmail.com" }
Response{ "status": "ERROR", "subCode": "409", "message": "Please provide either Virtual Account or VPA" }

Edit Virtual Account

To edit details of a Virtual Account.

Edit Virtual Account Request

Method URL
POST /cac/v1/editVA

Edit Virtual Account Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
POST vAccountId String. Alphanumeric (already added virtual account)
POST remitterAccount String. Alphanumeric ( <=40 and >=6 characters)
POST remitterIfsc Standard IFSC format
POST name String. Alphanumeric and spaces. You can associate a name with this account. For instance, name of the vendor who will be transferring money to this account (60 character limit)
POST email String (Ex:johndoe_1@cashfree.com ) (50 character limit)
POST phone Number (Valid phone number format)

Edit Virtual Account Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "Virtual account details updated"}
403 {"status": "SUCCESS", "subCode": "403", "message": "Virtual account is not active"}
422 {"status": "SUCCESS", "subCode": "422", "message": "Please pass a valid remitter Ifsc"}

Change Virtual Account Status

To change virtual account status.

Change Virtual Account Status Request

Method URL
POST /cac/v1/changeVAStatus

Change Virtual Account Status Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "Vitual account status updated succesfully"}
403 {"status": "SUCCESS", "subCode": "403", "message": "Virtual account not found with given id"}
422 {"status": "SUCCESS", "subCode": "422", "message": "Please provide a valid status"}

Recent Payments

Get all the recent payments on all of your virtual accounts.

Recent Payments Request

Method URL
POST /cac/v1/payments

Recent Payments Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
GET startDate [optional] Date in YYYYMMDD. Search beginning from this date.
GET endDate [optional] Date in YYYYMMDD. Search till this date. Has to be greater than startDate.
GET maxReturn [optional] Number (200 >= maxReturn > 0). For pagination support. Details the maximum number of records that should be returned from this query
GET lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL with GET query params: /cac/v1/payments?startDate=20170804&endDate=20170823&maxReturn=20&lastReturnId=37

Recent Payments Response

Status Response
200 "status": "SUCCESS", "subCode": "200", "message": "List of Payments", "data": { "payments": [{"vAccountId": "DEMO2", "amount": "56.00", "referenceId": 2125, "utr": "2014", "creditRefNo": "1243", "remitterAccount": "001130007628", "remitterName": "JANE", "paymentTime": "2007-07-06 15:14:06"}, {"vAccountId": "DEM01", "amount": "700.00", "referenceId": 2540, "utr": "2004", "creditRefNo": "12656242", "remitterAccount": "00130007628", "remitterName": "JOHNDOE", "paymentTime": "2007-06-24 17:50:51"}], "lastReturnId": 2120123 }

Fetch Rejected Payment Details

Get details regarding a rejected payment using rejectId.

Fetch Rejected Payment Details Request

Method URL
GET /cac/v1/rejectedPayment/<rejectId>

Fetch Rejected Payment Details Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Example URL with GET query params: /cac/v1/rejectedPayment/6234

Fetch Rejected Payment Details Response

Status Response
200 { "status": "SUCCESS", "subCode": "200", "message": "Details retrieved for rejected transfer", "data": { "payment": { "vAccountId": "RCHK0001", "amount": "200.00", "utr": "9034", "remitterAccount": "771130007627", "reason": "REMITTER_NOT_ALLOWED", "transferTime": "2017-11-24 15:39:29" } } }
404 { "status":"ERROR", "subCode":"404", "message":"No transfers found with given rejectId" }

Recent Payments for Virtual Account Id

Get all the recent payments on your virtual account by passing corresponding virtual account id (vAccountId)

Recent Payments for Virtual Account Id Request

Method URL
GET /cac/v1/payments/<vAccountId>

Recent Payments for Virtual Account Id Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
GET startDate [optional] Date in YYYYMMDD. Search beginning from this date.
GET endDate [optional] Date in YYYYMMDD. Search till this date. Has to be greater than startDate.
GET maxReturn [optional] Number (200 >= maxReturn > 0). For pagination support. Details the maximum number of records that should be returned from this query.
GET lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL with GET query params: /cac/v1/payments/TEST1?startDate=20170804&endDate=20170823&maxReturn=20&lastReturnId=37

Recent Payments for Virtual Account Id Response

Status Response
200 { "status": "SUCCESS", "subCode": "200", "message": "List of Virtual account payments received", "data": { "payments": [{ "referenceId": 269233, "amount": "1200.00", "utr": "207384909", "creditRefNo": "1438354982", "remitterAccount": "0030007628", "remitterName": JOHNDOE, "paymentTime": "2007-06-28 15:29:26" }, { "referenceId": 293352, "amount": "700.00", "utr": "209263608", "creditRefNo": "2382053846", "remitterAccount": "0030007628", "remitterName": JOHNDOE, "paymentTime": "2007-06-28 15:28:08" }], "lastReturnId": 21232 } }
404 { "status":"ERROR", "subCode":"404", "message":"Virtual account not found" }

List All Virtual Accounts

Get a list of all the virtual accounts associated with your AutoCollect account

List All Virtual Accounts Request

Method URL
GET /cac/v1/allVA

List All Virtual Accounts Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
GET maxReturn [optional] Number (200 >= maxReturn > 0). For pagination support. Details the maximum number of records that should be returned from this query
GET lastReturnId [optional] Number. For pagination support. Every query response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL with GET query params: /cac/v1/allVA?maxReturn=20&lastReturnId=1498208149

List All Virtual Accounts Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "List of virtual accounts", "data": { "vAccounts": [{ "vAccountId": "TEST", "virtualAccountNumber": "CASHFREEABCDTEST", "name": "Test Corp", "ifsc": "YESB0CMSNOC", "phone": "9876543210", "email": "cf_janedoe@gmail.com", "remitterAccount": "", "remitterIfsc": "0", "status": "ACTIVE", "addedOn": "2007-07-25 18:42:09" }, { "vAccountId": "DEMO1", "virtualAccountNumber": "CASHFREEABCDDEMO1", "name": "Demo Corp", "ifsc": "HDFC0000077", "phone": "9999999999", "email": "johndoe@cashfree.com", "remitterAccount": "", "remitterIfsc": "0", "status": "ACTIVE", "addedOn": "2007-06-20 17:21:40" }], "lastReturnId": 7497959500 }}

Get details for Virtual Account

Get the details for your virtual account identified by its virtual account id (vAccountId)

Get details for Virtual Account Request

Method URL
GET /cac/v1/va/<vAccountId>

Get details for Virtual Account Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Example URL with GET query params: /cac/v1/allVA?maxReturn=20&lastReturnId=1498208149

Get details for Virtual Account Response

Status Response
200 {"status":"SUCCESS", "subCode":"200", "message":"Virtual Account Details", "data": {"vAccountId":"VIRTUA1", "virtualAccountNumber":"CASHFREENAFSVIRTUA1", "name": "Virtua Corp", "ifsc":"HDFC0001111", "phone":"9900111111", "email":"test@gmail.com", "remitterAccount": "", "remitterIfsc": "0", "status":"VERIFIED", "addedOn":"2017-06-15 19:01:39"}}
404 {"status":"ERROR", "subCode":"404", "message":"Virtual account not found"}

Search for a transaction by UTR

Get the details for your virtual account payment by using the UTR of the corresponding bank Transfer.

NOTE: This search is limited to last 48 hours by default. You can search a different time range using startDate and endDate query params in the GET url. However, this range can not be greater than 30 days.

Search for a transaction by UTR Request

Method URL
GET /cac/v1/searchUTR/<utr>

Search for a transaction by UTR Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
GET startDate [optional] Date in YYYYMMDD. Search beginning from this date.
GET endDate [optional] Date in YYYYMMDD. Search till this date. Has to be greater than startDate. The difference between startDate and endDate can’t be greater than 30 days.

Example URL with GET query params: /cac/v1/searchUTR/20044?startDate=20170921&endDate=20170930

Search for a transaction by UTR Response

Status Response
200 { "status": "SUCCESS", "subCode": "200", "message": "Payment with UTR found", "data": { "payment": { "vAccountId": "56", "amount": "95.00", "referenceId": 51, "utr": "20043", "creditRefNo": "20001", "remitterAccount": "11401504", "remitterName": "Akash Sinha", "paymentTime": "2017-09-21 18:32:27" }}}
404 {"status":"ERROR", "subCode":"404", "message":"No Payment found"}

Webhook

Configure Webhook

  1. Add your webhook through the merchant dashboard for the first time. Contact support@cashfree.com to edit your Webhook endpoint.
  2. Make sure that you don’t process duplicate events.
  3. Below is the list of events for which we will be notifying on your Webhook and list of parameters being sent. There might be new events added in the future.

Get details of all transfers requested along with their details. Please note that response for this API endpoint is paginated. See ‘Conventions’ in the Glossary for more details on how to handle paginated responses.

AMOUNT_COLLECTED

Money has been received in your CashFree Virtual account through auto collect.

Parameters

  • event
  • amount
  • vAccountId
  • virtualVpaId (If received to VPA)
  • isVpa (1 if VPA transfer)
  • vAccountNumber (If received to Virtual Bank Account)
  • referenceId
  • utr
  • email
  • phone
  • creditRefNo
  • remitterAccount
  • remitterName
  • paymentTime

TRANSFER_REJECTED

Transfer request was received, but has been rejected due to some reason (mentioned in the field reason)

Parameters

  • event
  • amount
  • vAccountId
  • rejectId
  • utr
  • remitterAccount
  • transferTime
  • reason

Verify Signature

Verifying the signature (passed along with the POST parameters) is mandatory before you process any response. We also recommending whitelisting only our IP address on your webhook endpoint.Follow steps below to calculate and verify the signature passed :

  1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair
  2. Sort the array based on keys
  3. Concatenate all the values in this array and resultant is the post data (say, postData)
  4. postData needs to be encrypted using SHA-256 and then base64 encoded.
  5. Now verify if both the signature calculated and the signature received match. Proceed further if it matches.

Please note that following code snippets are merely pointers on how to generate and verify signature. This should not be assumed production ready, so kindly consider adding necessary validation before processing.

PHP CODE

<?php
 $data = $_POST;
  $signature = $_POST["signature"];
  unset($data["signature"]);
  // $data now has all the POST parameters except signature
  ksort($data);  // Sort the $data array based on keys
  $postData = "";
  
  foreach ($data as $key => $value){
    if (strlen($value) > 0) {
      $postData .= $value;
    }
  }
  $hash_hmac = hash_hmac('sha256', $postData, $clientSecret, true) ;
  // Use the clientSecret from the oldest active Key Pair.
  $computedSignature = base64_encode($hash_hmac);
  if ($signature == $computedSignature) {
    // Proceed based on $event 
  } else {
    // Reject this call 
  }
?>

JAVA CODE

import javax.crypto.spec.SecretKeySpec;
import javax.crypto.Mac;
import org.apache.commons.codec.binary.Base64;
public class ComputedSignature {
    public static String generateHMAC(String clientSecret, String data) {
        String hash = null;
        try {
            String secret = clientSecret;
            String message = data;
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(),"HmacSHA256");
            sha256_HMAC.init(secret_key);
            hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
        }
        catch (Exception e){ //Log it
        }
        return hash;
    }
}