Using the Zotlo Checkout SDK

Learn about Zotlo Checkout SDK

Zotlo Checkout SDK allows you to embed a secure payment form directly into your website, providing your customers with a seamless checkout experience without leaving your site.

Quick Start

Installation

Add the zotlo-checkout package to your project: npm

npm install zotlo-checkout

yarn

yarn add -D zotlo-checkout

Import the SDK

import 'zotlo-checkout/dist/zotlo-checkout.css'; // Required stylesheet
import ZotloCheckout from 'zotlo-checkout';

Initialize Checkout

const checkout = await ZotloCheckout({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: { // Optional
    myCustomParam: 'OK!'
  },
  events: {
    onSuccess(result) {
      // Handle success here
    },
    onFail(error) {
      // Handle fails here
    }
  }
});

// Render form whenever you want
checkout.mount('zotlo-checkout')

Note: The string 'zotlo-checkout' passed to mount is the id of the DOM element where the form will be embedded, for example:

<div id="zotlo-checkout"></div>

Using via CDN

You can also include Zotlo Checkout SDK directly in the browser using CDN links:

unpkg:

<link rel="stylesheet" href="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.min.js"></script>

jsDelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-checkout.min.js"></script>

Usage example:

<div id="zotlo-checkout"></div>

<script>
  ZotloCheckout({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en',
    customParameters: { // Optional
      myCustomParam: 'OK!'
    },
    events: {
      onSuccess(result) {
        // Handle success here
      },
      onFail(error) {
        // Handle fails here
      }
    }
  }).then(function (checkout) {
    checkout.mount('zotlo-checkout');
  })
</script>

Parameters

These parameters specify the parameters and descriptions used in the Zotlo Checkout SDK.

Parameter	Required	Description
token	Yes	The checkout token obtained from the Zotlo Console. You can find this in your project's Developer Tools > Checkout SDK page.
packageId	Yes	The ID of the package you want to use.
returnUrl	Yes	The URL to redirect the user after payment completion.
subscriberId	No	(Optional) Default subscriber ID for registration; can be an email, phone number, or UUID v4.
style	No	Custom styling on config
customParameters	No	Send custom parameters to webhooks
events	No	Event listeners that can be used during the checkout process.
events.onLoad()	No	Triggered after the form is loaded.
events.onSubmit()	No	Triggered after the form is submitted.
events.onSuccess()	No	Triggered after a successful payment.
events.onFail()	No	Triggered when a payment fails.
events.onInvalidForm()	No	Triggers when form has an invalid field.

Events

Please view IZotloCheckoutEvents for full details on src/lib/types.ts file.

onLoad

Triggers after form loaded.

onLoad?: (params: IFormLoad) => void;

Note: You can see params details on type IFormLoad

{
  ...
  events: {
    onLoad(params) {
      // Update page bg color by form bg color
      document.body.style.backgroundColor = params.backgroundColor;
    }
  }
}

onSubmit

Triggers after the form is submitted.

onSubmit?: () => void;

{
  ...
  events: {
    onSubmit() {
      console.log('Form submitted')
    }
  }
}

onSuccess

Triggers after a successful payment.

onSuccess?: (result: PaymentDetail) => void;

Note: You can see result details on type PaymentDetail

{
  ...
  events: {
    onSuccess(result) {
      const emailEl = document.getElementById('email')
      emailEl.innerText = result.client.subscriberId;
      alert('Success done!');
    }
  }
}

onFail

Triggers when a payment fails.

onFail?: (error: FailEventData) => void;

Note: You can see error details on type FailEventData

{
  ...
  events: {
    onFail(error) {
      alert(error.message)
    }
  }
}

onInvalidForm

Triggers when form has an invalid field.

onInvalidForm?: (error: IFormInvalid) => void;

Note: You can see error details on type IFormInvalid

{
  ...
  events: {
    onInvalidForm(error) {
      alert('Invalid field:', error.name)
    }
  }
}

Methods

User methods available after Checkout is started:

mount

Renders the Checkout form to the specified DOM element.

checkout.mount(containerId: string);

refresh

Refreshes the form.

checkout.refresh(): Promise<void>;

unmount

Removes the form and deletes it from the DOM.

checkout.unmount();

Styling

You can customize your form on config with style parameter. If you do not define any parameters, the settings made in the Zotlo Console will apply by default.

Note: For more details, please check IZotloCheckoutStyle on types.ts file.

{
  ...
  style: {
    design: {
      theme: 'mobileapp',
      borderWidth: 2,
      backgroundColor: '#CCCCCC',
      ...
    },
    success: {
      show: true,
      waitTime: 20
      ...
    }
  }
}

Card Update

This method allows you to update the credit card information used for subscription purchases made by your users with credit card as the payment method.

