Getting Started

Get started easily with Cashfree Payout API by downloading the following collection and importing it in Postman.


  Download Postman Collection

CashFree requires Authentication bearer token to access the API endpoints. You will have to call /payout/v1/authorize endpoint with your client Id and client Secret(can be generated from smart payout dashboard) to get this bearer token.

Endpoints

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

Authenticate

To authenticate 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.Also, 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 Smart Payout
  2. Go to Access Control -> IP Whitelist
  3. Enter IPv4 address from where you are making API requests and submit

Request

Method URL
POST /payout/v1/authorize

Request Parameters

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

You can obtain the Client Id and the Secret key from the merchant dashboard. Go to Payout > Access Control > API Keys to get your client id and the secret key.

The keys for TEST and PROD will be different.

You can access the TEST keys from the TEST dashboard and the PROD keys from the PROD dashboard.

Response

Status Response
200 {"status":"SUCCESS", "message":"Token generated", "subCode":"200", "data": {"token":"eyJ0eXA...fWStg"}}
401 {"status":"ERROR","message":"Invalid clientId and clientSecret combination","subCode":"401"}

Verify Token

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

Verify Token Request

Method URL
POST /payout/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"}

Add Beneficiary

Add a beneficiary to your CashFree account by providing bank account number, ifsc and other required details. You can only request a transfer if account has been successfully added as a beneficiary already.

Note : If we find out that bank account details are not correct (customer name does not match / ifsc not matching), beneficiary status will be automatically be changed to INVALID. You can add beneficiaries to a group while creating them although this is optional. To create beneficiary groups, use /payout/v1/createGroup

Add Beneficiary Request

Method URL
POST /payout/v1/addBeneficiary

Add Beneficiary Request Parameters

Type Params Values
HEAD Authorization String
POST beneId alphanum and underscore allowed (50 character limit)
POST group [optional] alphanum and underscore allowed (25 character limit)
POST name only alphabets and white space (100 character limit)
POST email string in email Id format (Ex: johndoe_1@cashfree.com) (200 character limit)
POST phone phone number registered in India (only digits)
POST bankAccount [optional] alphanum (40 character limit)
POST ifsc [optional] alphanum (should be in standard IFSC format)
POST vpa [optional] alphanum, period (.), at sign (@) and underscore (_) allowed (100 character limit)
POST address1 all characters allowed ( but script tags, html tags, etc.. will be sanitized or removed) (150 character limit)
POST address2 [optional] all characters allowed (but script tags, html tags, etc.. will be sanitized or removed) (150 character limit)
POST city [optional] only alphabets and white space (50 character limit)
POST state [optional] only alphabets and white space (50 character limit)
POST pincode [optional] number (6 digits)

Add Beneficiary Response

Status Response
200 Request body (Authorization Bearer token in header)
{"beneId": "JOHN18011", "name": "john doe","email": "johndoe@cashfree.com", "phone": "9876543210", "bankAccount": "00001111222233", "ifsc": "HDFC0000001", "address1" : "ABC Street", "city": "Bangalore", "state":"Karnataka", "pincode": "560001"}

Response
{"status":"SUCCESS","subCode":"200","message":"Beneficiary added successfully"}
409 Request body (Authorization Bearer token in header)
{"beneId": "JOHN18011", "name": "john doe","email":"johndoe@cashfree.com", "phone": "9876543210","bankAccount": "00001111222233", "ifsc": "HDFC0000001","address1" : "ABC Street", "city": "Bangalore","state":"Karnataka", "pincode": "560001"}

Response
{"status":"ERROR","subCode":"409","message":"Beneficiary Id already exists"}
412 Request body (Authorization Bearer token in header)
<EMPTY>

Response
{"status":"ERROR","subCode":"412","message":"Post data is empty or not a valid JSON"}
422 Request body (Authorization Bearer token in header)
{} (empty json)

