1. Create Order

Learn how to create an Order.

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

Prerequisites

Create a Cashfree Merchant Account.
Log in to the Merchant Dashboard and generate test keys from developers Dashboard.
Generate API Keys (Client ID & Secret Key).

Sample Request

Sample request to create an Order in the language of your choice 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: 2022-09-01' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "order_amount": "10",
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "USER123",
    "customer_name": "Harshith",
    "customer_email": "[email protected]",
    "customer_phone": "+919876543210"
  },
  "order_meta": { 
    "notify_url": "https://webhook.site/c75b847b-c1b5-41bc-9a93-6f607cf58aa0"
  }

}'

Try Cashfree DevStudio

Try Now

❗️

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 is used in further steps to render the checkout page.

Request Parameters

The table below explains the Order API request parameters.

Name	Type	Description	Example
order_id	`string` `optional` (min 3, max 50, alphanumeric with _ and -)	The order ID identifies your order in the system.	order_8123
order_amount	`float` `required` (provide in two decimal places)	The order amount.	101.12 (INR 101.12 implies rupees 101 and 12 paisa)
order_currency	`string` `required`	The order currency. We use the ISO 4217 currency list.	The order currency - INR.
customer_details	`object` `required`	This 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_meta	`object` `optional`	This 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_time	`string` `optional`	Time after which the order expires. This is the time after which customers will not be able to make any payment "attempt". We will reverse any delayed payment received from the bank side after this time (if the attempt was made within the expiry time).	2023-07-29T00:00:00Z
order_note	`string` `optional`	Order 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.

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	Customer phone number. Provide a valid 10 digit phone number.

Order Meta

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

Name	Type	Description
return_url	`string` `optional`	Your customers will be redirected to this URL after making 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 must contain a placeholder {order_id}. When redirecting customer back to the return URL from the bank’s OTP page, Cashfree Payments will replace the 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 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_12. Only https URL allowed in production, http is allowed only in sandbox.
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".

Sample 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_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"
  }
}

Try this api and others at Cashfree Labs

Try Now

Upon successful order creation, you will receive a 200 response along with the order entity. This has relevant information regarding 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.

Parameters	Description
cf_order_id	The ID that identifies the order in Cashfree Payments system.
created_at	The time at which the order was created in Cashfree Payments system.
order_id	It is the unique ID to identify the order. If no order ID is provided, we automatically generate one.
order_amount , order_currency	The order amount and the order currency for this order.
order_expiry_time	This is the maximum time beyond which Cashfree Payments will not accept payments for this order.
payment_session_id	This is the session id which will be used in the JS SDK to redirect your customers to Cashfree Payments checkout page.
order_status	The 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_note	The note that was passed by you for this order.
customer_details	These are the customer details passed by you.
order_meta	Meta details passed for this order. `return_url`, `notify_url` and `payment_methods`.
payments	This is the URL to access all the payment attempts for this order.
refunds	This is the URL to access all the refunds for this order.
settlements	This is the URL to access settlement amounts and settlement-related information for this order.

The table below explains the various states an order can go through -

Order State	Description
ACTIVE	This 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.
PAID	This state indicates that your customer has completed the order payment.
EXPIRED	This state indicates that the order has expired and your customers can no longer pay for this order. You must create a new order.
TERMINATED	This 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.

Ask a question about Integration

You can ask questions and participate in discussions about Cashfree PG API in the Cashfree Discord channel.

Subscribe to Developer Updates

Updated about 1 year ago