Create Order

Order

An order is an entity which has a amount and currency associated with it. It is something for which you want to collect payment for. Use this API to create orders with Cashfree from your backend to get a payment_sessions_id. You can use the payment_sessions_id to create a transaction for the order.

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 in the Merchant Dashboard.

Headers

x-api-version · string · default: 2022-09-01 · required

API version to be used. Format is in YYYY-MM-DD

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>

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

Currently supported on all POST calls that uses x-client-id & x-client-secret. To use enable, pass x-idempotency-key in the request header. The value of this header must be unique to each operation you are trying to do. One example can be to use the same order_id that you pass while creating orders

Body

application/json

Request body to create an order at cashfree

order_amount · number · required

Bill amount for the order. Provide upto two decimals. 10.15 means Rs 10 and 15 paisa

Required range: x >= 1

Example:

10.15

order_currency · string · required

Currency for the order. INR if left empty. Fill out the Support Form to enable new currencies.

Example:

"INR"

customer_details · object · required

The customer details that are necessary. Note that you can pass dummy details if your use case does not require the customer details.

Show child attributes

Example:

{
  "customer_id": "7112AAA812234",
  "customer_email": "[e-mail]",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333
}

order_id · string | null

Order identifier present in your system. Alphanumeric, '_' and '-' only

Required string length: 3 - 45

Example:

"your-order-id"

terminal · object

Use this if you are creating an order for cashfree's softPOS

Show child attributes

Example:

{
  "terminal_phone_no": "6309291183",
  "terminal_id": "terminal-123",
  "terminal_type": "SPOS",
  "added_on": "2023-08-04T13:12:58+05:30",
  "cf_terminal_id": 1051123,
  "last_updated_on": "2023-09-06T14:07:00+05:30",
  "terminal_address": "Banglore",
  "terminal_name": "test",
  "terminal_note": "POS vertical",
  "terminal_status": "ACTIVE"
}

order_meta · object

Optional meta details to control how the customer pays and how payment journey completes

Show child attributes

Example:

{
  "return_url": "https://example.com?order_id={order_id}",
  "notify_url": "https://example.com/webhook.php",
  "payment_methods": "cc,dc"
}

order_expiry_time · string<ISO8601>

Time after which the order expires. Customers will not be able to make the payment beyond the time specified here. We store timestamps in IST, but you can provide them in a valid ISO 8601 time format. Example 2021-07-02T10:20:12+05:30 for IST, 2021-07-02T10:20:12Z for UTC

Example:

"2021-07-02T10:20:12+05:30"

order_note · string | null

Order note for reference.

Required string length: 3 - 200

Example:

"Test order"

order_tags · object | null

Custom Tags in thr form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

Example:

{
  "name": "John Doe",
  "city": "Bangalore",
  "product": "Laptop",
  "shipping_address": "123 Main St"
}

order_splits · VendorSplit · object[] | null

If you have Easy split enabled in your Cashfree account then you can use this option to split the order amount.

Show child attributes

Example:

[{ "amount": 10, "vendor": "john" }]

Response

200

application/json

OK

The complete order entity

cf_order_id · integer

unique id generated by cashfree for your order

order_id · string

order_id sent during the api request

entity · string

Type of the entity.

order_currency · string

Currency of the order. Example INR

order_amount · number

order_status · string

Possible values are

• ACTIVE: Order does not have a sucessful transaction yet
• PAID: Order is PAID with one successful transaction
• EXPIRED: Order was not PAID and not it has expired. No transaction can be initiated for an EXPIRED order.

payment_session_id · string

order_expiry_time · string<date-time>

order_note · string | null

Additional note for order

created_at · string<date-time>

When the order was created at cashfree's server

Example:

"2022-08-16T14:45:38+05:30"

order_splits · VendorSplit · object[]

Show child attributes

customer_details · object

The customer details that are necessary. Note that you can pass dummy details if your use case does not require the customer details.

Show child attributes

Example:

{
  "customer_id": "7112AAA812234",
  "customer_email": "[e-mail]",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333
}

order_meta · object

Optional meta details to control how the customer pays and how payment journey completes

Show child attributes

payments · object

URL for payment retrieval for an order

Show child attributes

settlements · object

Settlement URL object

Show child attributes

refunds · object

URL to get refunds for order

Show child attributes

order_tags · object | null

Custom Tags in thr form of {"key":"value"} which can be passed for an order. A maximum of 10 tags can be added

Show child attributes

Example:

{
  "product": "Laptop",
  "shipping_address": "123 Main St"
}