Preauth API

Cashfree payment gateway now supports Pre Auth on credit/debit card transactions. Card brands supported are Mastercard and Visa card type only. Pre Auth flow allows you to authorize any amount of funds from your customer’s card and capture these funds (or any part of it) at a later time. This is different from typical credit/debit card transactions where the capture of funds happens immediately after a transaction is authorized.
Cashfree PG also allows you to void authorization or any transactions that haven’t been captured yet. This will deauthorize all the fund or the transaction and credit it back to the customer’s card immediately. Both void and capture can also be done manually on the merchant dashboard.
Note:
To help you identify if a transaction has been processed through pre-auth, Cashfree explicitly marks the txMsg parameter as "PRE_AUTH|....". You will need to check in the code if the txMsg starts with the following string "PRE_AUTH".
You can initiate a capture, void call only once per transaction. It should be done within 7 days from the date of the transaction.
Captured transactions cannot be made void or vice versa.
Any amount blocked for transactions that are not captured within the 7 day period will be sent back to the customer.
Amount blocked for transactions will be sent back to the customer account immediately when you mark transactions as void.
You can capture a full payment only and not a partial payment. The captured amount will be settled during the next settlement cycle.
Capture API
This endpoint allows you to capture a transaction. 
Request Configuration
Type
Value
HTTP Method
POST
URL
/api/v1/order/capture
Content-Type
application/x-www-form-urlencoded
Post Parameters
Parameter
Description
appId
Your app Id
secretKey
Your secret key
referenceId
The referenceId of the successful transaction that needs to be captured(Integer)
idemKey
A unique Id generated by the caller to ensure single invocation of the capture API(Alphanumeric)
captureAmount
The amount that needs to be captured. If this field is not included the full amount or the transaction will be captured (Decimal) (Optional)
Sample Request and Response
Request
Curl
PHP
Java
Go
Python
C#
Curl
curl -XPOST -H 'Content-Type: application/x-www-form-urlencoded'
-d
'appId=MTA2OTkyMDE1ODE0NDIyNTExNjYjIz&secretKey=63ca0b83c8ca85d73f
ff9c3fd29a7c87e292fd63&referenceId=3890&idemKey=3890sdfas&c
aptureAmount=1' 'https://test.cashfree.com/api/v1/order/capture'
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://test.cashfree.com/api/v1/order/capture',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjIz",
    "referenceId": "3890",
    "idemKey": "3890sdfas",
    "captureAmount": "1",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
      .addFormDataPart("appId", "MTA2OTkyMDE1ODE0NDIyNTExNjYjIz")
      .addFormDataPart("secretKey", "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63")
      .addFormDataPart("referenceId", "3890")
      .addFormDataPart("idemKey", "3890sdfas")
      .addFormDataPart("captureAmount", "1")
      .build();
Request request = new Request.Builder()
  .url("https://test.cashfree.com/api/v1/order/capture")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();
Go
package main
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
func main() {
  url := "https://test.cashfree.com/api/v1/order/capture"
  method := "POST"
  payload := strings.NewReader(`{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjIz",
    "referenceId": "3890",
    "idemKey": "3890sdfas",
    "captureAmount": "1",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63"
}`)
  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)
  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
Python
import http.client
conn = http.client.HTTPSConnection("test.cashfree.com")
payload = "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjIz\",\n    \"referenceId\": \"3890\",\n    \"idemKey\": \"3890sdfas\",\n    \"captureAmount\": \"1\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\"\n}"
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/api/v1/order/capture", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
C#
var client = new RestClient("https://test.cashfree.com/api/v1/order/capture");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjIz\",\n    \"referenceId\": \"3890\",\n    \"idemKey\": \"3890sdfas\",\n    \"captureAmount\": \"1\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\"\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response
Capture Success
Capture Failed
Capture Success
{
 “status”:”OK”,
 “capturedAmount”:1,
 "captureStatus": "SUCCESS"
 “authId”:1,
 “message”:”Capture Success ul”
}
Capture Failed
{
 “status”:”ERROR”,
 “message”:”Already Captured Transaction”
}
Successful Response Description
capturedAmount is the fund captured by this request
captureStatus will either be SUCCESS or PENDING depending on whether the capture is pending or is confirmed
authId is a unique id generated by Cashfree for this request
Void Authorization API
This endpoint allows you to void authorization or an uncaptured transaction.
Request Configuration
Type
Value
HTTP Method
POST
URL
/api/v1/order/void
Content-Type
application/x-www-form-urlencoded
Post Parameters
Parameter
Description
appId
Your app Id
secretKey
Your secret key
referenceId
The referenceId of the successful transaction that needs to be captured (Integer)
idemKey
A unique Id generated by the caller to ensure single invocation of the capture API (Alphanumeric)
Sample Request and Response
Request
Curl
PHP
Java
Go
Python
C#
Curl
curl -XPOST -H 'Content-Type: application/x-www-form-urlencoded'
-d
'appId=MTA2OTkyMDE1ODE0NDIyNTExNjYjI&secretKey=63ca0b83c8ca85d73ff
f9c3fd29a7c87e292fd63&referenceId=3892&idempotencyKey=3892asdf'
'https://test.cashfree.com/api/v1/order/void'
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://test.cashfree.com/api/v1/order/void',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjI",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63",
    "referenceId": "3890",
    "idemKey": "3890sdfas"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