Response
{"status":"ERROR","subCode":"422","message":"Please provide a valid Beneficiary Id."}

Create Beneficiary Group

Create groups to manage huge number of beneficiaries in a better way.

Create Beneficiary Request

Method URL
POST /payout/v1/createGroup

Create Beneficiary Request Parameters

Type Params Values
HEAD Authorization String
POST group alphanum and underscore allowed (25 character limit)
POST description [optional] all characters allowed ( but script tags, html tags, etc.. will be sanitized/removed) (50 character limit)

Create Beneficiary Response

Status Response
200 Request body (Authorization Bearer token in header)
{"group" : "SALES", "description": "Sales department group"}

Response
{"status":"SUCCESS","subCode":"200","message":"Beneficiary group added successfully"}
409 Request body (Authorization Bearer token in header)
{"group" : "SALES", "description": "Sales department group"}

Response
{"status":"ERROR","subCode":"409","message":"Beneficiary group already exists"}
412 Request body (Authorization Bearer token in header)
<EMPTY>

Response
{"status":"ERROR","subCode":"412","message":"Post data is empty or not a valid JSON"}
422 Request body (Authorization Bearer token in header)
{"group" : "MARKETING#1", "description": "Marketing department group 1"}

Response
{"status":"ERROR","subCode":"422","message":"Please provide a valid Group name."}

List Beneficiaries

Get list of all beneficiaries added to your account along with their activation status and 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.

List Beneficiaries Request

Method URL
GET /payout/v1/getBeneficiaries

List Beneficiaries Request Parameters

Type Params Values
HEAD Authorization String
GET maxReturn [optional] number ( >=1 and <= 50)
GET lastReturnId [optional] alphanum

List Beneficiaries Response

Status Response
200 {"status":"SUCCESS", "subCode":"200", "message":"List of beneficiaries", "data": {"beneficiaries":[{"beneId":"EMPLOYEE_183", "name":"John", "groupName":"DEFAULT", "email":"johndoe@cashfree.com", "phone":"9611634836", "bankAccount":"1234567890", "ifsc":"HDFC0000077", "status":"VERIFIED", "addedOn":"2017­01­0222:09:26"}], "lastReturnId":62}}
403 {"status":"ERROR","subCode":"403","message":"Token is not valid"}

Get Beneficiary Details

Get details of a particular beneficiary.

Get Beneficiary Request

Method URL
GET /payout/v1/getBeneficiary/<beneId>

beneId is the unique identifier for your beneficiary provided when the he/she was added to your Cashfree account.

Get Beneficiary Request Parameters

Type Params Values
HEAD Authorization String

Get Beneficiary Response

Status Response
200 {"status":"SUCCESS", "subCode":"200", "message":"Details of beneficiary", "data": {"beneId":"EMP_2", "name":"John","groupName":"DEFAULT", "email":"john@ymail.com", "phone":"9611634836", "address1":"ABCavenue", "address2":"", "city":"Bangalore", "state":"Karnataka", "pincode":"0", "bankAccount":"0009876544911", "ifsc":"HDFC000007", "status":"VERIFIED"}}
404 {"status":"ERROR","subCode":"404","message":"Beneficiary does not exist"}

Get Beneficiary Status

Beneficiary Status Description
VERIFIED Beneficiary verified and added successfully
PENDING (For future use) Add beneficiary request received, but requires internal or external action for completing the verification
INVALID Beneficiary was added successfully. But when a transfer was attempted, bank denied the transaction due to invalid account details (customer name doesn’t match with bank record / incorrect ifsc). Beneficiary status will be changed to INVALID in this case.

Fetch Beneficiary Id

Retrieve beneficiary Id of an already added beneficiary from bank account number and ifsc.

Fetch Beneficiaries Request

Method URL
GET /payout/v1/getBeneId

Fetch Beneficiaries Request Parameters

