Auto Collect API

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your App Id and Secret Key.

Sample Integration Kits

Below are the integration kits on how to use Auto Collect. The integration kits help you get started with the integration.

Node.js - https://github.com/cashfree/cashfree-autocollect-nodeā€‹

Java - https://github.com/cashfree/cashfree-autocollect-javaā€‹

Python - https://github.com/cashfree/cashfree-autocollect-pythonā€‹

PHP - https://github.com/cashfree/cashfree-autocollect-phpā€‹

Endpoints

URL

Environment

https://cac-gamma.cashfree.com

TEST

https://cac-api.cashfree.com

PRODUCTION

Postman Collection

Get started quickly with Cashfree's Auto Collect APIs by downloading the following collection and importing it in Postman.

Authentication

Calling the Authentication APIs allows you to get and verify bearer tokens returned by Cashfree. Cashfree requires this token for all further communication.

  • Cashfree libraries automatically call the Authorize API and internally store the token.

  • Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used at a different IP address.

  • Token generated is valid for 300 seconds. Please ensure that you recall the authorize API once the token has expired.

  • Ensure your IP is whitelisted. To whitelist your IP or if you have a dynamic IP, click here for more details.

<Post> Authorize

To authenticate with the Cashfree system and obtain the authorization bearer token, call the authorize API. All other API calls must have this token as Authorization header in the format 'Bearer <token>' (without quotes) for them to get processed.

/cac/v1/authorize

Request Parameters

Type

Params

Values

HEAD

X-Client-Id

String

HEAD

X-Client-Secret

String

Request and Response Sample Code

Status

Request and Response

200

Request

curl --location --request POST 'https://{Host URL}/cac/v1/authorize' --header 'X-Client-ID: client_id' --header 'X-Client-Secret: client_secret' Response

{

"status":"SUCCESS",

"message":"Token generated", "subCode":"200",

"data":{ "token": "4k9JCN4M....H2xyPBe", "expiry":1497637144 }

}

401

{

"status":"ERROR",

"message":"Invalid clientId and clientSecret combination",

"subCode":"401"

}

<Post> Verify Token

Verify the authentication token generated. The response will be ā€˜Token is not validā€™ if the token does not exist, invalid or has expired. Regenerate token in case of token expiry for making API calls (use /cac/v1/authorize for this)

/cac/v1/verifyToken

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

Request and Response Sample Code

Status

Request and Response

200

Request curl --location --request POST '{Host URL}/cac/v1/verifyToken'

--header

'Authorization: Bearer {Token}' Response

{

"status":"SUCCESS",

"message":"Token is valid",

"subCode":"200"

}

403

{

"status":"ERROR",

"subCode":"403",

"message":"Token is not valid"

}

<Post> Create Virtual Account / VPA

The create virtual account API allows you to create a virtual account or a virtual UPI address.

/cac/v1/createVA

Request Parameters

Request
Request

Type

Params

Values

HEAD

Authorization

String

POST

vAccountIdĀ¹

String. Alphanumeric. CAPS only. The 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. The resulting bank account number would be: Ex: CASHFREE1234

POST

virtualVpaIdĀ²

String. Alphanumeric. The 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: Ex: CASHME1234

POST

name*

String. Alphanumeric and spaces. You can associate a name with this account. For instance, the 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 [optional]

Alphanumeric. When this optional parameter is passed, a 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 [optional]

Alphanumeric. Mandatory when remitterAccount parameter is passed. This will be the IFSC code of remitterAccount being passed.

POST

createMultiple [optional]

Boolean Integer. Assumed to be 0 by default and if 1 is passed, virtual accounts would be created with multiple banking partners.

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

For the parameter createMultiple the length of the vAccountIdĀ¹ should be less than 9. Failing to be less than 9 only the default virtual account would be created. Please contact your account manager or care@cashfree.com to enable this feature.

Request and Response Sample Code

Status

Request and Response

200

Request {

"vAccountId":"VATEST",

"name":"TestVendor",

"phone":"9900111111",

"email":"test@gmail.com",

"notifGroup":"TestGroup",

"createMultiple": 1

} Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Virtual account added successfully",

