Cashgram API

Learn more about Cashgram API.
Guidelines
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.
Postman collection
Get started quickly with Cashfree payouts APIs by downloading the following collection and importing it in Postman.
Cashfree Payouts Collection.json
Cashfree Payouts.postman_collection.json - 16KB
Host URL
Use the following host URLs based on your specific environment.
Environment
Host URL
Test
​https://payout-gamma.cashfree.com​
Prod
​https://payout-api.cashfree.com​
Authentication
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.
post
Authorize
/payout/v1/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.
Request
Response
Request
Headers
X-Cf-Signature
optional
string
Signature to be sent if IP is not whitelisted
X-Client-Secret
required
string
ClientSecret
X-Client-Id
required
string
ClientId
Response
200: OK
	{"status":"SUCCESS", 
	"message":"Token generated", 
	"subCode":"200", 
	"data": {"token":"eyJ0eXA...fWStg", 
	"expiry":1564130052}}
401: Unauthorized
{"status":"ERROR",
"message":"Invalid clientId and clientSecret combination",
"subCode":"401"}
Curl
Curl
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.
post
Verify token
/payout/v1/verifyToken
Verify the bearer token generated. If the token does not exist, is invalid, or has expired, the response "Token is not valid" is returned. Regenerate token incase of token expiry for making API calls ( use /payout/v1/authorize for this)
Request
Response
Request
Headers
Authorization
required
string
Bearer token to be verified
Response
200: OK
{"status":"SUCCESS", 
"message":"Token is valid", 
"subCode":"200"}
403: Forbidden
{"status":"ERROR", 
"subCode":"403", 
"message":"Token is not valid"}
Curl
Curl
curl -X POST \
  'http://{{Host%20Url}}/payout/v1/verifyToken' \
  -H 'Authorization: Bearer {{Token}}' \
Cashgram
Create, deactivate, and get the status of a cashgram.
Node
Python
Java
Node
const cfSdk = require('cashfree-sdk');
const {Cashgram} = cfSdk.Payouts;
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.cashgram import Cashgram
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Cashgram;
import com.cashfree.lib.domains.CashgramDetails
​
//Cashgram cashgram = new Cashgram(payouts);
post
Create cashgram
/payout/v1/createCashgram
API to create a Cashgram.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
cashgramId
required
string
Unique Id of the Cashgram, alphanumeric, underscore (_), and hyphen (-) allowed (35 character limit)
amount
required
number
Amount to be transferred,
>= 1.00
name
required
string
Name of the contact  
email
optional
string
Email of the contact
phone
required
string
Phone number of contact
linkExpiry
required
string
Date to expire the cashgram link, Date format YYYY/MM/DD, maximum 30 days from the date of creation
remarks
optional
string
Remarks, if any.
notifyCustomer
optional
boolean
If value is 1, a link is sent to customers phone and email
Response
200: OK
Request body (Authorization Bearer token in header)
{"cashgramId": "JOHaN10",
"amount": "1" , 
"name": "John Doe",
"email": "[email protected]", 
"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"
    }
}
​
409: Conflict
{ "status": "ERROR", 
"subCode": "409", 
"message": "Cashgram with id JOHaN10 already exists" }
422: Unprocessable Entity
{ "status": "ERROR", 
"subCode": "422", 
"message": "Remarks can have only numbers,alphabets and whitespaces"}
Response Codes
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.
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Cashgram} = cfSdk.Payouts;
​
const response = await Cashgram.CreateCashgram({
            cashgramId: "JOHaN10",
            amount: "1.00",
            name: "John Doe",
            email: "[email protected]",
            phone: "9876543210",
            linkExpiry: "2020/04/01",
            remarks: "sample cashgram",
            notifyCustomer: 1
        });
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.cashgram import Cashgram
​
c = Cashgram.create_cashgram(cashgramId="JOHaN10", amount="1.1", name="john doe", email="[email protected]", phone="9876543210", 
linkExpiry="2020/04/01", remarks="sample cashgram", notifyCustomer=1)  
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Cashgram;
import com.cashfree.lib.domains.CashgramDetails
​
Payouts 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("[email protected]")
        .setPhone("9876543210")
        .setLinkExpiry(LocalDateTime.now().plusMinutes(0))
        .setRemarks("sample cashgram")
        .setNotifyCustomer(1);
cashgram.createCashgram(cashgramDetails);
​
}
Curl
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": "[email protected]",
            "phone": "9876543210",
            "linkExpiry": "2020/04/01",
            "remarks": "sample cashgram",
            "notifyCustomer": 1
}'
get
Get cashgram status
/payout/v1/getCashgramStatus
Get the status of the Cashgram created.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
cashgramId
required
string
Id of the cashgram
Response
200: OK
{
    "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"
    }
}
422: Unprocessable Entity
{ "status": "ERROR", 
"subCode": "404", 
"message": "Cashgram with id JOHaN10 does not exists" }
Response Codes
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
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Cashgram} = cfSdk.Payouts;
​
const response = await Cashgram.GetCashgramStatus({
            cashgramId: "JOHaN10"
        });
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.cashgram import Cashgram
​
status = Cashgram.get_cashgram_status(cashgramId="JOHaN10")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Cashgram;
import com.cashfree.lib.domains.CashgramDetails
​
Payouts payouts = Payouts.getInstance(
    Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Cashgram cashgram = new Cashgram(payouts);
cashgram.getCashgramStatus("JOHaN10");
}
Curl
curl -X GET \
  'http://{{Host%20Url}}/payout/v1/getCashgramStatus?cashgramId=JOHaN10' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{Token}}'
post
Deactivate cashgram
/payout/v1/deactivateCashgram
Request to deactivate an active Cashgram.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Form Data Parameters
cashgramId
required
string
Id of the cashgram to be deactivated, alphanumeric and underscore (_) allowed (35 character limit)
Response
200: OK
{ "status": "SUCCESS", 
"subCode": "200", 
"message": "Cashgram with id - JOHaN10 successfully deactivated!" }
404: Not Found
{ "status": "ERROR", 
"subCode": "404", 
"message": "Cashgram with id JOHaN10 does not exists" }
412: Precondition Failed
{ "status": "ERROR", 
"subCode": "412", 
"message": "Cashgram with id - JOHaN10 has already been Expired" }
Response Codes
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
Unknown error occurred
​
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Cashgram} = cfSdk.Payouts;
​
const response = await Cashgram.DeactivateCashgram({
            cashgramId: "JOHaN10"
        });
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.cashgram import Cashgram
​
status = Cashgram.deactivate_cashgram(cashgramId="JOHaN10")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Cashgram;
import com.cashfree.lib.domains.CashgramDetails
​
Payouts payouts = Payouts.getInstance(
    Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Cashgram cashgram = new Cashgram(payouts);
cashgram.deactivateCashgram("JOHaN10");
}
Curl
curl -X GET \
  'http://{{Host%20Url}}/payout/v1/deactivateCashgram?cashgramId=JOHaN10' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{Token}}'
Payouts API
Bank Account Verification API
Last updated 3 weeks ago
Environment	Host URL
Test	https://payout-gamma.cashfree.com
Prod	https://payout-api.cashfree.com
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.
Cashgram API

Guidelines

Postman collection

Host URL

Authentication

postAuthorize

postVerify token

Cashgram

postCreate cashgram

Response Codes

getGet cashgram status

Response Codes

postDeactivate cashgram

Response Codes

post
Authorize

post
Verify token

post
Create cashgram

get
Get cashgram status

post
Deactivate cashgram