Type Params Values
HEAD Authorization String
GET bankAccount alphanum ( >=6 and <= 40 characters)
GET ifsc alphanum (standard IFSC format)

Fetch Beneficiaries Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "beneId retrieved successfully", "data": { "beneId": "USER_1901"}}
403 {"status": "ERROR", "subCode": "404", "message": "Beneficiary not found with given bank account details"}

Remove Beneficiary

Remove a beneficiary from the list of beneficiaries already added.

Remove Beneficiary Request

Method URL
POST /payout/v1/removeBeneficiary

Remove Beneficiary Request Parameters

Type Params Values
HEAD Authorization String
POST beneId alphanum and underscore allowed (50 character limit)

Remove Beneficiary Request/Response

Status Response
200 Request body (Authorization Bearer token in header) {"beneId" : "JOHN18011"}
Response { "status":"SUCCESS", "subCode":"200", "message":"Beneficiary removed"}
412 Request body (Authorization Bearer token in header) {}
Response {"status":"ERROR", "subCode":"412", "message":"beneId missing in the request"}
404 Request body (Authorization Bearer token in header) {"beneId" : "JOHN18011"}
Response {"status":"ERROR", "subCode":"404", "message":"Beneficiary doesnot exist with given Id"}

Get Balance

Get ledger balance and available balane of your account. Available balance is ledger balance minus sum of all pending transfers (Transfers triggered and being processed or pending now).

Get Balance Request

Method URL
GET /payout/v1/getBalance

Get Balance Request Parameters

Type Params Values
HEAD Authorization String

Get Balance Request/Response

Status Response
200 {"status":"SUCCESS", "subCode":"200", "message":"Ledger balance for the account", "data": {"balance":"214735.50", "availableBalance":"173980.50"}}
403 {"status":"ERROR","subCode":"403","message":"Token is not valid"}

Request Transfer

Request an amount transfer at CashFree. This API gives responses other than SUCCESS and ERROR. Please see table after request/reponse section for possible statuses. Also, do note that transfer status query API has different transfer statuses in the response(like FAILED, REVERSED,..)

Request Transfer Request

Method URL
POST /payout/v1/requestTransfer

Request Transfer Request Parameters

Type Params Values
HEAD Authorization String
POST beneId alphanum and underscore allowed (50 character limit)
POST amount decimal (>= 1.00)
POST transferId alphanum and underscore allowed (40 character limit)
POST transferMode [optional] banktransfer by default. Allowed values are banktransfer, upi and paytm.
POST remarks [optional] alphanum and white space (70 character limit)

Request Transfer Response

Status Response
200 Request body (Authorization Bearer token in header)
{"beneId" : "JOHN18011", "amount": "100.00", "transferId": "DEC2016"}

Response
{"status":"SUCCESS", "subCode":"200", "message":"Transfer completed successfully", "data": {"referenceId":"10023","utr":"P16111765023806","acknowledged": 1}}
404 Request body (Authorization Bearer token in header)
{"beneId" : "JOHN18012", "amount": "100.00", "transferId": "DEC2016"}

Response
{"status":"ERROR","subCode":"404","message":"Beneficiary doesnot exist"}
422 Request body (Authorization Bearer token in header)
{"beneId" : "JOHN18011", "amount": "100.00", "transferId": "JAN2017", "remarks": "Salary for Jan. 2017"}

Response
{"status":"ERROR","subCode":"422", "message":"Remarks can have only numbers,alphabets and whitespaces"}

Request Transfer Status

Beneficiary Status Description
SUCCESS Transfer completed successfully. acknowledged flag in the response tells whether beneficiary bank has provided acknowledgement of the transfer request
ERROR There was an error while requesting the transfer. See subStatus code received for more details on why it failed. Ex: Wrong IFSC code.
PENDING Request being processed. Query transfer status (/getTransferStatus) after sometime to see whether request was successful/failed.

Get Transfer Status

Get details of a particular transfer. You can either pass referenceId or transferId to fetch the details.

