Below are the steps you must be aware of while calling Cashgram APIs:
All API responses are in JSON format.
POST Requests should include ContentType: application/json
All API response has status, subCode, message, and data.
Subcode is the status subcode of the response-All requests to Cashfree that are processed by the server return HTTP 200
. Use the status flag to determine if the request was successfully processed. Check the error subcodes here.
It is strongly recommended to scan error sub-code and not error messages.
Get started quickly with Cashfree payouts APIs by downloading the following collection and importing it in Postman.
Use the following host URLs based on your specific environment.
Environment | Host URL |
Test | |
Prod |
Calling the Authentication APIs allows you to get and verify bearer tokens returned by Cashfree. Cashfree require these 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 from a different IP.
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 find out how to whitelist your IP or if you have a dynamic IP, take a look here.
<token>
' (without quotes) for them to get processed.{"status":"SUCCESS","message":"Token generated","subCode":"200","data": {"token":"eyJ0eXA...fWStg","expiry":1564130052}}
{"status":"ERROR","message":"Invalid clientId and clientSecret combination","subCode":"401"}
curl -X POST \'http://{{Host%20Url}}/payout/v1/authorize' \-H 'X-Client-Id: {{client id}}' \-H 'X-Client-Secret: {{client secret}}' \
Cashfree libraries store the token internally and have their internal verification logic. This API does not apply to them.
/payout/v1/authorize
for this){"status":"SUCCESS","message":"Token is valid","subCode":"200"}
{"status":"ERROR","subCode":"403","message":"Token is not valid"}
curl -X POST \'http://{{Host%20Url}}/payout/v1/verifyToken' \-H 'Authorization: Bearer {{Token}}' \
Create, deactivate, and get the status of a cashgram.
const cfSdk = require('cashfree-sdk');const {Cashgram} = cfSdk.Payouts;
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.cashgram import Cashgram
import com.cashfree.lib.clients.Payouts;import com.cashfree.lib.clients.Cashgram;import com.cashfree.lib.domains.CashgramDetails//Cashgram cashgram = new Cashgram(payouts);
Request body (Authorization Bearer token in header){"cashgramId": "JOHaN10","amount": "1" ,"name": "John Doe","email": "johndoe@cashfree.com","phone": "9876543210","linkExpiry" : "2020/04/01" ,"remarks" :"sample cashgram","notifyCustomer" : 1 }Response{"status": "SUCCESS","subCode": "200","message": "Cashgram Created","data": {"referenceId": 123456,"cashgramLink": "http://csgr.am/abcdefg"}}
{ "status": "ERROR","subCode": "409","message": "Cashgram with id JOHaN10 already exists" }
{ "status": "ERROR","subCode": "422","message": "Remarks can have only numbers,alphabets and whitespaces"}
Status | Sub Code | Message |
SUCCESS | 200 | Cashgram Created |
ERROR | 403 | Token is not valid |
ERROR | 403 | IP not whitelisted |
ERROR | 412 | Token missing in the request |
ERROR | 412 | Available balance is less than requested cashgram amount. |
ERROR | 520 | Unknown error occurred. Please try again. |
const cfSdk = require('cashfree-sdk');const {Cashgram} = cfSdk.Payouts;const response = await Cashgram.CreateCashgram({cashgramId: "JOHaN10",amount: "1.00",name: "John Doe",email: "johndoe@cashfree.com",phone: "9876543210",linkExpiry: "2020/04/01",remarks: "sample cashgram",notifyCustomer: 1});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.cashgram import Cashgramc = Cashgram.create_cashgram(cashgramId="JOHaN10", amount="1.1", name="john doe", email="johndoe@cashfree.com", phone="9876543210",linkExpiry="2020/04/01", remarks="sample cashgram", notifyCustomer=1)
import com.cashfree.lib.clients.Payouts;import com.cashfree.lib.clients.Cashgram;import com.cashfree.lib.domains.CashgramDetailsPayouts payouts = Payouts.getInstance(Environment.PRODUCTION, "<client_id>", "<client_secret>");payouts.init();Cashgram cashgram = new Cashgram(payouts);CashgramDetails cashgramDetails = new CashgramDetails().setCashgramId("JOHaN10").setAmount(new BigDecimal("1.00")).setName("John Doe").setEmail("johndoe@cashfree.com").setPhone("9876543210").setLinkExpiry(LocalDateTime.now().plusMinutes(0)).setRemarks("sample cashgram").setNotifyCustomer(1);cashgram.createCashgram(cashgramDetails);}
curl -X POST \'http://{{Host%20Url}}/payout/v1/createCashgram' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer {{Token}}'-d '{"cashgramId": "JOHaN10","amount": "1.00","name": "John Doe","email": "johndoe@cashfree.com","phone": "9876543210","linkExpiry": "2020/04/01","remarks": "sample cashgram","notifyCustomer": 1}'
{"status": "SUCCESS","subCode": "200","message": "Cashgram details retrieved","data": {"cashgramStatus": "ACTIVE","referenceId": 123456,"cashgramId": "JOHaN10","cashgramLink": "http://csgr.am/abcdefg"}}{"status": "SUCCESS","subCode": "200","message": "Cashgram details retrieved","data": {"cashgramStatus": "PENDING","referenceId": 123456,"cashgramId": "JOHaN10","cashgramLink": "http://csgr.am/abcdefg","redeemRefId": 123456789}}{"status": "SUCCESS","subCode": "200","message": "Cashgram details retrieved","data": {"cashgramStatus": "REDEEMED","referenceId": 123456,"cashgramId": "JOHaN10","cashgramLink": "http://csgr.am/abcdefg","redeemRefId": 123456789}}{"status": "SUCCESS","subCode": "200","message": "Cashgram details retrieved","data": {"cashgramStatus": "EXPIRED","reason": "EXCEEDED_EXPIRY_DATE","referenceId": 123456,"cashgramId": "JOHaN10","cashgramLink": "http://csgr.am/abcdefg"}}
{ "status": "ERROR","subCode": "404","message": "Cashgram with id JOHaN10 does not exists" }
Status | Sub Code | Message |
SUCCESS | 200 | Cashgram details retrieved |
ERROR | 403 | Token is not valid |
ERROR | 403 | IP not whitelisted |
ERROR | 412 | Token missing in the request |
ERROR | 404 | Cashgram with id does not exist |
ERROR | 422 | Please provide a valid cashgram Id |
ERROR | 520 | Unknown error occurred |
const cfSdk = require('cashfree-sdk');const {Cashgram} = cfSdk.Payouts;const response = await Cashgram.GetCashgramStatus({cashgramId: "JOHaN10"});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.cashgram import Cashgramstatus = Cashgram.get_cashgram_status(cashgramId="JOHaN10")
import com.cashfree.lib.clients.Payouts;import com.cashfree.lib.clients.Cashgram;import com.cashfree.lib.domains.CashgramDetailsPayouts payouts = Payouts.getInstance(Environment.PRODUCTION, "<client_id>", "<client_secret>");payouts.init();Cashgram cashgram = new Cashgram(payouts);cashgram.getCashgramStatus("JOHaN10");}
curl -X GET \'http://{{Host%20Url}}/payout/v1/getCashgramStatus?cashgramId=JOHaN10' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer {{Token}}'
{ "status": "SUCCESS","subCode": "200","message": "Cashgram with id - JOHaN10 successfully deactivated!" }
{ "status": "ERROR","subCode": "404","message": "Cashgram with id JOHaN10 does not exists" }
{ "status": "ERROR","subCode": "412","message": "Cashgram with id - JOHaN10 has already been Expired" }
Status | Sub Code | Message |
SUCCESS | 200 | Cashgram with id <cashgramId> successfully deactivated! |
ERROR | 403 | Token is not valid |
ERROR | 403 | IP not whitelisted |
ERROR | 412 | Token missing in the request |
ERROR | 412 | Active cashgrams can only be deactivated |
ERROR | 404 | Active cashgrams id <cashgramId> can only be deactivated |
ERROR | 422 | Please provide a valid cashgram Id |
ERROR | 520 |
const cfSdk = require('cashfree-sdk');const {Cashgram} = cfSdk.Payouts;const response = await Cashgram.DeactivateCashgram({cashgramId: "JOHaN10"});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.cashgram import Cashgramstatus = Cashgram.deactivate_cashgram(cashgramId="JOHaN10")
import com.cashfree.lib.clients.Payouts;import com.cashfree.lib.clients.Cashgram;import com.cashfree.lib.domains.CashgramDetailsPayouts payouts = Payouts.getInstance(Environment.PRODUCTION, "<client_id>", "<client_secret>");payouts.init();Cashgram cashgram = new Cashgram(payouts);cashgram.deactivateCashgram("JOHaN10");}
curl -X GET \'http://{{Host%20Url}}/payout/v1/deactivateCashgram?cashgramId=JOHaN10' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer {{Token}}'