"data": {

"YESB": {

"accountNumber": "CASHFREE1234VATEST",

"ifsc": "YESB0CMSNOC"

},

"ICIC": {

"accountNumber": "PASFR1234VATEST",

"ifsc": "ICIC0000106"

}

}

}

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

{

"vAccountId":"A9876543210",

"name":"TestVendor",

"phone":"9900111111",

"email":"test@gmail.com",

"notifGroup":"TestGroup",

"createMultiple": 1} Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Virtual account added successfully",

"data": {

"YESB": {

"accountNumber": "CASHFREE1234A98765432210",

"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"

}

}

409

Request

{

"vAccountId":"VATEST",

"name":"TestVendor",

"phone":"9900111111",

"email":"test@gmail.com",

"remitterAccount":"007711300000000762",

"remitterIfsc":"YESB0000001"

} Response

{

"status": "ERROR",

"subCode": "409",

"message": "Virtual account Id already exists"

}

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"

}

<Post> Edit Virtual Account

To edit the details of a Virtual Account.

/cac/v1/editVA

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

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 allowed. 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)

Request and Response Sample Code

Status

Request and Response

200

Request

{

"vAccountId":"VATEST",

"name":"TestVendor",

"phone":"9900111111",

"email":"cashfree@cashfree.com",

"remitterAccount" : "123456789",

"remitterIfsc":"HDFC0000549"

} Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Virtual account details updated"

}

403

Request

{

"vAccountId":"VATEST1",

"name":"TestVendor",

"phone":"9876543210",

"email":"test@cashfree.com"

} Response

{

"status": "SUCCESS",

"subCode": "403",

"message": "Virtual account is not active"

}

422

Request

{

"vAccountId":"VATEST1",

"name":"TestVendor",

"phone":"9876543210",

"email":"test@cashfree.com",

"remitterAccount" : "123456789",

"remitterIfsc":"ABC012434"

} Response

{

"status": "SUCCESS",

"subCode": "422",

"message": "Please pass a valid remitter Ifsc"

}

<Get> Create QR code

This API allows you to create a QR code for your existing Cashfree Virtual VPA.

/cac/v1/createQRCode

Request Parameters

Type

Params

Values

HEAD

Authorization

String

GET

virtualVPA

String

GET

virtualVpaId

String

From the above parameters, either virtualVPA or virtualVpaId is mandatory to create the QR code. Providing both would result in an error.

Example URL with GET query params:

/cac/v1/createQRCode?virtualVPA=cashmetest@yesbankltd

Request and Response Sample Code

Status

Request and Response

200

Request

curl -X GET \'https://cac-api.cashfree.com/cac/v1/createQRCode?virtualVPA=cashme1234john@icici' -H 'Authorization: Bearer XXXX' Response

{ "status": "SUCCESS", "subCode": "200", "message": "QR Code generated succesfully", "qrCode": "data:image/png;base64,iVEā€¦.UI=)", "virtualVPA": "cashmetest@yesbankltd"

}

400

Response

{

"status": "ERROR", "subCode": "400", "message": "VPA does not exist for the account provided"

}

<Get> Create Dynamic QR code

This API allows you to create a QR code for your existing Cashfree Virtual VPA fixed with an amount. This amount cannot be changed after creation. This will force the user to pay a predefined amount defined through the API.

/cac/v1/createDynamicQRCode

Request Parameters

Type

Params

Values

HEAD

Authorization

String

GET

virtualVPA

String

GET

virtualVpaId

String

GET

amount

Decimal ( >=1.0 ) INR by default

From the above parameters, either virtualVPA or virtualVpaId is mandatory to create the QR code. Providing both would result in a error.

Amount is a mandatory parameter.

Example URL with GET query params:

/cac/v1/createDynamicQRCode?virtualVPA=cashmetest@yesbankltd&amount=50

Request and Response Sample Code

Status

Request and Response

200

Request

curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/createDynamicQRCode?virtualVpaId=john&amount=50' \ -H 'Authorization: Bearer XXXX' Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Dynamic QR Code generated succesfully",