Get Transfer Request

Method URL
GET /payout/v1/getTransferStatus

Get Transfer Request Parameters

Type Params Values
HEAD Authorization String
GET referenceId alphanum
GET transferId alphanum, underscore

Get Transfer Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "Details of transfer with transferId 159381033b123", "data": {"transfer": { "referenceId": 17073, "bankAccount": "026291800001191", "beneId": "ABCD_123", "amount": "20.00", "status": "SUCCESS", "utr": "1387420170430008800069857", "addedOn": "2017­-01­-07 20:09:59", "processedOn": "2017­-01­-07 20:10:05", "acknowledged": 1 }}}
404 {"status":"ERROR","subCode":"404","message":"referenceId is invalid or doesnot exist"}

In the below table, PENDING is a temporary status. Query transfer request after sometime (usually gets updated in 20 mins) to see whether it was successful or failed. Alternatively, you can configure webhook (details below).

Get Transfer Status

Beneficiary Status Description
SUCCESS Transfer completed successfully
FAILED Transfer attempt failed
PENDING Request being processed
REVERSED Transfer rejected by beneficiary bank. Payout balance will be credited back with the amount charged. Note : You will not receive this when you are attempting a transfer, but might see this when querying for transfer status (after couple of hours). Please configure Webhook endpoint (discussed later) to be notified in such cases.

List Transfers

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.

List Transfers Request

Method URL
GET /payout/v1/getTransfers

List Transfers Request Parameters

Type Params Values
HEAD Authorization String
GET maxReturn [optional] number ( >0 and <=50 ) [Default is 50]
GET lastReturnId [optional] number (>0) [Default is 0]

List Transfers Response

Status Response
200 {"status":"SUCCESS", "subCode":"200", "message":"List of transfers","data":{"transfers": [{"referenceId":471, "transferId":"32115", "amount":"101.00"," beneId":62, "bankAccount":"1234567890", "status":"FAILED", "processedOn":"2017­01­02 23:14:04"}], "lastReturnId":471}}
422 {"status":"ERROR", "subCode":"422", "message":"Invalid maxReturn value passed"}

Bank Details Validation

This operation can be used to verify a bank account and ifsc code combination.The operation will return a success response in two cases:
1) The bank account or ifsc code or both are invalid
2) The bank account and ifsc combination are verified

Please use the test account details provided here for integration. You will receive customer name at the bank in the response for valid accounts.

Bank Details Validation Request

Method URL
GET /payout/v1/validation/bankDetails

Bank Details Validation Request Parameters

Type Params Values
HEAD Authorization String
GET name only alphabets and white space (100 character limit)
GET phone phone number registered in India (10 digits)
GET bankAccount alphanum (40 character limit)
GET ifsc alphanum (standard IFSC format)

Bank Details Validation Response

Status Response
200 { "status": "SUCCESS", "subCode": "200", "message": "Amount Deposited Successfully", "data": { "nameAtBank": "John Barnes Smith", "accountExists": "YES", "amountDeposited": "1.28", "refId": "5a7da061af50584d5992b2" } }
200 { "status": "SUCCESS", "subCode": "200", "message": "Invalid ifsc provided", "data": { "accountExists": "NO" } }
422 { "status": "ERROR", "subCode": "422", "message": "Please provide a valid IFSC code" }

Cashgram

These operations can be used to create cashgram , get Cashgram status and deactivate Cashgram. See Cashgram redeemed, Cashgram expired in the Webhook section for more details on how to handle Webhook.

Add Cashgram Request

Method URL
POST /payout/v1/createCashgram

Add Cashgram Request Paramters

Type Params Values
HEAD Authorization String
POST cashgramId alphanum and underscore allowed (50 character limit)
POST amount decimal (>= 1.00)
POST name only alphabets and white space (100 character limit)
POST email [optional] string in email Id format (Ex: johndoe_1@cashfree.com) (200 character limit)
POST phone phone number registered in India (only digits)
POST linkExpiry Date format yyyy/MM/DD ,maximum 7 days gap from the date of creation
POST remarks [optional] alphanum and white space (70 character limit)
POST notifyCustomer [optional] boolean 1 or 0

