Integrate Payment Method Widget | Developer Docs

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.

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

Establish Communication
Create Customer
Create Payment Method Session
Integrate Payment Method Widget
Confirm Payment Method
Verify Payment Method Status

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. To obtain the customer_id:

Collect the customer’s details, including name and email (required), and optionally, phone and metadata (key-value pairs for additional info).
Call the API with the OAuth token generated from your server.
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 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 for more details.

4. Integrate Payment Method Widget

After receiving the payment_method_session_id from your server, you can invoke the widget on your website. To do so:

Add the script given below to your website or application.

zpayments.js

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

Initialise the script using the API key generated from Zoho Payments > Settings > Developer Space.

Create Instance

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

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

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

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 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. This ensures that the payment method was securely saved. Based on the status returned (active, expired, blocked, processing, or, deleted), update your system.

Integrating Payment Method Widget