"qrCode":"data:image/png;base64,iVEā€¦.UI=)",

"virtualVPA": "cashmetest@yesbankltd"

}

400

Response

{

"status": "ERROR", "subCode": "400", "message": "VPA does not exist for the account provided"

}

<Post> Change Virtual Account Status

This API allows you to change virtual account status from ACTIVE to INACTIVE and vice-versa.

Type

Params

Values

HEAD

Authorization

String

POST

vAccountId

String

POST

status

String, it will be active or inactive

/cac/v1/changeVAStatus

Request and Response Sample Code

Status

Request and Response

200

Request

{

"vAccountId":"cashfreetest",

"status":"INACTIVE"

} Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Vitual account status updated succesfully"

}

403

Request

{

"vAccountId":"abcd123",

"status":"ACTIVE"

} Response

{

"status": "SUCCESS",

"subCode": "403",

"message": "Virtual account not found with given id"

}

422

Request

{

"vAccountId":"cashfreetest",

"status":"ACTIVATE"

} Response

{

"status": "SUCCESS",

"subCode": "422",

"message": "Please provide a valid status"

}

<Get> Recent Payments

Use this API to get all the recent payments on all of your virtual accounts.

/cac/v1/payments

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

GET

startDate [optional]

Date in YYYYMMDD or YYYY-MM-DD HH:MM:SS. Search beginning from this date.

GET

endDate [optional]

Date in YYYYMMDD or YYYY-MM-DD HH:MM:SS. 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
ā€‹
/cac/v1/payments?startDate=2019-10-24 15:22:47&endDate=2019-10-24 15:24:47

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/payments' \ -H 'Authorization: Bearer XXXX'

Response

{

"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",

"isSettled": 1,

"settlementUtr" : "2151"

}, {

"vAccountId": "DEM01",

"amount": "700.00",

"referenceId": 2540,

"utr": "2004",

"creditRefNo": "12656242",

"remitterAccount": "00130007628",

"remitterName": "JOHNDOE",

"paymentTime": "2007-06-24 17:50:51",

"isSettled": 0}

],

"lastReturnId": 2120123

}

}

<Get> Fetch Rejected Payment Details

Use this API to get details regarding a rejected payment using rejectId.

/cac/v1/rejectedPayment/

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

Example URL with GET query params:

/cac/v1/rejectedPayment/6234

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/rejectedpayment/6234' \ -H 'Authorization: Bearer XXXX'

Response

{

"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

Response

{

"status":"ERROR",

"subCode":"404",

"message":"No transfers found with given rejectId"

}

<Get> View Settlement Details

Use this API to get all payment details made for a settlement.

/cac/v1/getSettlementDetails

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

GET

settlementUtrĀ¹

alphanumeric

GET

settlementIdĀ²

integer

From the above parameters, either settlementUtrĀ¹ or settlementIdĀ² is mandatory to retrieve Payments against a settlement. Providing both would result in an error.

Example URL with GET query params:

/cac/v1/getSettlementDetails?settlementUtr=123345
ā€‹
/cac/v1/getSettlementDetails?settlementId=456

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/getSettlementDetails?settlementUtr=123345'

\-H 'Authorization: Bearer XXXX'

ā€‹

Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Details successfully retrieved",

"data": {

"entries": [

{

"vAccountId": 41674,

"amount": "5670.00",

"incomingUTR": "1232425114",

"transactionTime": "2018-11-19 18:31:11"

},

{

"vAccountId": 41675,

"amount": "150.00",

"incomingUTR": "75950266858557",

"transactionTime": "2018-11-22 17:54:34"

},

{

"vAccountId": 41675,

"amount": "150.00",

"incomingUTR": "78210597364224",

"transactionTime": "2018-11-22 17:55:27"

},

{

"vAccountId": 41677,

"amount": "150.00",

"incomingUTR": "79916902319519",

"transactionTime": "2018-11-23 15:56:20"

},

{

"vAccountId": 41677,

"amount": "150.00",

"incomingUTR": "70886353403329",

"transactionTime": "2018-11-23 15:57:22"

},

{

"vAccountId": 41690,

"amount": "100.00",

"incomingUTR": "70879797027446",

"transactionTime": "2019-04-18 17:02:50"

}

] }

}