Add Cashgram Response

Status Response
200 Request body (Authorization Bearer token in header)
{"cashgramId": "JOHaN10","amount": "1" , "name": "john doe","email": "johndoe@cashfree.com", "phone": "9876543210","linkExpiry" : "2018/09/12" ,"remarks" :"api","notifyCustomer" : 1 }

Response
{"status": "SUCCESS","subCode": "200", "message": "Cashgram Created", "data": { "referenceId": 3645 , "cashgramLink": "http://bit.ly/2xxnGm8" } }
409 Response
{ "status": "ERROR", "subCode": "409", "message": "Cashgram with id JOHaN10 already exists" }
422 Response
{ "status": "ERROR", "subCode": "422", "message": "Remarks can have only numbers,alphabets and whitespaces" }

Cashgram Status Request

Method URL
GET /payout/v1/getCashgramStatus

Cashgram Status Request Paramters

Type Params Values
HEAD Authorization String
GET cashgramId alphanum and underscore allowed (50 character limit)

Cashgram Status Response

Status Response
200 Response
{"status": "SUCCESS", "subCode": "200","data": { "cashGramStatus": "EXPIRED" } }
404 Response
{ "status": "ERROR", "subCode": "404", "message": "Cashgram with id JOHaN10 does not exists" }

Deactivate Cashgram Request

Method URL
POST /payout/v1/deactivateCashgram

Deactivate Cashgram Request Paramters

Type Params Values
HEAD Authorization String
POST cashgramId alphanum and underscore allowed (50 character limit)

Deactivate Cashgram Response

Status Response
200 Request body (Authorization Bearer token in header)
{"cashgramId": "JOHaN10" }

Response
{ "status": "SUCCESS", "subCode": "200", "message": "Cashgram with id - JOHaN10 successfully deactivated!" }
412 Response
{ "status": "ERROR", "subCode": "412", "message": "Cashgram with id - JOHaN10 has already been Expired" }
404 Response
{ "status": "ERROR", "subCode": "404", "message": "Cashgram with id JOHaN10 does not exists" }

BatchTransfer Api

These operations can be used to request batchTransfers and get batchTransfers status.

Request BatchTransfer

Method URL
POST /payout/v1/requestBatchTransfer

Add BulkTransfer Request Paramters

Type Params Values
HEAD Authorization String
POST batchTransferId alphanum and underscore allowed (60 character limit)
POST batchFormat alphanum and underscore allowed (50 character limit)
POST beneId alphanum and underscore allowed (50 character limit)
POST amount decimal (>= 1.00)
POST transferId alphanum and underscore allowed (40 character limit)
POST remarks[optional] alphanum and white space (70 character limit)
POST name only alphabets and white space (100 character limit)
POST email string in email Id format (Ex: johndoe_1@cashfree.com) (200 character limit)
POST phone phone number registered in India (only digits)
POST bankAccount alphanum (40 character limit)
POST ifsc alphanum (should be in standard IFSC format)

Add BulkTransfer Response

Status Response
200 Request body For Bank Account(Authorization Bearer token in header)
{"batchTransferId" : "Test_Bank_Account_Format_45","batchFormat": "BANK_ACCOUNT" , "batch" : [{"transferId" : "PTM_00121241112", "amount" : "12","phone" : "9999999999", "bankAccount" : "9999999999" , "ifsc" : "PYTM0_000001","email" : "bahrat@gocashfree.com", "name": "bharat"},{"transferId" : "PTM_00052312126", "amount" : "12","phone" : "9999999999", "bankAccount" : "9999999999" , "ifsc" : "PYTM0000001","email" : "bahrat@gocashfree.com", "name": "bharat" },{"transferId" : "PTM_0001321215", "amount" : "12","phone" : "9999999999", "bankAccount" : "9999999999" , "ifsc" : "PYTM0000001","email" : "bahrat@gocashfree.com", "name": "bharat"}]}

