Skip to main content
POST
/
subscriptions
Create Subscription
curl --request POST \
  --url https://sandbox.cashfree.com/pg/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "subscription_id": "Demo_Subscription",
  "customer_details": {
    "customer_name": "john",
    "customer_email": "john@dummy.com",
    "customer_phone": "9908730221",
    "customer_bank_account_number": "59108290701802",
    "customer_bank_ifsc": "HDFC0002614",
    "customer_bank_code": "HDFC",
    "customer_bank_account_type": "SAVINGS"
  },
  "plan_details": {
    "plan_name": "plan12345",
    "plan_type": "PERIODIC",
    "plan_amount": 10,
    "plan_max_amount": 100,
    "plan_max_cycles": 100,
    "plan_intervals": 2,
    "plan_interval_type": "WEEK",
    "plan_note": "Bi-weekly INR 10 plan"
  },
  "authorization_details": {
    "authorization_amount": 100,
    "authorization_amount_refund": true,
    "payment_methods": [
      "enach",
      "pnach",
      "upi",
      "card"
    ]
  },
  "subscription_meta": {
    "return_url": "https://wa.me/9512440440?text=Payment%20Successfull",
    "notification_channel": [
      "EMAIL",
      "SMS"
    ],
    "session_id_expiry": "2024-01-14T23:00:08+05:30"
  },
  "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
  "subscription_first_charge_time": "2024-01-10T23:00:08+05:30",
  "subscription_tags": {
    "psp_note": "Monthly subscription payment",
    "key2": "value2"
  },
  "subscription_payment_splits": [
    {
      "vendor_id": "vendor1",
      "amount": 100,
      "percentage": 10
    },
    {
      "vendor_id": "vendor2",
      "amount": 100,
      "percentage": 10
    }
  ]
}
'
import requests

url = "https://sandbox.cashfree.com/pg/subscriptions"

payload = {
    "subscription_id": "Demo_Subscription",
    "customer_details": {
        "customer_name": "john",
        "customer_email": "john@dummy.com",
        "customer_phone": "9908730221",
        "customer_bank_account_number": "59108290701802",
        "customer_bank_ifsc": "HDFC0002614",
        "customer_bank_code": "HDFC",
        "customer_bank_account_type": "SAVINGS"
    },
    "plan_details": {
        "plan_name": "plan12345",
        "plan_type": "PERIODIC",
        "plan_amount": 10,
        "plan_max_amount": 100,
        "plan_max_cycles": 100,
        "plan_intervals": 2,
        "plan_interval_type": "WEEK",
        "plan_note": "Bi-weekly INR 10 plan"
    },
    "authorization_details": {
        "authorization_amount": 100,
        "authorization_amount_refund": True,
        "payment_methods": ["enach", "pnach", "upi", "card"]
    },
    "subscription_meta": {
        "return_url": "https://wa.me/9512440440?text=Payment%20Successfull",
        "notification_channel": ["EMAIL", "SMS"],
        "session_id_expiry": "2024-01-14T23:00:08+05:30"
    },
    "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
    "subscription_first_charge_time": "2024-01-10T23:00:08+05:30",
    "subscription_tags": {
        "psp_note": "Monthly subscription payment",
        "key2": "value2"
    },
    "subscription_payment_splits": [
        {
            "vendor_id": "vendor1",
            "amount": 100,
            "percentage": 10
        },
        {
            "vendor_id": "vendor2",
            "amount": 100,
            "percentage": 10
        }
    ]
}
headers = {
    "x-api-version": "<x-api-version>",
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'x-api-version': '<x-api-version>',
    'x-client-id': '<api-key>',
    'x-client-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscription_id: 'Demo_Subscription',
    customer_details: {
      customer_name: 'john',
      customer_email: 'john@dummy.com',
      customer_phone: '9908730221',
      customer_bank_account_number: '59108290701802',
      customer_bank_ifsc: 'HDFC0002614',
      customer_bank_code: 'HDFC',
      customer_bank_account_type: 'SAVINGS'
    },
    plan_details: {
      plan_name: 'plan12345',
      plan_type: 'PERIODIC',
      plan_amount: 10,
      plan_max_amount: 100,
      plan_max_cycles: 100,
      plan_intervals: 2,
      plan_interval_type: 'WEEK',
      plan_note: 'Bi-weekly INR 10 plan'
    },
    authorization_details: {
      authorization_amount: 100,
      authorization_amount_refund: true,
      payment_methods: ['enach', 'pnach', 'upi', 'card']
    },
    subscription_meta: {
      return_url: 'https://wa.me/9512440440?text=Payment%20Successfull',
      notification_channel: ['EMAIL', 'SMS'],
      session_id_expiry: '2024-01-14T23:00:08+05:30'
    },
    subscription_expiry_time: '2024-01-14T23:00:08+05:30',
    subscription_first_charge_time: '2024-01-10T23:00:08+05:30',
    subscription_tags: {psp_note: 'Monthly subscription payment', key2: 'value2'},
    subscription_payment_splits: [
      {vendor_id: 'vendor1', amount: 100, percentage: 10},
      {vendor_id: 'vendor2', amount: 100, percentage: 10}
    ]
  })
};

