Embedded Payments Sandbox

Build and safely test your Embedded Payment Gateway Integration in our Sandbox (‘Test’) Environment developed exclusively for Embedded Payments Partners. Our aim is to streamline the integration process for developers seeking to incorporate our Payments and/or Onboarding APIs and Webhooks into their software platforms. This dedicated testing environment provides you with a robust space to experiment, simulate, and code our development solutions within your platforms. Use the sandbox environment to test and validate your API and webhook integrations before going live in production.

Advantages

Safe Testing: You can conduct thorough testing without affecting real transactions. This safeguards your live environment while refining payment flows.
Realistic Simulations: You can mimic real-world scenarios with our realistic simulations. You can as well test various payment methods, edge cases, and user interactions effortlessly.
Enhanced Debugging: You can diagnose and troubleshoot issues effectively with detailed error reporting. Identify and resolve potential challenges before you impact your live users.

How to simulate working environment in sandbox?

To begin with, login to your Partner Dashboard > and click the Switch to Test option. The dashboard will switch to the Test Environment (sandbox). There will be a visible label at the top to let you identify that you are in the Test Environment.

When you are in the test environment, the “Switch to Test” button will change to “Switch to Prod”. You can use it to switch back to the live environment. In the test environment, you can simulate essential features of the payment gateway. You can replicate and test the functionalities required for the payment gateway system to operate seamlessly. You can add new merchants from the Merchants section through the Add Merchant option. The system enables the added merchant in the test environment with the payment gateway activated and default pricing.

Only Business Name, Registered Email and Phone Number are mandatory when adding a merchant in the test environment. You can then select the checkbox “I agree to the terms and conditions” and submit the form.
This activation takes up to 5 mins. Refresh the Merchants tab to recheck the activation status.
Please note that KYC is required for activating merchants in the live environment.

You can access the Developers tab, and generate Partner API Key and configure Partner Webhooks as well. Once done, you can follow integration steps mentioned in the Embedded Payment Gateway Integration guide. To access your test API keys directly, go to Partner Dashboard > Developers > API Keys (test environment).

Sample request to Create an Order -

curl

curl --location 'https://sandbox.cashfree.com/pg/orders' \
--header 'x-partner-apikey: {{partnerAPIKey}}' \
--header 'x-partner-merchantid: {{partnermerchantId}}'
--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": "joe",
    "customer_email": "joe.s@cashfree.com",
    "customer_phone": "+919876543210"
  },
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id={order_id}",
    "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php",
  }
}'

Sample request to Get Order details -

curl

curl --request GET \
     --url https://sandbox.cashfree.com/pg/orders/{{order_id}}\
     --header 'x-partner-apikey: {{partnerAPIKey}}' \
     --header 'x-partner-merchantid: {{partnermerchantId}}'
     --header 'accept: application/json' \
     --header 'x-api-version: 2022-09-01'

Apart from this, you can simulate payments using payments methods such as Card, UPI, and other payment modes that are part of the integration. Other features like Summary, PG Orders, Reports will also work in Test Environment

The data between Live and Test environments is completely isolated. Any data changes (eg. merchant addition, order creation etc.) in this environment will not happen in Live, and vice versa. These are not live transactions, these are just simulations. No fund movement will occur.

Partner webhooks

You can also configure webhooks in the test environment. To configure partner webhook,

Go to Partner Dashboard > Developers > Webhooks.

Click Add Webhook URL and enter the URL where you want to receive the updates.
Select the events for which you want to configure the webhooks to receive updates, and click Add Webhook.

Notifications will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type. We support webhooks in both encoded and JSON formats.

Payment success webhook

A payment success webhook notifies you when a payment completes successfully. Use this event to update the payment status, trigger fulfilment, and send a confirmation to the customer.

Sample payload