Response
{ "status": SUCCESS, "subCode": "200", "message": "Request accepted", "data": { "referenceId": 1594 }}
200 Request body for Beneficiary(Authorization Bearer token in header)
{"batchTransferId" : "Test_Beneficiary_Format_45","batchFormat":"BENEFICIARY_ID", "batch" : [{"transferId" : "PTM_00121241112", "amount" : "12","beneId" : "b01" , "remarks" : "working"}]}

Response
{ "status": "SUCCESS", "subCode": "200", "message": "Batch Transfer requested successfully. Please check later for processing status.", "data": { "referenceId": 1594 }}
409 Response
{"status": "ERROR", "subCode": "409", "message": "Batch TransferId already exists"}
422 Response
{ "status": "ERROR", "subCode": "422", "message": "Parameters missing in request" }

GET Batch Transfer Status Request

Method URL
GET /payout/v1/getBatchTransferStatus

GET Batch Transfer Status Request Paramters

Type Params Values
HEAD Authorization String
GET batchTransferId alphanum and underscore allowed (60 character limit)

Batch Transfer Status Response

Status Response
200 Response
{"status" : "SUCCESS","subCode": "200", "message": "Data retrieved successfully", "data":{ "rowCount" : 3, "referenceId" : 1582, "transfers": [{"beneId":"9999999999_18875", "transferId":"PTM_00121241112", "referenceId":1523969542, "bankAccount":"9999999999", "ifsc":"PYTM0000001", "amount":"12.00", "remarks":"", "status":"SUCCESS", "utr":"W1532082925", "addedOn":"2018-07-20", "processedOn":"2018-07-20" },{ "beneId":"9999999999_18875", "transferId":"PTM_00052312126", "referenceId":1523969543, "bankAccount":"9999999999"," ifsc":"PYTM0000001", "amount":"12.00", "remarks":"", "status":"SUCCESS", "utr":"W1532082926", "addedOn":"2018-07-20", "processedOn":"2018-07-20"},{"transferId":"PTM_0001321215", "failureReason":"PLEASE PROVIDE A VALID EMAIL."}]}}
200 Response
{ "status": "SUCCESS", ,"subCode": "200", "message": "Data retrieved successfully", "data": { "referenceId": 1579, "rowCount": 3, "transfers": [{ "transferId":"PTM_00121241112", "failureReason":"PLEASE PROVIDE A VALID EMAIL."},{"transferId":"PTM_00052312126", "failureReason":"PLEASE PROVIDE A VALID EMAIL."},{"transferId":"PTM_0001321215", "failureReason":"PLEASE PROVIDE A VALID EMAIL."}]}}
404 Response
{ "status": "ERROR", "subCode": "404", "message": "Batch Transfer Id does not exist" }

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. For instance, if you have already received a success response for transfer request API call. Discard TRANSFER_SUCCESS event for the corresponding transferId.
  3. Below is the list of events for which we will be notifying on your Webhook and list of parameters being sent. Please note that there might be new events added in the future.

TRANSFER_SUCCESS

Transfer attempt successful at the bank and account debited.

Parameters

  • event
  • transferId
  • referenceId
  • eventTime
  • utr
  • signature

TRANSFER_FAILED

Transfer attempt failed.

Parameters

  • event
  • transferId
  • reason
  • referenceId
  • signature

TRANSFER_REVERSED

Transfer reversed by the beneficiary bank.

Parameters

  • event
  • transferId
  • reason
  • referenceId
  • signature

INVALID_BENEFICIARY_ACCOUNT

Beneficiary account was found to be invalid (account could be blocked, closed or inactive) during the transfer attempt.

