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	✅	The checkout token obtained from the Zotlo Console. You can find this in your project's Developer Tools > Checkout SDK page.
packageId	✅	The ID of the package you want to use.
returnUrl	✅	The URL to redirect the user after payment completion.
subscriberId	❌	(Optional) Default subscriber ID for registration; can be an email, phone number, or UUID v4.
style	❌	Custom styling on config
customParameters	❌	Send custom parameters to webhooks
events	❌	Event listeners that can be used during the checkout process.
events.onLoad	❌	Triggered after the form is loaded.
events.onSubmit	❌	Triggered after the form is submitted.
events.onSuccess	❌	Triggered after a successful payment.
events.onFail	❌	Triggered when a payment fails.
events.onInvalidForm	❌	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. When you submit card form, you will receive form fields with values.

onSubmit?: (data?: Record<string, any>) => void;

{
  ...
  events: {
    onSubmit(data) {
      console.log('Form fields', data)
    }
  }
}

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
      ...
    }
  }
}