{
  "data": {
    "customer_details": {
      "customer_email": "customer@example.com",
      "customer_id": "customer_001",
      "customer_name": "Sample Customer",
      "customer_phone": "9999999999"
    },
    "order": {
      "order_amount": 481.12,
      "order_currency": "INR",
      "order_id": "CFPay_oajh3anbh140_AAAAAACpnxQ_62e8_1782286213402",
      "order_tags": {
        "cf_link_id": "6976920",
        "link_id": "link111163083FZcnhNgBinXLztUJv9E10tFXQw",
        "mf_member_id": "ESPLUAT"
      }
    },
    "payment": {
      "auth_id": null,
      "bank_reference": "1234567890",
      "cf_payment_id": 5114930339041,
      "payment_amount": 481.12,
      "payment_currency": "INR",
      "payment_group": "upi",
      "payment_message": "Simulated response message",
      "payment_method": {
        "upi": {
          "channel": "collect",
          "upi_id": "testsuccess@gocash"
        }
      },
      "payment_status": "SUCCESS",
      "payment_time": "2026-06-24T13:01:22+05:30"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": null,
      "gateway_order_reference_id": null,
      "gateway_payment_id": null,
      "gateway_settlement": "CASHFREE",
      "gateway_status_code": null
    },
    "payment_offers": null
  },
  "event_time": "2026-06-24T13:01:40+05:30",
  "merchant": {
    "merchant_id": "Merchant_business001_1782217071175"
  },
  "type": "PAYMENT_SUCCESS_WEBHOOK"
}

Payment failed webhook

A payment failed webhook notifies you when a payment attempt fails and Cashfree receives a failure response from the bank. Use this event to record the failed attempt, notify the customer, and allow them to retry the payment.

Sample payload

{
  "data": {
    "order": {
      "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
      "order_amount": 1.8,
      "order_currency": "INR",
      "order_tags": {
        "cf_link_id": "13746255"
      }
    },
    "payment": {
      "cf_payment_id": 1504280029,
      "payment_status": "FAILED",
      "payment_amount": 1.8,
      "payment_currency": "INR",
      "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
      "payment_time": "2026-06-24T13:05:11+05:30",
      "bank_reference": "NA",
      "auth_id": "null",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3054",
          "netbanking_bank_name": "UCO Bank"
        }
      },
      "payment_group": "net_banking"
    },
    "customer_details": {
      "customer_name": "Sample Customer",
      "customer_id": "customer_001",
      "customer_email": "customer@example.com",
      "customer_phone": "9999999999"
    },
    "error_details": {
      "error_code": "GATEWAY_ERROR",
      "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
      "error_reason": "invalid_amount",
      "error_source": "cashfree",
      "error_subcode_raw": "U09"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": "1634766330",
      "gateway_payment_id": "1504280029",
      "gateway_settlement": "CASHFREE",
      "gateway_status_code": null
    },
    "payment_offers": null
  },
  "event_time": "2026-06-24T13:05:12+05:30",
  "merchant": {
    "merchant_id": "Merchant_business001_1782217071175"
  },
  "type": "PAYMENT_FAILED_WEBHOOK"
}

Payment user dropped webhook

A payment user dropped webhook notifies you when a customer abandons the payment flow before completing it. For example, the customer may leave the bank’s OTP page without entering the OTP or open a UPI app without entering the UPI PIN. Use this event to track incomplete payment attempts.

Sample payload

{
  "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 975672265,
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2026-06-24T13:10:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking"
    },
    "customer_details": {
      "customer_name": "Sample Customer",
      "customer_id": "customer_001",
      "customer_email": "customer@example.com",
      "customer_phone": "9999999999"
    }
  },
  "event_time": "2026-06-24T13:15:38+05:30",
  "merchant": {
    "merchant_id": "Merchant_business001_1782217071175"
  },
  "type": "PAYMENT_USER_DROPPED_WEBHOOK"
}

Partner payment webhooks use the same payload structure as merchant payment webhooks for the corresponding event and webhook version, with one additional top-level object: merchant. Its merchant_id field identifies the merchant associated with the payment, so you can route each event to the correct merchant in your platform.

"merchant": {
  "merchant_id": "Merchant_business001_1782217071175"
}

Partners and Platforms