1. Create Order
In this article, let us learn how to create an order.
Prerequisites
- Create a merchant account with Cashfree Payments
- Generate API Keys with Cashfree Payments
Creating an order is the first step in web integration. To process any payments, you must create an order for every payment. You must create this order from the backend as it uses your client ID and the secret key. This step is common for both integration types.
You can create the order using the Create Order API. On successful creation of the order, you will receive a payment_session_id. This payment_session_id is used to invoke the javascript checkout SDK code that renders the Cashfree Payments checkout page.
There are various states an order can go through, they are explained in the table below:
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. |
Sample Curl Request and Response
The following is a sample request and response used for creating an order using the Create Order API.
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 PostmanRequest 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 100 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". 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_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
andorder_meta
. Find the details in the below section.
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 also configure the webhook endpoint.
Name | Type | Description |
---|---|---|
return_url | string optional | This 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 must contain a placeholder {order_id}. When redirecting the 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". |
Response
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.
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 provided by you to identify the order. If you do not provide an order ID, 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 .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. |
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.
The curl fields are hardcoded in the PHP code below.
<?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. The snippet below shows you 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.
Updated 2 months ago