❗️
Order creation must happen from your backend (as this API uses your secret key).

To process any payment on Cashfree Payment Gateway, the merchant needs to create an order in the Cashfree system. On successful creation of the order, you will receive a payment_session_id which can be used in our Javascript Checkout SDK to redirect to Cashfree's checkout page.

Cashfree provides two environments, one being the sandbox environment for developers to test the payment flow & responses and the other being production environment which gets shipped to production. The URL for these are -
Production -> https://api.cashfree.com/pg/orders
Sandbox -> https://sandbox.cashfree.com/pg/orders

Curl Request

Following is a sample curl request that can be used.

curl  --request POST \
 --url https://sandbox.cashfree.com/pg/orders \
 --header 'Content-Type: application/json' \
 --header 'x-api-version: 2022-09-01' \
 --header 'x-client-id: <App ID>' \
 --header 'x-client-secret: <Secret Key>' \
 --data '{
  "order_id": "order_1626945143520",
  "order_amount": 10.12,
  "order_currency": "INR",
  "order_note": "Additional order info",
  "customer_details": {
   "customer_id": "12345",
    "customer_name": "name",
    "customer_email": "[email protected]",
    "customer_phone": "9816512345"
  }
}'

{
  "cf_order_id": 1539553,
  "created_at": "2021-07-19T16:13:35+05:30",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_name": null,
    "customer_email": "[email protected]",
    "customer_phone": "9908734801"
  },
  "entity": "order",
  "order_amount": 5.01,
  "order_currency": "INR",
  "order_expiry_time": "2021-08-18T16:13:34+05:30",
  "order_id": "order_271vWwzSQOHe01ZVXpEcguVxQSRqr",
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id={order_id}",
    "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php",
    "payment_methods": null
  },
  "order_note": null,
  "order_status": "PAID",
  "payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD",
  "payments": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/payments"
  },
  "refunds": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/refunds"
  },
  "settlements": {
    "url": "https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr/settlements"
  }
}

Use test API keys for creating order in Sandbox/test environment and prod API keys for creating order in production environment. Refer here to know how to generate or view API keys.

INTEGRATION TOOLKIT

Try our Integration Try the API's using Postman

Name	Type	Description	Example
order_id	`string` `optional` (min 3, max 50, alphanumeric with _ and -)	Order identifier for your system.	order_8123
order_amount	`float` `required` (provide in two decimal places)	Order amount.	101.12 (INR 101.12 implies rupees 100 and 12 paisa)
order_currency	`string` `required`	Valid order currency. We use the ISO 4217 currency list.	INR
customer_details	`object` `required`	This is a custom object which contains customer_details	See below for details of this object
order_meta	`object` `optional`	This is a custom object which contains information about available payment modes for this order, webhook url and notify url.	See below for details of this object.
order_expiry_time	`string` `optional`	Time after which the order expires. This is the time after which customers will not be able to make the payment "attempt". Any delayed payment received from the bank side post this time (whose attempt was done within expiry time) will be reversed.	2021-07-29T00:00:00Z
order_note	`string` `optional`	Order related extra detail

There are two objects in the above payload which require some more context - customer_details and order_meta

Customer Details

The customer details are required for risk checks and in providing a seamless experience to repeat customers.

Name	Type	Description
customer_id	`string` `required` (alphanumeric with - and _ allowed)	This is is the identifier for the customer in your system. (Example - customer1234)
customer_name	`string` `required` (Special characters are not allowed)	Name of your customer.
customer_email	`string` `required` Email id of the customer	[email protected]
customer_phone	`string` `required` Phone of the customer	Please provide valid 10 digit phone number.

Order Meta

The meta object can be used to control the payment behaviour. You can customize the payment options available to the customer for this order and also configure the webhook endpoint.

