1. Create Order

Learn how to create an order.

Creating an order is the first step to integrate Cashfree Payment Gateway. To process any payments, you must create an order first.

Prerequisites

Request

Sample request to create an Order in your desired language using our backend SDKs.

curl --location 'https://sandbox.cashfree.com/pg/orders' \
--header 'X-Client-Secret: {{clientKey}}' \
--header 'X-Client-Id: {{clientId}}' 
--header 'x-api-version: 2023-08-01' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "order_amount": 10.10,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "USER123",
    "customer_name": "joe",
    "customer_email": "[email protected]",
    "customer_phone": "+919876543210"
  },
  "order_meta": { 
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123",
  }

}'
import com.cashfree.*;

Cashfree.XClientId = {Client Key};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.SANDBOX;

static void createOrder() {
  CustomerDetails customerDetails = new CustomerDetails();
  customerDetails.setCustomerId("123");
  customerDetails.setCustomerPhone("9999999999");

  CreateOrderRequest request = new CreateOrderRequest();
  request.setOrderAmount(1.0);
  request.setOrderCurrency("INR");
  request.setCustomerDetails(customerDetails);
  try {
    Cashfree cashfree = new Cashfree();
    ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
    System.out.println(response.getData().getOrderId());

  } catch (ApiException e) {
    throw new RuntimeException(e);
  }
}
import (
  cashfree "github.com/cashfree/cashfree-pg/v3"
)

func createOrder() {

clientId := {Client ID}
clientSecret := {Client Secret Key}
cashfree.XClientId = &clientId
cashfree.XClientSecret = &clientSecret
cashfree.XEnvironment = cashfree.SANDBOX

request := cashfree.CreateOrderRequest{
		OrderAmount: 1,
		CustomerDetails: cashfree.CustomerDetails{
			CustomerId:    "1",
			CustomerPhone: "9999999999",
		},
		OrderCurrency: "INR",
		OrderSplits:   []cashfree.VendorSplit{},
	}
	version := "2023-08-01"
	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
	if err != nil {
		fmt.Println(err.Error())
	} else {
		fmt.Println(httpResponse.StatusCode)
		fmt.Println(response)
}

}
using cashfree_pg.Client;

using cashfree_pg.Model;

Cashfree.XClientId = {Client ID};

Cashfree.XClientSecret = {Client Secret Key};

Cashfree.XEnvironment = Cashfree.PRODUCTION;

var cashfree = new Cashfree();

var xApiVersion = "2023-08-01";

void CreateOrder() {
    var customerDetails = new CustomerDetails("123", null, "9999999999");
    var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
    try {
        // Create Order
        var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
        Console.WriteLine(result);
        Console.WriteLine(result.StatusCode);
        Console.WriteLine((result.Content as OrderEntity));
    } catch (ApiException e) {
        Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
        Console.WriteLine("Status Code: " + e.ErrorCode);
        Console.WriteLine(e.StackTrace);
    }
}
import { Cashfree } from "cashfree-pg"; 

Cashfree.XClientId = {Client ID};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.Environment.PRODUCTION;

function createOrder() {
  var request = {
    "order_amount": "1",
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "node_sdk_test",
      "customer_name": "",
      "customer_email": "[email protected]",
      "customer_phone": "9999999999"
    },
    "order_meta": {
      "return_url": "https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123"
    },
    "order_note": ""
  }

  Cashfree.PGCreateOrder("2023-08-01", request).then((response) => {
    var a = response.data;
    console.log(a)
  })
    .catch((error) => {
      console.error('Error setting up order request:', error.response.data);
    });
}
\Cashfree\Cashfree::$XClientId = "<x-client-id>";
\Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
\Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

$cashfree = new \Cashfree\Cashfree();

$x_api_version = "2023-08-01";
$create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
$create_orders_request->setOrderAmount(1.0);
$create_orders_request->setOrderCurrency("INR");
$customer_details = new \Cashfree\Model\CustomerDetails();
$customer_details->setCustomerId("123");
$customer_details->setCustomerPhone("9999999999");
$create_orders_request->setCustomerDetails($customer_details);

try {
    $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
}
from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.customer_details import CustomerDetails


Cashfree.XClientId = {Client ID}
Cashfree.XClientSecret = {Client Secret Key}
Cashfree.XEnvironment = Cashfree.XSandbox
x_api_version = "2023-08-01"

def create_order():
        customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
        createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
        try:
            api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
            print(api_response.data)
        except Exception as e:
            print(e)
labs icon Try Cashfree DevStudio
Try Now

👍

Watchout!

  • You must create this order from the backend as it uses your client ID and the secret key.
  • You can create the order using the Create Order API. On successful creation of the order, you will receive the payment_session_id. This payment_session_id will be used in further steps to open the checkout page.

