Skip to main content

Widget Integration

This guide provides step-by-step instructions for integrating the widget into your application. By following these steps, you can enable your customers to make cryptocurrency payments using their Globiance app wallet or other blockchain address methods.

Before you begin the integration process, ensure that you have the following prerequisites:

  • Access to the source code of your application.
  • An API key from Globiance to authenticate your widget requests.

Step 1: Include the Widget Script​

Include the widget payment script in your application. Place the following <script> tag in the <head> section of your HTML code or before the closing </body> tag.

Copy code
<script src="https://cdn.globiance.com/widget/latest/widget.js"></script>
This script will load the necessary widget functionality into your application.

Step 2: Trigger the Widget on Button Click​

To initiate the widget and enable users to make payments, you need to add a button to your application. On the button's click event, trigger the window.Start(payload) function and pass the required attributes as the payload to the widget.

The payload can follow two different flows:

  1. Standard Flow (Items Array):

    • The merchant passes an array of items.
    • The payload includes details about each item.

  2. Dynamic Form Flow (Pages Array):

    • The merchant passes an array of pages.
    • Each page represents a step in the payment process, with customizable fields.

Standard Flow​

In the standard flow, the payload includes an array of items that the customer is purchasing. Here are the attributes to include:

  • apikey (required: true, default: null):
    • Your API key obtained from Globiance.
  • amount (required: true, default: null):
    • The amount to be paid by the customer.
  • currency (required: true, default: "USD"):
    • The currency in which the payment should be processed` (e.g., "USD", "EUR").
  • note (required: false, default: null):
    • An optional note or description for the payment.
  • itemName (required: false, default: null):
    • The name of the Order against which the checkout is created.
  • clientId (required: false, default: null):
    • An identifier for the client initiating the payment from the merchant system.
  • itemId (required: false, default: null):
    • An identifier for the Order from the merchant system.
  • language (required: false, default: "en"):
    • The language to be used in the widget interface` (e.g., "en", "de", "fr").
  • theme (required: false, default: "light"):
    • An optional parameter to customize the widget's appearance.
  • items (required: true, default: null):
    • Array of items included in the Order.

Example:

function handlePayment() {
  const payload = {
    apikey: 'YOUR_API_KEY',
    amount: 100.0,
    currency: 'USD',
    note: 'Payment for Widget Purchase',
    itemName: 'YOUR_ORDER_NAME',
    clientId: 'YOUR_CLIENT_ID',
    itemId: 'YOUR_ORDER_ID',
    language: 'en',
    theme: 'light',
    items: [
      {
        itemName: "Test Item",
        price: 50,
        qty: 5,
        taxRate: 1.5
      }
    ]
  };

  window.Start(payload);
}

// Attach the click event listener to your button
const paymentButton = document.getElementById('paymentButton');
paymentButton.addEventListener('click', handlePayment);

Dynamic Form Flow​

In the dynamic form flow, the payload includes an array of pages. Each page can have multiple customizable fields and can include up to three steps:

  1. Payment Details (required)
  2. Customer Details (optional)
  3. Shipping Details (optional)

Example:

function handlePayment() {
  const payload = {
    apikey: 'YOUR_API_KEY',
    note: '',
    pages: [
      {
        pageTitle: "Amount Details",
        fields: [
          {
            type: "fixed-amount",
            disabled: true,
            value: "44000",
            label: "Platinum Package",
            mandatory: false,
            fieldType: "amount",
          }
        ],
      },
      {
        pageTitle: "Customer Details",
        fields: [
          {
            type: "text",
            disabled: false,
            label: "Full Name",
            mandatory: true,
            defaultValue: "",
            fieldType: "input",
          },
          {
            type: "text",
            disabled: false,
            label: "Email",
            mandatory: true,
            defaultValue: "",
            fieldType: "input",
          },
          {
            type: "text",
            disabled: false,
            label: "Mobile Number",
            mandatory: false,
            fieldType: "input",
          },
          {
            type: "text",
            disabled: false,
            label: "Company Name",
            mandatory: false,
            defaultValue: "",
            fieldType: "input",
          }
        ],
      }
    ],
    language: 'en',
    theme: 'dark',
    currency: 'USD',
    itemName: 'Platinum Package',
    mode: 'form'
  };

  window.Start(payload);
}

// Attach the click event listener to your button
const paymentButton = document.getElementById('paymentButton');
paymentButton.addEventListener('click', handlePayment);

Pages Array Structure​

Each Pages Array contains a title representing the specific step and a field array (Inputs). The fields are primarily of two types:

  • Amount
  • Information

Amount​

The entries in the Amount fields will be summed up to determine the total amount the user has to pay. The Amount fields can be of three types:

  • qty-selector: Users select the quantities of products they wish to purchase.
  • custom-amount: Users can enter an amount themselves, useful for tips or donations.
  • fixed-amount: The amount is predefined by the merchant and cannot be edited by the user.

Information​

In the Information fields, merchants can collect user information, such as personal details or shipping information. The following fields can be used for this purpose:

  • text
  • textarea
  • dropdown
  • radio

Summary​

  • Standard Flow: Use when passing a static list of items.
  • Dynamic Form Flow: Use when needing a customizable, multi-step form for user input.

Make sure to replace placeholders like 'YOUR_API_KEY', 'YOUR_CLIENT_ID', and 'YOUR_ORDER_ID' with actual values provided by Globiance.

By following these updated steps, you'll be able to integrate the widget seamlessly and provide your customers with a versatile payment experience. If you have any questions or need further assistance, please reach out for support.