Telr Developer Documentation

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders \
  --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 '
{
  "order_currency": "INR",
  "order_amount": 10.34,
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  }
}
'

{
  "$ref": "#/components/examples/order_entity_list_example/value/0"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "somethind_not_found",
  "type": "invalid_request_error"
}

{
  "message": "order with same id is already present",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "order_already_exists",
  "type": "invalid_request_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "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",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "internal_error",
  "type": "api_error"
}

POST

orders

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders \
  --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 '
{
  "order_currency": "INR",
  "order_amount": 10.34,
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  }
}
'

{
  "$ref": "#/components/examples/order_entity_list_example/value/0"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "somethind_not_found",
  "type": "invalid_request_error"
}

{
  "message": "order with same id is already present",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "order_already_exists",
  "type": "invalid_request_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "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",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "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 in the merchant dashboard.

Headers

x-api-version

string

default:2025-01-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 an order at cashfree

order_amount

number<double>

required

Bill amount for the order. Provide upto two decimals. 10.15 means Rs 10 and 15 paisa. For orders in non-INR currency, please refer to supported amounts per currency.

Required range: x >= 1

Example:

10.15

order_currency

string

required

Currency for the order. INR if left empty. For support currency list, refer here. Contact care@cashfree.com to enable new currencies.

Example:

"INR"

customer_details

CustomerDetails · 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": "john@cashfree.com",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333,
  "customer_uid": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10"
}

order_id

string

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

Required string length: 3 - 45

Example:

"your-order-id"

cart_details

CartDetails · object

The cart details that are necessary like shipping address, billing address and more.

Show child attributes

terminal

Terminal · object

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

Show child attributes

Example:

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

order_meta

OrderMeta · object

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

Show child attributes

Example:

{
  "return_url": "https://www.cashfree.com/devstudio/thankyou",
  "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

Order note for reference.

Required string length: 3 - 200

Example:

"Test order"

order_tags

object

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",
  "name": "John Doe",
  "city": "Bangalore"
}

order_splits

VendorSplit · object[]

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" }]

products

products · object

Use this to set configurations for the products like One Click Checkout, Verify and Pay, if they are enabled for your account

Show child attributes

Response

The complete order entity

cf_order_id

string

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. TERMINATED: Order terminated TERMINATION_REQUESTED: Order termination requested

payment_session_id

string

order_expiry_time

string

order_note

string

Additional note for order

created_at

string

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

CustomerDetailsResponse · 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": "john@cashfree.com",
  "customer_phone": "9908734801",
  "customer_name": "John Doe",
  "customer_bank_account_number": "1518121112",
  "customer_bank_ifsc": "XITI0000001",
  "customer_bank_code": 3333,
  "customer_uid": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10"
}

order_meta

OrderMeta · object

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

Show child attributes

order_tags

object

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

cart_details

CartDetailsEntity · object

Cart Details in the Order Entity Response

Show child attributes

terminal_data

TerminalData · object

Terminal Data in the create order response

Show child attributes

Example:

{
  "agent_mobile_number": "9876543214",
  "cf_terminal_id": 1838,
  "merchant_terminal_id": "ahdsgadjhgfaj7137e",
  "terminal_type": "STOREFRONT"
}

products

object

Configurations for the products like One Click Checkout, Verify and Pay, if they are enabled for your account

Show child attributes

Payments API

v2025-01-01

Create Order

Order

Authorizations

Headers

Body

Response