Checkout Widget

The Checkout widget in Zoho Payments provides a streamlined and secure way to facilitate payments directly on your website. Use the Checkout Widget APIs to embed the widget on your website and collect payments.

Prerequisites

An active Zoho Payments account.
An API Key. You can view or generate the API Key under
Zoho Payments > Settings > Developer Space.

Note: Only users with Account Owner, Admin, or Developer roles in Zoho Payments can generate and view API keys.

To use Zoho Payments' checkout widget in your application, add this script to your webpage.


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

Create an instance for Zoho Payments using the following parameters:

config parameter

account_id

string

(Required)

The Zoho Payments account ID.

domain

string

(Required)

The edition of Zoho Payments you are using. This is represented by a 2-letter country code (e.g., IN).

otherOptions.api_key

string

(Required)

The API key generated in Zoho Payments.

Using the Sandbox? Set otherOptions.is_test_mode to true in the config object. Refer to Web Integration for Sandbox for more details.


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

Initiate a payment using the following code.

options parameter

amount

string

(Required)

The payment amount, it can be any non-negative value.

currency_code

string

(Required)

Currency of the payment amount, represented by a 3-letter currency code (e.g., INR).

payments_session_id

string

(Required)

The Payment Session ID is a unique identifier created for each payment session. Learn how to create a payment session.

description

string

(Required)

A description of the payment, which will be displayed in the checkout widget's header.

currency_symbol

string

The currency symbol corresponding to the payment, such as ₹.

business

string

Business Name of the merchant, which will be displayed in the checkout widget's header.

payment_method

string

The default payment method to be displayed in the checkout widget. It can be card, upi, and net_banking. If no payment method is provided, all options will be displayed by default.

address.name

string

The name of the customer or cardholder, which will be prefilled in the checkout widget's name field.

address.email

string

The email address of the customer, which will be prefilled in the checkout widget's email field.

address.phone

string

The phone number of the customer, which will be prefilled in the checkout widget's phone number field. Format: +<country_code><phone_number>. If the country code is omitted, the number will be assumed to be an Indian number by default.

invoice_number

string

The invoice number associated with the payment.

reference_number

string

The reference number for the payment. The maximum length can be 50 characters.


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": "+91XXXXXXXXXX"
            }
        };
        let data = await instance.requestPaymentMethod(options);
    } catch (err) {
        if (err.code != 'widget_closed') {
            // Handle Error
        }
    } finally {
        await instance.close();
    }
}   
 initiatePayment();

After initiating the payment successfully, the checkout widget will return a response with the payment_id and a signature. The signature will be included only if you've generated a signing key under Settings > Developer Space.

Note: For recurring payments, the mandate_id will be returned in the response along with the payment details. To set up recurring payments, refer to the API Document for Mandates.

Refer to our developer documentation for detailed instructions on integrating the checkout widget.


{
    "payment_id": "2299000000189035",
    "signature": "7b825220c0fac6dbed0df247c290b55b607c8f0c977686edc7e2ed733134a317",
    "message": "Payment successful!"
}


{
    "payment_id": "2299000000189035",
    "mandate_id": "2299000000189037",
    "signature": "7b825220c0fac6dbed0df247c290b55b607c8f0c977686edc7e2ed733134a317",
    "message": "Payment successful!"
}


{
    "code": "session_expired",
    "message": "Payment could not be processed after multiple attempts. Please refresh the page and initiate the payment again."
}


{
    "code": "session_expired",
    "message": "Payment could not be processed after multiple attempts. Please refresh the page and initiate the payment again."
},
{
    "code": "invalid_payment_session",
    "message": "Payment session is invalid or expired. Please refresh the page and initiate the payment again."
},
{
    "code": "widget_closed",
    "message": "Checkout widget closed by user"
},
{
    "code": "paymentmethods_validation",
    "message": "Online payments are not enabled by your merchant. Please contact merchant to enable this option."
},
{
    "code": "widget_validation_error",
    "message": "Something went wrong and it looks like a temporary glitch. Please try again in some time."
}

Prerequisites

Integrate Widget

Instance Creation

config parameter

Initiate Payment

options parameter

Widget Response