Name	Type	Description
return_url	`string` `optional`	This is the return url for redirection based payments. When a customer makes a card payment they are redirected from your website to the bank's OTP page. From there the customer is redirected back to your The return_url must contain placeholder {order_id}. When redirecting the customer back to the return url from the bank’s OTP page, Cashfree will replace these placeholder with the actual value for that order. Example - Let's say you provide a return url like https://merchant.in/pg/process_return?order_id={order_id} when the customer is getting back to your page from the bank's OTP page. We will hit the following url - https://merchant.in/pg/process_return?cf_id=order_12 Only https url allowed in production, http is allowed only in sandbox. Refer here for more details on how to handle return URL
notify_url	`string` `optional`	The webhook url is required to get successful or failed webhooks after a payment on an order is completed. Only https url allowed in production, http is allowed only in sandbox.
payment_methods	`string` `optional`	List of payment modes. Use the following values - `cc`, `dc`, `ccc`, `ppc`, `nb`, `upi`, `paypal`, `emi`, `app` `paylater`. For example, if you want to accept only net banking and UPI from customers, you must pass the following value - "nb,upi".

Response

If the order creation is successful you will receive a 200 response and the order entity in response. This order entity contains relevant details for the order and the details provided in the request.

We recommend that you store the following parameters at your end cf_order_id, payment_session_id, and the order_status. The below table should help you understand the order response.

Parameters	Description
cf_order_id	This is the identifier for this order in Cashfree's system.
created_at	The time when this order was created in Cashfree's system.
order_id	Order Id provided by the merchant. If merchant does not provide an order id we auto-generate one.
order_amount , order_currency	Order amount and the currency for this order.
order_expiry_time	This is the maximum time beyond which Cashfree will not accept payment for this order.
payment_session_id	This is the session id which will used in JS SDK to redirect to checkout page. See next steps for a better understanding.
order_status	The order status -`ACTIVE`, `PAID`, `EXPIRED`. An order when created is ACTIVE in the Cashfree Payments system. It will either be paid or get expired after a certain time.
order_note	The note passed by the merchant for this order.
customer_details	These are the customer details passed by the merchant.
order_meta	Meta details passed for this order. `return_url`, `notify_url` and `payment_methods`.
payments	This is a URL that can be used to access all the payment attempts on this Order. See API for more details.
refunds	This is a URL which can be used to access all the refunds for this Order. See API for more details.
settlements	This is a URL which can be used to access all the settlement amount and settlement related information for this Order. See API for more details.

Backend code

Here is a sample backend code that needs to be hosted by you to create an order. This endpoint will be consumed by your javascript code to fetch a token. Please note that the curl fields are hardcoded in the below PHP code.

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.cashfree.com/pg/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"customer_details\":{\"customer_id\":\"12345\",\"customer_email\":\"[email protected]\",\"customer_phone\":\"9908734801\"},\"order_amount\":4,\"order_currency\":\"INR\",\"order_note\":\"test order\"}",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Content-Type: application/json",
    "x-api-version: 2022-09-01",
    "x-client-id: <app Id>",
     "x-client-secret: <secret key>"
  ],
]);

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

curl_close($curl);

if ($err) {
  header('Content-Type: application/json; charset=utf-8');
  echo json_encode(array("error" => 1));
  echo "cURL Error #:" . $err;
  die();

} else {
  $result = json_decode($response, true);
  header('Content-Type: application/json; charset=utf-8');
  $output = array("payment_session_id" => $result["payment_session_id"]);
  echo json_encode($output);
  die();
}
?>

{"payment_session_id":"session_kUQjlgkHS_TUp6wYMWRtHrjDyy9Thb-m2eXe0vYGuF_hns2NL41akH4g14fX9zW41jZSrcl8RyiZp-Zdh-mk30gfULunxjL7qMOu5BIyl-F4"}

Javascript code

Once you have tested the backend code which creates a token for a specific order, we must call this endpoint from the frontend. Below we simply show how to do this in jquery.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script>
  var paymentSessionId = "";
  const getSessionAndPay = function(){
  $.ajax({
    url: "http://localhost/cashfree/jssdk/fetchtoken.php",
    success: function(result) {
      console.log(result);
      paymentSessionId = result["payment_session_id"]
      // comment this out for now, we will use this later!
      //cfCheckout.pay(orderToken, payType);
    }
  });
  return false
}
</script>

Create order in production environment

Use Prod API keys for creating order in prod environment and follow the above mentioned steps. Refer here to know how to generate or view prod API keys.

You also need to whitelist your domain name on Cashfree Payments system. Refer here to know how to do Whitelisting.

Please note that prod environment can be accessed only when PG is activated for your account.