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., US).

otherOptions.api_key

string

(Required)

The API key generated in Zoho Payments.


let config = {
    "account_id": "23137556",
    "domain": "US",
    "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.

transaction_type

string

(Required)

The transaction type of the payment method, it can be either add or payment.

currency_code

string

(Required)

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

Show list of supported currencies

                          USDEURGBPINR
                          AUDCADJPYCNY
                          NZDSGDCHFSEK
                          NOKDKKZARHKD
                          MXNBRLRUBKRW
                          IDRMYRTHBPHP
                          VNDTRYPLNCZK
                          HUFILSSARAED
                          EGPPKRBDTLKR
                          NPRUAHKZTQAR
                          OMRKWDBHDJOD
                          NGNGHSARSCLP
                          COPPENUYUBOB
                          VESDZDMADTND
                          XOFXAFXCDXPF
                          MMKMNTLAKKHR
                          BTNMVRSCRSYP
                          SDGETBRWFBIF
                          ZMWZWLAOAMWK
                          MZNGNFDJFUGX
                          TZSLSLSZLGMD
                          SLLXDRFJDWST
                          TOPPGKVUVKYD
                          BBDTTDBSDHTG
                          JMDANGAWGSRD
                          GYDBZDBMDBAM
                          MADMDLMKDISK
                          GELAZNAMDKGS
                          TJSUZSMGAAOA
                        

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 or ach_debit. If no payment method is provided, payment methods that are enabled for your Zoho Payments account will be displayed.

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.

invoice_number

string

The invoice number associated with the payment.

response

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.

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


async function initiatePayment()
{
    try {
        let options = {
            "amount": "100.5",
            "transaction_type": "payment",
            "currency_code": "USD",
            "payments_session_id": "2000000012001",
            "currency_symbol": "$",
            "business": "Zylker",
            "description": "Purchase of Zylker electronics.",
            "invoice_number": "INV-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();


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


{
    "code": "error",
    "message": "Payment failed!"
}

Save a payment method using the following code.

options parameter

payment_method

string

(Required)

The payment method type, it can be either card or ach_debit.

transaction_type

string

(Required)

The transaction type of the payment method, it can be either add or payment.

customer_id

string

(Required)

The customer id for the payment method generated from the Customers API. Learn how to create a customer

payment_method_session_id

string

(Required)

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

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 of the customer, which will be prefilled in the checkout widget's email field.

address.address_line1

string

The address Line 1 of the customer's billing address, which will be prefilled in the checkout widget's address_line1 field.

address.address_line2

string

The address Line 2 of the customer's billing address, which will be prefilled in the checkout widget's address_line2 field.

address.city

string

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

address.state

string

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

address.country

string

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

address.postal_code

string

The postal code of the customer's billing address, which will be prefilled in the checkout widget's postal_code field.

response

After initiating the payment successfully, the checkout widget will return a response with the payment_method_id

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


async function saveCard()
{
  try {
    let options = {
      "payment_method": "card",
      "transaction_type": "add",
      "customer_id": '12345678',
      "payment_method_session_id": "2000000012001",
      "address": {
        "name": "Canon",
        "email": "canonbolt@zylker.com",
        "address_line1": "Address Line 1",
        "address_line2": "Address Line 2",
        "city": "City",
        "state": "State",
        "country": "Country",
        "postal_code": "123456"
      }
    };
    let data = await instance.requestPaymentMethod(options);
  } catch (err) {
    if (err.code != 'widget_closed') {
      // Handle Error
    }
  } finally {
    await instance.close();
  }
}
saveCard();


async function saveBankAccount()
{
  try {
    let options = {
      "payment_method": "ach_debit",
      "transaction_type": "add",
      "customer_id": '12345678',
      "payment_method_session_id": "2000000012001"
    };
    let data = await instance.requestPaymentMethod(options);
  } catch (err) {
    if (err.code != 'widget_closed') {
      // Handle Error
    }
  } finally {
    await instance.close();
  }
}
saveBankAccount();


{
    "payment_method_id": "2299000000189035",
    "message": "Payment method added successfully!"
}


{
    "code": "error",
    "message": "Error while adding payment method!"
}

Prerequisites

Integrate Widget

Instance Creation

config parameter

Initiate Payment

options parameter

response

Save Payment Method

options parameter

response