## Zoho Payments Documentation Index

Access the complete documentation index at:
https://www.zoho.com/in/payments/llms.txt

Use this file to discover all available documentation pages before proceeding.

# Integrating Checkout Widget

The checkout widget is a payment interface that enables you to securely collect payments from customers on your website or application. With various payment options like cards, UPI, net banking, and bank transfer (early access), it ensures a smooth checkout experience for your customers. You can also set up UPI mandates and collect recurring payments. Check out our [API Docs](https://www.zoho.com/us/payments/api/v1/widget/#overview "API") for endpoint details and request examples.

**Insight:** If you’d like to test your widget integration and payment flows, you can use the Zoho Payments Sandbox environment. Refer to the [Sandbox help doc](https://www.zoho.com/in/payments/developerdocs/sandbox/setup/ "Sandbox") for more details. To enable, Zoho Payments sandbox [contact support.](https://www.zoho.com/in/payments/contact-us/ "Contact Us")

Follow the steps below to configure the checkout widget on your website.

*   [Establish Communication](#establish-communication)
*   [Create Payment Session](#payment-session-creation)
*   [Integrate Checkout Widget](#checkout-widget-integration)
*   [Confirm Payment](#confirm-payment)
*   [Verify Payment Status](#verify-status)

## 1\. Establish Communication

To communicate with our APIs and webhooks, you must first establish connectivity. Ensure that your setup allows or whitelists the Zoho Payments domain, **payments.zoho.in**.

## 2\. Create Payment Session

To initiate the payment process, you need to create a payment session on your server. Based on your payment type, you can create the session for one-time or recurring payments.

One-Time PaymentsRecurring Payments

#### Payment Session for One-time Payments

Call the [Payment Session Create API](/in/payments/api/v1/payment-session/#create-payment-session "payment-session") on your server, and follow the steps below to obtain the `payment_session_id`.

*   Collect payment information from the website (amount, currency, etc.).
*   Call the Payment Session Create API using the OAuth token generated from your server.
*   The API will return a `payment_session_id.`

Use this `payment_session_id` while integrating the checkout widget.

**Note:**

Each session allows up to five payment attempts, but only one can be successful. Once a payment attempt is successful, no further attempts can be made within that session. Any additional attempts will result in an `invalid_payment_session` error. To make more payment attempts, a new session must be created.

#### Create Customer

Collect customer details (name, email, phone, and metadata) and call the [Create Customer API](https://www.zoho.com/in/payments/api/v1/mandates/#create-customer "Create Customer") using the OAuth token.

The API will return a `customer_id,` which you can use to initiate a payment session for mandate enrollment.

#### Create Payment Session for Mandate Enrollment

Call the [Create Payment Session for Mandate Enrollment API](https://www.zoho.com/in/payments/api/v1/mandates/#create-payment-session-mandate-enrollment "Mandate Enrollment") on your server using an OAuth token to obtain a `payment_session_id.`

**Note:** Each session allows up to three payment attempts, but only one can succeed. Any additional attempts return an `invalid_payment_session` response.

Use the `payment_session_id` when integrating the checkout widget.

## 3\. Integrate Checkout Widget

After receiving the `payment_session_id` from your server, you can [invoke the checkout widget](https://www.zoho.com/in/payments/api/v1/widget/#integrate-widget "Invoke Widget") on your website. Zoho Payments' script helps you manage the payment flow easily.

1.  Add the Zoho Payments script given below to your website or application.

zpayments.js

Copy

```javascript
<script src="https://static.zohocdn.com/zpay/zpay-js/v1/zpayments.js"></script>
```

2.  Initialise the script using the API key generated from Zoho Payments' Developers Space.

Create Instance

Copy

```javascript
let config = {
  account_id: "23137556",
  domain: "IN",
  otherOptions: {
    api_key:
      "1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
  },
};
let instance = new window.ZPayments(config);
```

**Note:** Once initialized, reuse the same widget instance across your application wherever it is required.

**Insight:** If you’re using sandbox, set `otherOptions.is_test_mode` to `true` in the config object. Refer to the [Sandbox developer doc](https://www.zoho.com/in/payments/developerdocs/sandbox/setup/#Widget-Integration "Web") for more details.

3.  Invoke the `requestPaymentMethod()` function with `payment_session_id` to initiate the payment.

Initiate Payment

Copy

```javascript
async function initiatePayment() {
  try {
    let options = {
      amount: "100.5",
      currency_code: "INR",
      payments_session_id: "2000000012001",
      currency_symbol: "₹",
      business: "Zylker",
      description: "Purchase of Zylker electronics.",
      invoice_number: "INV-12345",
      reference_number: "REF-12345",
      address: {
        name: "Canon",
        email: "canonbolt@zylker.com",
        phone: "98XXXXXXXX",
      },
    };
    let data = await instance.requestPaymentMethod(options);
  } catch (err) {
    if (err.code != "widget_closed") {
      // Handle Error
    }
  } finally {
    await instance.close();
  }
}
initiatePayment();
```

Once the checkout widget is integrated, you can collect payments, gather transaction details such as amount, currency, and customer information, and verify the payment status. You verify the payment status using the `payment_id` provided from the server after the customer completes the payment.

## 4\. Confirm Payment

Once the customer completes the payment, the `requestPaymentMethod()` function returns a response that includes the `payment_id`, and for recurring payments, both the `payment_id` and `mandate_id`. Use the parameters returned by the widget to [verify the signature](/in/payments/developerdocs/signature-verification/#widget-response "Signature") and ensure the transaction data is authentic.

**Note:** In some cases, you may not receive the `payment_id` if the customer accidentally closes the widget before a response is returned. In such cases, use your configured webhooks or the `payment_session_id` to retrieve the payment status.

These IDs can be used to track the payment and mandate status. If a payment fails due to issues like payment errors or user cancellations, refer to the [error messages](/in/payments/developerdocs/errors/ "handle-errors") to identify and resolve the issue.

## 5\. Verify Payment Status

You can verify your payment status in three ways:

*   **Verify via Widget Response:** After receiving the `payment_id`, verify the payment status using the [Payment Retrieve API](/in/payments/api/v1/payments/#retrieve-payment "Retrieve API"). For recurring payments, use the [Retrieve Mandate API](https://www.zoho.com/in/payments/api/v1/mandates/#retrieve-mandate "Retrieve Mandate") to check specific mandates. Based on the status returned (success, failure, or pending), update your system.
    
*   **Verify via Webhooks:** Use your [configured webhooks](/in/payments/developerdocs/webhooks/configure/ "configure-webhooks") for the events **payment.success** and **payment.failed** to receive the final payment status directly.
    
*   **Verify via Session ID:** If you haven’t received the payment status via the widget response or webhooks, use the [Payment Session Retrieve API](https://www.zoho.com/in/payments/api/v1/payment-session/#retrieve-payment-session "Session") to verify the payment result.
    

**Note:** Ensure that all three options are configured for reliable payment verification.