## Zoho Payments Documentation Index

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

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

# Integrating Payment Method Widget

![](/payments/svg/cross.svg)

## Install Skills

Give your coding agents the context they need to build with Zoho Payments. [View documentation](/us/payments/developerdocs/agent-skills/)

`npx skills add https://www.zoho.com/payments/` ![](/payments/svg/copy-icon.svg)

**Note:** Skills-only installs don't receive automatic updates.  
Run `npx skills update -y` to get the latest version.

The payment method widget is an interface that lets your customers securely save their card and ACH bank account details for future transactions.

Here’s an outline of the end-to-end process for saving customer payment methods using Zoho Payments' payment method widget.

[![Payment Lifecycle](/us/payments/developerdocs/web-integration/Integrating-payment-method-widget-flow.png)](/us/payments/developerdocs/web-integration/Integrating-payment-method-widget-flow.png)

Follow the steps below to configure the payment method widget on your website.

*   [Establish Communication](#establish-communication)
*   [Create Customer](#create-customer)
*   [Create Payment Method Session](#generate-customer-id)
*   [Integrate Payment Method Widget](#payment-method-integration)
*   [Confirm Payment Method](#confirm-payment-method)
*   [Verify Payment Method Status](#verify-status)
*   [Collect Payments Using Saved Payment Methods](#make-a-payment)

## 1\. Establish Communication

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

## 2\. Create Customer

To save a customer’s payment method details, start by [creating a customer](https://www.zoho.com/us/payments/api/v1/customers/#create-customer "Create Customer"). To obtain the `customer_id`:

1.  Collect the customer’s details, including name and email (required), and optionally, phone and metadata (key-value pairs for additional info).
2.  Call the API with the [OAuth token generated](https://www.zoho.com/us/payments/api/v1/oauth/#overview "Generate OAuth") from your server.
3.  Provide your Zoho Payments `account_id` as a query parameter.

The API will return a `customer_id,` which you can use to create a payment method session. Refer to our [Create Customer API Doc](https://www.zoho.com/us/payments/api/v1/customer/#create-customer "Create Customer") for more details.

## 3\. Create Payment Method Session

After creating the customer, use the `customer_id` to call the Payment Method Session API.

The API will return a `payment_method_session_id`, which can be used to integrate payment method widget. Refer to our [Create a Payment Method Session API Doc](https://www.zoho.com/us/payments/api/v1/payment-method-session/#create-payment-method-session "Create a Payment Method Session") for more details.

## 4\. Integrate Payment Method Widget

After receiving the `payment_method_session_id` from your server, you can [invoke the widget](https://www.zoho.com/in/payments/api/v1/widget/#integrate-widget "Invoke Widget") on your website. To do so:

1.  Add the 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 > Settings > Developer Space._

Create Instance

Copy

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

3.  Invoke the `requestPaymentMethod()` function wit the `payment_method_session_id`. You can use the scripts provided below to securely save card or bank account details.

Save Card Details

Copy

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

**Note:**

You should obtain authorization from your customers to periodically debit their bank account for ACH payments. You can use the following template for authorization:

`By proceeding, you authorize {Business Name} to periodically debit funds from your account for ACH payments related to {Business Name}'s services or purchases. Any payments outside the regular debits will only be processed after obtaining your authorization. This authorization remains valid until revoked by contacting {Business' support email address}.`

Save Bank Account Details

Copy

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

Once integrated, the widget allows your customers to securely save their card and bank account details for future payments.

## 5\. Confirm Payment Method

Once the customer saves their payment method details, you can confirm it using the `requestPaymentMethod()` function. The function returns a response containing the `payment_method_id`, which can be used to track the payment method status. If an error occurs while saving the payment method, refer to the [error messages](/us/payments/developerdocs/errors/#payment-and-payment-method-errors "handle-errors") to identify and resolve the issue.

## 6\. Verify Payment Method Status

After receiving the `payment_method_id,` you can verify the payment method status using the [Retrieve Payment Method API](https://www.zoho.com/us/payments/api/v1/payments/#retrieve-payment-details "retrieve-payment-method"). This ensures that the payment method was securely saved. Based on the status returned (active, expired, blocked, processing, or, deleted), update your system.

## 7\. Collect Payments Using Saved Payment Methods

After a customer’s payment method is securely saved and verified, you can use it to collect future payments without requiring them to re-enter their details.

To do this, [create a new payment](https://www.zoho.com/us/payments/api/v1/payments/#create-payment "create a new payment") by passing the following parameters:

*   `customer_id`: The unique identifier of the customer
*   `payment_method_id`: The saved card or bank account to be charged
*   Payment details, such as `amount`, `currency`, and a `description`

Zoho Payments will then automatically process the payment using the saved card or bank account associated with the provided `payment_method_id`. The API will return a `payment_id` once the payment is completed.