Handle Return URL and Confirm Status

Once the customer enters the OTP on the payment page, they will return back to the return url.

There are two broad types of payment flows -

  1. Where customer is redirected to a third party page (bank OTP page, app login page, etc.)
  2. Where customer needs to approve the payment through an asynchronous process (example - by approving a payment request on their phone).

While the former requires a redirection to the third party page, the latter does not. In case the customer is redirected from your website to a third party page, you would also want them to return back to your application. The return_url provided in the create order API call is used for this.

🚧

Return URL

Once the customer has completed the payment on the banks OTP page, we will redirect them back to your return_url. This will be a link based redirection, so if you have provided a return_url of the format - https://b8af79f41056.eu.ngrok.io?order_id={order_id} - the customer will be redirected to the url - https://b8af79f41056.eu.ngrok.io?order_id=order_271vfuhh1o4h6bQIigqyOx74YiJ1T

Once you receive a request on this URL, you must first confirm if the the order_id belong to the same order.

The last step is to check the status of the order in Cashfree's system and update the order at your end. You can do it through a simple GET request as below.
There are few things you should ensure

  1. Only make successful orders which are still active in your system. If an order is already PAID, you do not want to fulfil it again.
  2. Make sure that you always check the order status. The order_status can be one of ACTIVE, PAID or EXPIRED. You must fetch the order status from your backend using the /orders/:orderID API call as below.
curl --request GET \
  --url https://sandbox.cashfree.com/pg/orders/order_271vWwzSQOHe01ZVXpEcguVxQSRqr \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <<x-api-version>>' \
  --header 'x-client-id: <appID>' \
  --header 'x-client-secret: <secret Key>'
{
  "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_VnheAG4KDGWpJ2qI936z5aaZ3cJFe4jOtj0hDp7x9I49RQzucQ0b2hvi5axrMRqprXmTPegGBG15f3fl76aueRvnSFVNhw7AkUxPaDmQPoVv",
  "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"
  }
}
<?php

$orderId = "order_HDUp8wlq";
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://sandbox.cashfree.com/pg/orders/$orderId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'x-client-id: {{appId}}',
    'x-client-secret: {{secretKey}}',
    'x-api-version: 2021-05-21'
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if(!$err) {
    $result = json_decode($response, true);
    if($result["order_status"] == 'PAID'){
        echo "This order is paid!";
    } else {
        echo "Order has not been paid!";
    }
} else {
    echo  $err;
}

?>
curl --request GET \
  --url https://sandbox.cashfree.com/pg/orders/order_1471yUGAj97hSGoOB \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2021-05-21' \
  --header 'x-client-id: {{appId}}' \
  --header 'x-client-secret: {{secretKey}}'
  
  // response
  {
  "cf_order_id": 594193729,
  "created_at": "2021-09-22T13:46:51+05:30",
  "customer_details": {
    "customer_id": "P9999711",
    "customer_name": null,
    "customer_email": "[email protected]",
    "customer_phone": "9899049110"
  },
  "entity": "order",
  "order_amount": 1.00,
  "order_currency": "INR",
  "order_expiry_time": "2021-10-22T13:46:51+05:30",
  "order_id": "order_1471yUGAj97hSGoOB",
  "order_meta": {
    "return_url": "http://localhost:1774/resp.php?order_id={order_id}&order_token={order_token}",
    "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php",
    "payment_methods": null
  },
  "order_note": null,
  "order_splits": [],
  "order_status": "PAID",
  "order_tags": null,
  "order_token": "9AtvrNXIXgQqFsJbaRVc",
  "payment_link": "https://payments.cashfree.com/order/#9AtvrNXIXgQqFsJbaRVc",
  "payments": {
    "url": "https://api.cashfree.com/pg/orders/order_1471yUGAj97hSGoOB/payments"
  },
  "refunds": {
    "url": "https://api.cashfree.com/pg/orders/order_1471yUGAj97hSGoOB/refunds"
  },
  "settlements": {
    "url": "https://api.cashfree.com/pg/orders/order_1471yUGAj97hSGoOB/settlements"
  }
}

Ask a question about Integration

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

INTEGRATION TOOLKIT

Try our Integration

What’s Next

Now that you have completed the sandbox integration, go through the final checklist once before pushing things to production.