The Update Card method is meaningful when you manage subscription lifecycle on your own system. It enables you to securely update the credit card associated with an existing subscription via Zotlo Card.

Important Notes

• Applicable only to subscriptions paid with credit cards.

• Not supported for one-time purchases.

• The subscription must be active and created using Credit Card payment method.

When this method is called, the credit card information linked to the user’s subscription is updated, and all future renewal payments will be charged to the new card.

Initialize Card Update

import 'zotlo-checkout/dist/zotlo-checkout.css';
import ZotloCard from 'zotlo-checkout/card';

// Initialize card update
const cardUpdate = await ZotloCard({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  subscriberId: 'SUBSCRIBER_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: { // Optional
    myCustomParam: 'OK!'
  },
  style: {
    design: {
      backgroundColor: '#f5f7fa'
    },
    success: {
      show: true,
      genericButton: {
        url: 'https://myfancy.site/dashboard' // This is required
      }
    }
  },
  events: {
    onSuccess(result) {
      // Handle success here
    },
    onFail(error) {
      // Handle fails here
    }
  }
});

// Render form whenever you want
cardUpdate.mount('zotlo-card')

Note: The string 'zotlo-card' passed to mount is the id of the DOM element where the form will be embedded, for example:

<div id="zotlo-card"></div>

Using via CDN

You can also include Zotlo Card directly in the browser using CDN links:

unpkg

<link rel="stylesheet" href="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://unpkg.com/zotlo-checkout/dist/zotlo-card.min.js"></script>

jsdelivr

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-card.min.js"></script>

Usage example

<div id="zotlo-card"></div>

<script>
  ZotloCard({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    subscriberId: 'SUBSCRIBER_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en',
    customParameters: { // Optional
      myCustomParam: 'OK!'
    },
    style: {
      design: {
        backgroundColor: '#f5f7fa'
      },
      success: {
        show: true,
        genericButton: {
          url: 'https://myfancy.site/dashboard' // This is required
        }
      }
    },
    events: {
      onSuccess(result) {
        // Handle success here
      },
      onFail(error) {
        // Handle fails here
      }
    }
  }).then(function (cardUpdate) {
    cardUpdate.mount('zotlo-card');
  })
</script>

Parameters

The following parameters define the configuration options and behaviors for the Zotlo Card – Update Card flow.

Name	Required	Description
token	Yes	The checkout token obtained from the Zotlo Console. You can find this in your project under Developer Tools → Checkout SDK.
packageId	Yes	The ID of the subscription package associated with the card update.
subscriberId	Yes	The unique identifier of the subscriber whose card will be updated. Can be an email address, phone number, or UUID v4.
returnUrl	No	The URL to which the user is redirected after the card update process is completed.
style	No	Custom styling configuration for the update card form.
style.design.backgroundColor	No	Sets the background color of the update card form.
style.design.showLabel	No	Determines whether field labels are displayed on the form. Set to true to show labels, false to hide them.
style.design.AdaptDarkMode	No	Enables automatic adaptation to dark mode style. When enabled, the form adjusts colors accordingly.
style.design.buttonColor	No	Sets the background color of the primary button. Accepts any valid CSS color value.
style.design.buttonTextColor	No	Sets the text color of the primary action button.
style.design.buttonCornerRadius	No	Defines the border radius of the primary button in pixels. Used to control button roundness.
style.design.footerFontSize	No	Sets the font size of the footer text (e.g. legal text or branding) in pixels.
style.design.fontType	No	Defines the font family used throughout the form (e.g. Arial, Inter, Roboto).
style.success.show	No	Determines whether the success screen is displayed after a successful card update.
style.success.genericButton.url	No	Specifies the URL that the generic button on the success screen redirects to when clicked.
customParameters	No	Custom key-value parameters that will be sent to webhooks.
events	No	Event listeners that can be used to track different stages of the update process.
events.onLoad()	No	Triggered after the update card form is fully loaded.
events.onSubmit()	No	Triggered when the update card form is submitted.
events.onSuccess()	No	Triggered after the card information is successfully updated.
events.onFail()	No	Triggered when the card update process fails.
events.onInvalidForm()	No	Triggered when the form contains one or more invalid fields.

Notes

In the card update flow, handling success and error scenarios is the responsibility of the integrator. Therefore, it is recommended to manage user redirections and notifications using callback events such as onSuccess and onFail.

The returnUrl parameter is typically used to redirect the user back to your application or website after a 3D Secure (3DS) authentication flow. This parameter does not automatically display a success or error page.

If the style.success.show option is disabled (false), no default success screen is shown after a successful card update. In this case, the redirection after a successful operation must be handled manually within the onSuccess callback.

Similarly, error scenarios should be handled using the onFail callback, where appropriate error messaging and user flow control can be implemented.