fetch('https://sandbox.cashfree.com/pg/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.cashfree.com/pg/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscription_id' => 'Demo_Subscription',
    'customer_details' => [
        'customer_name' => 'john',
        'customer_email' => 'john@dummy.com',
        'customer_phone' => '9908730221',
        'customer_bank_account_number' => '59108290701802',
        'customer_bank_ifsc' => 'HDFC0002614',
        'customer_bank_code' => 'HDFC',
        'customer_bank_account_type' => 'SAVINGS'
    ],
    'plan_details' => [
        'plan_name' => 'plan12345',
        'plan_type' => 'PERIODIC',
        'plan_amount' => 10,
        'plan_max_amount' => 100,
        'plan_max_cycles' => 100,
        'plan_intervals' => 2,
        'plan_interval_type' => 'WEEK',
        'plan_note' => 'Bi-weekly INR 10 plan'
    ],
    'authorization_details' => [
        'authorization_amount' => 100,
        'authorization_amount_refund' => true,
        'payment_methods' => [
                'enach',
                'pnach',
                'upi',
                'card'
        ]
    ],
    'subscription_meta' => [
        'return_url' => 'https://wa.me/9512440440?text=Payment%20Successfull',
        'notification_channel' => [
                'EMAIL',
                'SMS'
        ],
        'session_id_expiry' => '2024-01-14T23:00:08+05:30'
    ],
    'subscription_expiry_time' => '2024-01-14T23:00:08+05:30',
    'subscription_first_charge_time' => '2024-01-10T23:00:08+05:30',
    'subscription_tags' => [
        'psp_note' => 'Monthly subscription payment',
        'key2' => 'value2'
    ],
    'subscription_payment_splits' => [
        [
                'vendor_id' => 'vendor1',
                'amount' => 100,
                'percentage' => 10
        ],
        [
                'vendor_id' => 'vendor2',
                'amount' => 100,
                'percentage' => 10
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-version: <x-api-version>",
    "x-client-id: <api-key>",
    "x-client-secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.cashfree.com/pg/subscriptions"

	payload := strings.NewReader("{\n  \"subscription_id\": \"Demo_Subscription\",\n  \"customer_details\": {\n    \"customer_name\": \"john\",\n    \"customer_email\": \"john@dummy.com\",\n    \"customer_phone\": \"9908730221\",\n    \"customer_bank_account_number\": \"59108290701802\",\n    \"customer_bank_ifsc\": \"HDFC0002614\",\n    \"customer_bank_code\": \"HDFC\",\n    \"customer_bank_account_type\": \"SAVINGS\"\n  },\n  \"plan_details\": {\n    \"plan_name\": \"plan12345\",\n    \"plan_type\": \"PERIODIC\",\n    \"plan_amount\": 10,\n    \"plan_max_amount\": 100,\n    \"plan_max_cycles\": 100,\n    \"plan_intervals\": 2,\n    \"plan_interval_type\": \"WEEK\",\n    \"plan_note\": \"Bi-weekly INR 10 plan\"\n  },\n  \"authorization_details\": {\n    \"authorization_amount\": 100,\n    \"authorization_amount_refund\": true,\n    \"payment_methods\": [\n      \"enach\",\n      \"pnach\",\n      \"upi\",\n      \"card\"\n    ]\n  },\n  \"subscription_meta\": {\n    \"return_url\": \"https://wa.me/9512440440?text=Payment%20Successfull\",\n    \"notification_channel\": [\n      \"EMAIL\",\n      \"SMS\"\n    ],\n    \"session_id_expiry\": \"2024-01-14T23:00:08+05:30\"\n  },\n  \"subscription_expiry_time\": \"2024-01-14T23:00:08+05:30\",\n  \"subscription_first_charge_time\": \"2024-01-10T23:00:08+05:30\",\n  \"subscription_tags\": {\n    \"psp_note\": \"Monthly subscription payment\",\n    \"key2\": \"value2\"\n  },\n  \"subscription_payment_splits\": [\n    {\n      \"vendor_id\": \"vendor1\",\n      \"amount\": 100,\n      \"percentage\": 10\n    },\n    {\n      \"vendor_id\": \"vendor2\",\n      \"amount\": 100,\n      \"percentage\": 10\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-version", "<x-api-version>")
	req.Header.Add("x-client-id", "<api-key>")
	req.Header.Add("x-client-secret", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://sandbox.cashfree.com/pg/subscriptions")
  .header("x-api-version", "<x-api-version>")
  .header("x-client-id", "<api-key>")
  .header("x-client-secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_id\": \"Demo_Subscription\",\n  \"customer_details\": {\n    \"customer_name\": \"john\",\n    \"customer_email\": \"john@dummy.com\",\n    \"customer_phone\": \"9908730221\",\n    \"customer_bank_account_number\": \"59108290701802\",\n    \"customer_bank_ifsc\": \"HDFC0002614\",\n    \"customer_bank_code\": \"HDFC\",\n    \"customer_bank_account_type\": \"SAVINGS\"\n  },\n  \"plan_details\": {\n    \"plan_name\": \"plan12345\",\n    \"plan_type\": \"PERIODIC\",\n    \"plan_amount\": 10,\n    \"plan_max_amount\": 100,\n    \"plan_max_cycles\": 100,\n    \"plan_intervals\": 2,\n    \"plan_interval_type\": \"WEEK\",\n    \"plan_note\": \"Bi-weekly INR 10 plan\"\n  },\n  \"authorization_details\": {\n    \"authorization_amount\": 100,\n    \"authorization_amount_refund\": true,\n    \"payment_methods\": [\n      \"enach\",\n      \"pnach\",\n      \"upi\",\n      \"card\"\n    ]\n  },\n  \"subscription_meta\": {\n    \"return_url\": \"https://wa.me/9512440440?text=Payment%20Successfull\",\n    \"notification_channel\": [\n      \"EMAIL\",\n      \"SMS\"\n    ],\n    \"session_id_expiry\": \"2024-01-14T23:00:08+05:30\"\n  },\n  \"subscription_expiry_time\": \"2024-01-14T23:00:08+05:30\",\n  \"subscription_first_charge_time\": \"2024-01-10T23:00:08+05:30\",\n  \"subscription_tags\": {\n    \"psp_note\": \"Monthly subscription payment\",\n    \"key2\": \"value2\"\n  },\n  \"subscription_payment_splits\": [\n    {\n      \"vendor_id\": \"vendor1\",\n      \"amount\": 100,\n      \"percentage\": 10\n    },\n    {\n      \"vendor_id\": \"vendor2\",\n      \"amount\": 100,\n      \"percentage\": 10\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox.cashfree.com/pg/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-version"] = '<x-api-version>'
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_id\": \"Demo_Subscription\",\n  \"customer_details\": {\n    \"customer_name\": \"john\",\n    \"customer_email\": \"john@dummy.com\",\n    \"customer_phone\": \"9908730221\",\n    \"customer_bank_account_number\": \"59108290701802\",\n    \"customer_bank_ifsc\": \"HDFC0002614\",\n    \"customer_bank_code\": \"HDFC\",\n    \"customer_bank_account_type\": \"SAVINGS\"\n  },\n  \"plan_details\": {\n    \"plan_name\": \"plan12345\",\n    \"plan_type\": \"PERIODIC\",\n    \"plan_amount\": 10,\n    \"plan_max_amount\": 100,\n    \"plan_max_cycles\": 100,\n    \"plan_intervals\": 2,\n    \"plan_interval_type\": \"WEEK\",\n    \"plan_note\": \"Bi-weekly INR 10 plan\"\n  },\n  \"authorization_details\": {\n    \"authorization_amount\": 100,\n    \"authorization_amount_refund\": true,\n    \"payment_methods\": [\n      \"enach\",\n      \"pnach\",\n      \"upi\",\n      \"card\"\n    ]\n  },\n  \"subscription_meta\": {\n    \"return_url\": \"https://wa.me/9512440440?text=Payment%20Successfull\",\n    \"notification_channel\": [\n      \"EMAIL\",\n      \"SMS\"\n    ],\n    \"session_id_expiry\": \"2024-01-14T23:00:08+05:30\"\n  },\n  \"subscription_expiry_time\": \"2024-01-14T23:00:08+05:30\",\n  \"subscription_first_charge_time\": \"2024-01-10T23:00:08+05:30\",\n  \"subscription_tags\": {\n    \"psp_note\": \"Monthly subscription payment\",\n    \"key2\": \"value2\"\n  },\n  \"subscription_payment_splits\": [\n    {\n      \"vendor_id\": \"vendor1\",\n      \"amount\": 100,\n      \"percentage\": 10\n    },\n    {\n      \"vendor_id\": \"vendor2\",\n      \"amount\": 100,\n      \"percentage\": 10\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "authorisation_details": {
    "authorization_amount": 1,
    "authorization_amount_refund": false,
    "authorization_reference": "",
    "authorization_time": "2022-06-14T23:47:52+05:30",
    "authorization_status": "INITIALIZED",
    "payment_id": "97877",
    "payment_method": "NPCI_SBC"
  },
  "cf_subscription_id": "4",
  "customer_details": {
    "customer_name": "Test Cust",
    "customer_email": "test@gmail.com",
    "customer_phone": "9900755700",
    "customer_bank_account_holder_name": "",
    "customer_bank_account_number": "",
    "customer_bank_ifsc": "",
    "customer_bank_code": "",
    "customer_bank_account_type": ""
  },
  "plan_details": {
    "plan_id": "od-20k-plan",
    "plan_name": "On demand plan for 20000 max amount",
    "plan_type": "ON_DEMAND",
    "plan_max_cycles": 0,
    "plan_recurring_amount": 0,
    "plan_max_amount": 20000,
    "plan_interval_type": "",
    "plan_intervals": 0,
    "plan_currency": "INR",
    "plan_note": "",
    "plan_status": ""
  },
  "subscription_expiry_time": "2100-01-01T05:29:59+05:30",
  "subscription_first_charge_time": "",
  "subscription_id": "SUB0028",
  "subscription_meta": {
    "return_url": ""
  },
  "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
  "subscription_payment_splits": null,
  "subscription_status": "INITIALIZED",
  "subscription_tags": {
    "subscription_note": "subscription note"
  }
}
{
  "message": "bad URL, please check API documentation",
  "code": "request_failed",
  "type": "invalid_request_error"
}
{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}
{
  "message": "something is not found",
  "code": "somethind_not_found",
  "type": "invalid_request_error"
}
{
  "message": "something is not found",
  "code": "request_invalid",
  "type": "idempotency_error"
}
{
  "message": "Too many requests from IP. Check headers",
  "code": "request_failed",
  "type": "rate_limit_error"
}
{
  "message": "internal Server Error",
  "code": "internal_error",
  "type": "api_error"
}

Authorizations

ā€‹
x-client-id
string
header
required

Client app ID. You can find your app id in the Merchant Dashboard.

ā€‹
x-client-secret
string
header
required

Client secret key. You can find your secret key in the Merchant Dashboard.

Headers

ā€‹
x-api-version
string
default:2023-08-01
required

API version to be used

ā€‹
x-request-id
string

Request id for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to cashfree

ā€‹
x-idempotency-key
string<UUID>

An idempotency key is a unique identifier you include with your API call. If the request fails or times out, you can safely retry it using the same key to avoid duplicate actions.

Body

application/json

Request body to create a new subscription.

Request body to create a new subscription.

ā€‹
subscription_id
string
required

A unique ID for the subscription. It can include alphanumeric characters, underscore, dot, hyphen, and space. Maximum characters allowed is 250.

Required string length: 1 - 250
ā€‹
customer_details
CustomerDetails Ā· object
required

Subscription customer details.

Example:
{
  "customer_name": "Test Cust",
  "customer_email": "test@gmail.com",
  "customer_phone": "9900755700",
  "customer_bank_account_holder_name": "",
  "customer_bank_account_number": "",
  "customer_bank_ifsc": "",
  "customer_bank_code": "",
  "customer_bank_account_type": ""
}
ā€‹
plan_details
object
required
ā€‹
authorization_details
object
ā€‹
subscription_meta
object
ā€‹
subscription_expiry_time
string

Expiry date for the subscription.

ā€‹
subscription_first_charge_time
string

Time at which the first charge will be made for the subscription after authorization. Applicable only for PERIODIC plans.

ā€‹
subscription_tags
object | null

Custom Tags in the form of {"key":"value"} which can be passed for a subscription. A maximum of 10 tags can be added

Example:
{
  "psp_note": "Monthly subscription payment"
}
ā€‹
subscription_payment_splits
SubscriptionPaymentSplitItem Ā· object[]

Payment splits for the subscription.

Response

Subscription Created

The response returned for Get, Create or Manage Subscription APIs.

ā€‹
authorisation_details
AuthorizationDetails Ā· object

Details of the authorization done for the subscription. Returned in Get subscription and auth payments.

Example:
{
  "authorization_amount": 1,
  "authorization_amount_refund": false,
  "authorization_reference": "",
  "authorization_time": "2022-06-14T23:47:52+05:30",
  "authorization_status": "INITIALIZED",
  "payment_id": "97877",
  "payment_method": "NPCI_SBC"
}
ā€‹
cf_subscription_id
string

Cashfree subscription reference number

ā€‹
customer_details
CustomerDetails Ā· object

Subscription customer details.

Example:
{
  "customer_name": "Test Cust",
  "customer_email": "test@gmail.com",
  "customer_phone": "9900755700",
  "customer_bank_account_holder_name": "",
  "customer_bank_account_number": "",
  "customer_bank_ifsc": "",
  "customer_bank_code": "",
  "customer_bank_account_type": ""
}
ā€‹
plan_details
PlanEntity Ā· object

The response returned for Get, Create and Manage Plan APIs

Example:
{
  "plan_currency": "INR",
  "plan_id": "144436-03471-JD_TEST",
  "plan_interval_type": "WEEK",
  "plan_intervals": 1,
  "plan_max_amount": 1,
  "plan_max_cycles": 4,
  "plan_name": "abscede",
  "plan_note": "lsdkdn",
  "plan_recurring_amount": 1,
  "plan_status": "ACTIVE",
  "plan_type": "PERIODIC"
}
ā€‹
subscription_expiry_time
string

Time at which the subscription will expire.

ā€‹
subscription_first_charge_time
string

Time at which the first charge will be made for the subscription. Applicable only for PERIODIC plans.

ā€‹
subscription_id
string

A unique ID passed by merchant for identifying the subscription.

ā€‹
subscription_meta
object

Subscription metadata.

ā€‹
subscription_session_id
string

Subscription Session Id.

ā€‹
subscription_payment_splits
SubscriptionPaymentSplitItem Ā· object[]

Payment splits for the subscription.

ā€‹
subscription_status
string

Status of the subscription.

ā€‹
subscription_tags
object

Tags for the subscription.