404

Response

{ "status":"ERROR",

"subCode":"404", "message":"Payments not found for the respective Utr or settlementId"

}

<Get> Recent Payments for Virtual Account Id/Virtual VPA Id

Use this API to get all the recent payments on your virtual account by sending corresponding virtual account ID (vAccountId) or virtual VPA id

/cac/v1/payments

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

GET

startDate [optional]

Date in YYYYMMDD or YYYY-MM-DD HH:MM:SS. Search beginning from this date.

GET

endDate [optional]

Date in YYYYMMDD or YYYY-MM-DD HH:MM:SS. 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 for vAccountId:

/cac/v1/payments/TEST1?startDate=20170804&endDate=20170823&maxReturn=20&lastReturnId=37
ā€‹
/cac/v1/payments/TEST2?startDate=2019-10-24 15:22:47&endDate=2019-10-24 15:24:47

Example URL with GET query params for virtualVPAId:

/cac/v1/payments/john?startDate=20170804&endDate=20170823&maxReturn=20&lastReturnId=37
ā€‹
/cac/v1/payments/john1?startDate=2019-10-24 15:22:47&endDate=2019-10-24 15:24:47

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/payments/cashme1234john@yesbankltd' \ -H 'Authorization: Bearer XXXX'

Response

{

"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",

"isSettled": 1, "settlementUtr" : "151214"

}],

"lastReturnId": 21232

}

}

404

Response

{

"status":"ERROR",

"subCode":"404",

"message":"Virtual account not found"

}

<Get> List All Virtual Accounts

Use this API to get a list of all the virtual accounts associated with your Auto Collect account.

/cac/v1/allVA

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

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

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/allVA?maxReturn=20&lastReturnId=1498208149' \ -H 'Authorization: Bearer XXXX'

Response

{

"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> Get details for Virtual Account or Virtual VPA

Use this API to get the details for virtual account identified by its virtual account id (vAccountId) or virtual vpa id (virtualVpaId).

/cac/v1/va/<vAccountId or virtualVPAId>

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

Example URL with GET query params for vAccountId:

/cac/v1/va/virtual

Example URL with GET query params for virtualVPAId:

/cac/v1/va/john

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/va/john' \ -H 'Authorization: Bearer XXXX'

Response

{

"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"

}

}

200

Response

{

"status": "SUCCESS",

"subCode": "200",

"message": "Virtual Account Details",

"data":

{

"vAccountId": "VIRTUA1",

"name": "Cashfree User",

"phone": "9876543210",

"email": "cashfreeuser@gmail.com",

"remitterAccount": "",

"remitterIfsc": "",

"status": "ACTIVE",

"addedOn": "2020-04-13 22:43:51",

"YESB":

{

"virtualAccountNumber": "CASHFREEABVIRTUA1",

"ifsc": "YESB0CMSNOC"},

"ICIC": {"virtualAccountNumber": "PASFRABVIRTUA1",

"ifsc": "ICIC0000106"

}

}

}

404

Response

{

"status":"ERROR",

"subCode":"404",

"message":"Virtual account not found"

}

<Get> Search for a transaction by UTR

Use this API to get the details of your virtual account payment by using the UTR of the corresponding bank Transfer.

By default, this search is limited to the last 48 hours. 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.

/cac/v1/searchUTR/<utr>

Request Parameters

Type

Params

Values

HEAD

Authorization

String (Format: Bearer)

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

Request and Response Sample Code

Status

Request and Response

200

Request curl -X GET \ 'https://cac-api.cashfree.com/cac/v1/searchUTR/02344858392' \ -H 'Authorization: Bearer XXXX'

Response

{

"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": "John Doe",

"paymentTime": "2019-09-21 18:32:27",

"isSettled": 1,

"settlementUtr" : "2132151"

}

}

}

404

Response

{

"status":"ERROR",

"subCode":"404",

"message":"No Payment found"

}