Request Parameters

The Order API request parameters are explained in the table below.

NameTypeDescriptionExample
order_idstring optional (min 3, max 50, alphanumeric with _ and -)The order ID identifies your order in the system.order_8123
order_amountfloat required (provide in two decimal places)The order amount.101.12 (INR 101.12 implies
rupees 101 and 12 paisa)
order_currencystring requiredThe order currency. We use the ISO 4217 currency list.The order currency - INR.
customer_detailsobject requiredThis is a custom object which contains customer_details. The details of the customer such as:
- customer ID
- name of the customer
- email of the customer
- phone number of the customer.
See the customer_details object below for more details.
order_metaobject optionalThis is a custom object which contains information about available payment methods for this order, webhook url and notify url.See the order_meta object for more for details.
order_expiry_timestring optionalTime after which the order expires. This is the time after which customers will not be able to make any payment "attempt". Any delayed payment received from the bank side post this time (whose attempt was done within expiry time) will be reversed.2023-07-29T00:00:00Z
order_notestring optionalOrder note for reference purposes.Sample note

ℹ️

There are two objects in the above payload which require some more information - customer_details and order_meta. Find the details in the section below.


Customer Details

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

NameTypeDescription
customer_idstring required (alphanumeric with - and _ allowed)This is is the identifier for the customer in your system. (Example - customer1234)
customer_namestring required (Special characters are not allowed)Name of your customer.
customer_emailstring Email id of the customer[email protected]
customer_phonestring required Phone of the customerCustomer phone number. Provide a valid 10 digit phone number.
customer_uidstring required (Either of (customer_id, customer_phone) or customer_uid is required)Unique identifier of the customer created at Cashfree. You can create customer using Create Customer API.

Order Meta

The meta-object can be used to control payment behaviour. You can customise the payment options and also configure the webhook endpoint.

NameTypeDescription
return_urlstring optionalThis is the URL to which your customers will be redirected to after the payment.

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 return url page.

The return_url should contain order_id for your convenience of identifing the order. Example - Let's say you create an order with orderId "order_123" then you can provide a return URL like https://merchant.in/pg/process_return?order_id=order_123.

When the customer is returning to your page from the bank's OTP page, we will hit the following URL: - https://merchant.in/pg/process_return?cf_id=order_123. With order_id present in return url, you can identify the order for which this url is hit and can do the recon accordingly.

Only https URL allowed in production, http is allowed only in sandbox.
payment_methodsstring optionalList 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

Sample Response for the above request is as below.

{
  "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_123",
    "payment_methods": null
  },
  "order_note": null,
  "order_status": "PAID",
  "payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD"
}
labs icon Try Cashfree DevStudio
Try Now

Once the order is created successfully, 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. Refer to the table below for more details on the order response.

ParametersDescription
cf_order_idThe ID that identifies the order in Cashfree Payments system. It is a string.
created_atThe time at which the order was created in Cashfree Payments system.
order_idIt is the unique ID provided by you to identify the order. If you do not provide an order ID, we automatically generate one.
order_amount , order_currencyThe order amount and the order currency for this order.
order_expiry_timeThis is the maximum time beyond which Cashfree Payments will not accept payments for this order.
payment_session_idThis is the session id which will be used in the JS SDK to redirect your customers to Cashfree Payments checkout page.
order_statusThe status of the order -ACTIVE, PAID, EXPIRED,TERMINATED, TERMINATION_REQUESTED.

An order when created is ACTIVE in the Cashfree Payments system. The order either gets paid or expires after a certain time.
order_noteThe note that was passed by you for this order.
customer_detailsThese are the customer details passed by you.
order_metaMeta details passed for this order. return_url and payment_methods.

Order States

An order can go through various states, they are explained in the table below:

Order StateDescription
ACTIVEThis state indicates that the order is active and yet to be paid. Once your customer has completed the order payment, Cashfree Payments processes the payment information.
PAIDThis state indicates that your customer has completed the order payment.
EXPIREDThis state indicates that the order has expired and your customers can no longer pay for this order. You must create a new order.
TERMINATEDThis status might come ONLY if you request to terminate the Order using [Order Termination API](Order Termination API). This indicates that customers can no longer pay for this order.
TERMINATION_REQUESTEDThis status might come ONLY if you request to terminate the Order using [Order Termination API](Order Termination API). This indicates that you have requested to Terminate the order, however, its still under process. Order gets Terminated only if there's no transaction in a non-terminal state. If a transaction is in intermediate state and gets success then status can go from TERMINATION_REQUESTED to SUCCESS also.

What’s Next