​
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
      .addFormDataPart("appId", "MTA2OTkyMDE1ODE0NDIyNTExNjYjIz")
      .addFormDataPart("secretKey", "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63")
      .addFormDataPart("referenceId", "3892")
      .addFormDataPart("idemKey", "3890sdfas")
      .build();
​
Request request = new Request.Builder()
  .url("https://test.cashfree.com/api/v1/order/void")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();
Go
package main
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
func main() {
  url := "https://test.cashfree.com/api/v1/order/void"
  method := "POST"
  payload := strings.NewReader(`{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjI",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63",
    "referenceId": "3890",
    "idemKey": "3890sdfas"
}`)
  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)
​
  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()
​
  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
Python
import http.client
conn = http.client.HTTPSConnection("test.cashfree.com")
payload = "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjI\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\",\n    \"referenceId\": \"3890\",\n    \"idemKey\": \"3890sdfas\"\n}"
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/api/v1/order/void", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
C#
var client = new RestClient("https://test.cashfree.com/api/v1/order/void");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjI\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\",\n    \"referenceId\": \"3890\",\n    \"idemKey\": \"3890sdfas\"\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response
Void Success
Void Failed
Void Success
{
“status”:”OK”,
 “authId”: 72,
 “message”:”Void Successful”,
 "voidStatus": "SUCCESS"
}
Void Failed
{
 “status”:”ERROR”,
 “message”:”Can only void successful transaction”
}
Successful Response Description
authId is a unique id generated by Cashfree for this request.
Capture Status API
This endpoint allows you to get the capture status for any order.
Request Configuration
Type
Value
HTTP Method
POST
URL
/api/v1/captureStatus
Content-Type
application/x-www-form-urlencoded
Post Params
Parameter
Description
appId
Your app Id
secretKey
Your secret key
referenceId
The referenceId of the successful transaction that needs to be captured (Integer)
Sample Request and Response
Request
Curl
PHP
Java
Go
Python
C#
Curl
curl -XPOST -H 'Content-Type: application/x-www-form-urlencoded'
-d
'appId=MTA2OTkyMDE1ODE0NDIyNTExNjYjI&secretKey=63ca0b83c8ca85d73ff
f9c3fd29a7c87e292fd63&referenceId=123''https://test.cashfree.com/api/v
1/captureStatus'
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://test.cashfree.com/api/v1/captureStatus',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjI",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63",
    "referenceId": "123",
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
      .addFormDataPart("appId", "MTA2OTkyMDE1ODE0NDIyNTExNjYjIz")
      .addFormDataPart("secretKey", "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63")
      .addFormDataPart("referenceId", "123")
      .build();
Request request = new Request.Builder()
  .url("https://test.cashfree.com/api/v1/captureStatus")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();
Go
package main
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
func main() {
  url := "https://test.cashfree.com/api/v1/captureStatus"
  method := "POST"
  payload := strings.NewReader(`{
    "appId": "MTA2OTkyMDE1ODE0NDIyNTExNjYjI",
    "secretKey": "63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63",
    "referenceId": "123",
}`)
  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)
  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
​
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
Python
import http.client
conn = http.client.HTTPSConnection("test.cashfree.com")
payload = "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjI\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\",\n    \"referenceId\": \"123\",\n}"
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/api/v1/captureStatus", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
C#
var client = new RestClient("https://test.cashfree.com/api/v1/captureStatus");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "{\n    \"appId\": \"MTA2OTkyMDE1ODE0NDIyNTExNjYjI\",\n    \"secretKey\": \"63ca0b83c8ca85d73fff9c3fd29a7c87e292fd63\",\n    \"referenceId\": \"123\",\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response
Success
Fail
Success
{
    "status":"OK",
    "message":"Capture Status",
    "captureType":"CAPTURE",
    "captureStatus": "SUCCESS"
}
Fail
{
    “status”:”ERROR”,
    “message”:”Transaction does not exist”
}
Successful Response Description
All possible values for captureType and captureStatus are:
CaptureType
CaptureStatus
Description
CAPTURE
SUCCESS
Transaction has been successfully captured
CAPTURE
PENDING
Capture has been attempted but pending
CAPTURE
FAILED
Capture failed
VOID
SUCCESS
Transaction has been successfully marked void
VOID
PENDING
Void is pending
VOID
FAILED
Void failed
NONE
UNCAPTURED
Capture/Void not initiated
Payment Gateway API
Card Vault API
Last updated 3 days ago
Type	Value
HTTP Method	POST
URL	/api/v1/order/capture
Content-Type	application/x-www-form-urlencoded
Parameter	Description
appId	Your app Id
secretKey	Your secret key
referenceId	The referenceId of the successful transaction that needs to be captured(Integer)
idemKey	A unique Id generated by the caller to ensure single invocation of the capture API(Alphanumeric)
captureAmount	The amount that needs to be captured. If this field is not included the full amount or the transaction will be captured (Decimal) (Optional)
CaptureType	CaptureStatus	Description
CAPTURE	SUCCESS	Transaction has been successfully captured
CAPTURE	PENDING	Capture has been attempted but pending
CAPTURE	FAILED	Capture failed
VOID	SUCCESS	Transaction has been successfully marked void
VOID	PENDING	Void is pending
VOID	FAILED	Void failed
NONE	UNCAPTURED	Capture/Void not initiated