# Checkout SDK

The Zotlo Web Checkout SDK allows you to display a seamless checkout form inside your web application. Your users can complete their purchase without leaving your site, while Zotlo securely handles payment processing, subscription creation, and 3D Secure (3DS) authentication.

## **Quick Start**

### **1. Install the SDK**

{% code title="NPM" %}

```bash
npm install zotlo-checkout
```

{% endcode %}

{% code title="Yarn" %}

```bash
yarn add zotlo-checkout
```

{% endcode %}

### **2.** Import the SDK

```javascript
import 'zotlo-checkout/dist/zotlo-checkout.css';
import ZotloCheckout from 'zotlo-checkout';
```

### **3.** Initialize Checkout

```javascript
const checkout = await ZotloCheckout({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: {
    myCustomParam: 'OK!'
  },
  events: {
    onSuccess(result) {
      // Payment succeeded
    },
    onFail(error) {
      // Payment failed
    }
  }
});
```

### **4.** Mount Checkout Form

{% code title="HTML" %}

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

{% endcode %}

{% code title="JavaScript" %}

```javascript
checkout.mount('zotlo-checkout');
```

{% endcode %}

## Using via CDN

**UNPKG**

{% code title="HTML" %}

```html
<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>
```

{% endcode %}

**jsDelivr**

{% code title="HTML" overflow="wrap" %}

```html-derivative
<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>
```

{% endcode %}

#### **Usage Example**

{% code title="HTML" overflow="wrap" %}

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

<script>
  ZotloCheckout({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en',
    events: {
      onSuccess(result) {
        alert('Payment Success!');
      },
      onFail(error) {
        alert(error.message);
      }
    }
  }).then(function (checkout) {
    checkout.mount('zotlo-checkout');
  });
</script>
```

{% endcode %}

## **Configuration Parameters**

| Parameter                                           | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **token**                                           | Yes      | Checkout token from Zotlo Dashboard → Developer Tools → Checkout SDK                                                                                                                                                                                                                                                                                                                                                                                      |
| **packageId**                                       | Yes      | ID of the package to be purchased                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **returnUrl**                                       | Yes      | URL to redirect after payment or 3DS                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **subscriberId**                                    | No       | Prefilled subscriber identifier (email, phone, UUID v4)                                                                                                                                                                                                                                                                                                                                                                                                   |
| <p><strong>enableDiscountCodeEntry</strong><br></p> | No       | <p></p><p>Controls whether customers can enter a discount code on the payment form.</p><ul><li><code>true</code> → The <strong>"I have a discount code"</strong> field is displayed and customers can enter a code.</li><li><code>false</code> → The <strong>"I have a discount code"</strong> field is hidden and code entry is disabled.</li><li><code>null</code> → The <strong>Embedded Form settings in the Zotlo Panel</strong> are used.</li></ul> |
| **style**                                           | No       | Custom styling configuration                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **customParameters**                                | No       | Custom key-values sent to webhooks                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **events**                                          | No       | Event listeners during checkout lifecycle                                                                                                                                                                                                                                                                                                                                                                                                                 |

## **Event Listeners**

#### **onLoad**

{% code title="JavaScript" overflow="wrap" %}

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

{% endcode %}

#### onSubmit

{% code title="JavaScript" overflow="wrap" %}

```javascript
onSubmit?: () => void;
```

{% endcode %}

#### onSuccess

{% code title="JavaScript" overflow="wrap" %}

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

{% endcode %}

#### onFail

{% code title="JavaScript" overflow="wrap" %}

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

{% endcode %}

#### onInvalidForm

{% code title="JavaScript" overflow="wrap" %}

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

{% endcode %}

## **SDK Methods**

#### **mount(containerId: string)**

Embeds the checkout form into a DOM element.

#### **refresh()**

Reloads the form (e.g., after a style or language update).

#### **unmount()**

Removes checkout form from the DOM.

## **Branding & Styling**

You can override default styles configured in Zotlo Dashboard.

{% code title="JavaScript" overflow="wrap" %}

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

{% endcode %}

More details are available in `IZotloCheckoutStyle`.