Parameters

  • event
  • beneId
  • transferId
  • name
  • bankAccount
  • ifsc
  • signature

LOW_BALANCE_ALERT

CashFree Payout account balance below low balance alert

Parameters

  • event
  • currentBalance
  • alertTime
  • signature

CASHGRAM_REDEEMED

Cashgram Redeemed by the customer.

Parameters

  • event
  • cashgramId
  • referenceId
  • eventTime
  • utr
  • signature

CASHGRAM_TRANSFER_REVERSAL

Cashgram Transfer reversed by the bank .(This rarely happens)

Parameters

  • event
  • cashgramId
  • referenceId
  • eventTime
  • signature

CASHGRAM_EXPIRED

Cashgram will become inactive because of the following reasons. An inactive Cashgram cannot be re-activated. You will have to create a new Cashgram to send to your customer.

  1. Redeeming post Expiry time - If the customer does not redeem the Cashgram before the expiration time set by the Merchant, the Cashgram will be automatically deactivated.
  2. Reaching maximum number of retries - We only allow customers to payout to his account a maximum of three times. If the customer enters incorrect details more than three times, the Cashgram will be automatically deactivated.
  3. OTP verification attempts exceeded - We only allow customers to verify OTP three times. If the customer reaches that limit without once successfully validating the OTP, the Cashgram link will expire.

Parameters

  • event
  • cashgramId
  • signature

Verify Signature

Verifying the signature (passed along with the POST parameters) is mandatory before processing any response. We also recommend whitelisting only our IP address at your webhook endpoint.Follow the steps below to compute 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.
  6. Proceed further if it matches, else discard the request.

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

RUBY CODE

require 'openssl'
require 'base64'
  hash = OpenSSL::HMAC.digest('sha256', clientSecret, data)
  computedSignature = Base64.strict_encode64(hash)

Glossary

  1. All the responses are in JSON format.
  2. All the POST requests should have content type as below : Content­Type: application/json
  3. All the responses have status, subCode, message and data (incase any data is returned from Server).
  4. data – All the data in the response will be part of the “data”.
  5. subCode - status sub code of response.
  6. Pagination - In case API response is a list (ex: list of transfers, beneficiaries list ), we do not return more than 50 items in a request. API call is paginated, so pass lastReturnId received as part of the first response to fetch more items.You can continue doing this till you do not receive lastReturnId in the response. This means that you have retrieved all the items.
  7. For integration, use only test accounts provided below for triggering transfer requests. All other requests will throw an error.
  8. All request parameters are mandatory unless explicitly marked as [optional].

Status Sub Codes

All sub codes are standard HTTP status codes. The below ones are used in this API.

200 - Success
4XX - Error occurred in client’s part
5XX - Error occurred in server’s part

Status Sub Code Description
200 OK
201 OK . But to be processed a later point of time
400 Bad request
401 Authentication failure
403 Forbidden
404 Entity does not exist
405 Method Not Allowed
409 Resource conflict (already exists)
412 Precondition Failed
413 Request Entity Too Large
422 Input not in expected format
429 Too many requests
500 Internal Server Error
503 Service Unavailable
520 Unknown Error Occured

Test Account Details

For bank transfer :

Account Number IFSC code Remarks
026291800001191 YESB0000262 Success
00011020001772 HDFC0000001 Success
000890289871772 SCBL0036078 Success
000100289877623 SBIN0008752 Success
2640101002729 CNRR0002640 Failure – Invaid IFSC code
026291800001190 YESB0000262 Failure – Invaid Account number
007711000031 HDFC0000077 Pending
00224412311300 YESB0000001 Pending (later to Success)
7766666351000 YESB0000001 Pending (later to Failure)

For wallets :

Phone Number Remarks
9999999999 PayTm successful wallet transfer

For UPI :

VPA Remarks
success@upi Successful UPI transfer
failure@upi Failed UPI transfer