# Zotlo Checkout
[![Publish Package to npm](https://github.com/Zotlo/zotlo-checkout/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/Zotlo/zotlo-checkout/actions/workflows/main.yml)

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
```bash
npm install --save-dev zotlo-checkout@latest
```

#### yarn
```bash
yarn add -D zotlo-checkout@latest
```

### Initialize Checkout
```javascript
import 'zotlo-checkout/dist/zotlo-checkout.css';
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:

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

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

**unpkg**
```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>
```

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

#### Usage example

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

| Name                    | 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      | Triggers after form 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.onOfferFail`    | no      | Triggered when a post payment offer request fails.                                                                           |
| `events.onInvalidForm`  | no      | Triggers when form has an invalid field.                                                                                     |
| `events.onError`        | no      | Triggers when pre-init errors occurs.                                                                                        |

**Note:** For more details, please visit [types.ts](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L100) file.

### Custom Parameters
Besides sending arbitrary parameters, you can associate your UTM data with the subscriber by passing a `utmData` object under `customParameters`:
```js
{
  ...
  customParameters: {
    mySpecialParameter: 'done',
    utmData: {
      utmCampaign: "utm_campaign",
      utmMedium: "utm_medium",
      utmSource: "utm_source",
      utmTerm: "utm_term",
      utmContent: "utm_content"
    },
  }
  ...
}
```

## Events
Please view [`IZotloCheckoutEvents`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L77) for full details on [src/lib/types.ts](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L77) file.

### onLoad
Triggers after form loaded.

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

**Note:** You can see `params` details on type [`IFormLoad`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L827)

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

### onSubmit
Triggers after the form is submitted.

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

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

### onSuccess
Triggers after a successful payment.

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

**Note:** You can see `result` details on type [`PaymentDetail`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L766)

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

### onFail
Triggers when a payment fails.

```typescript
onFail?: (error: FailEventData) => void;
```
**Note:** You can see `error` details on type [`FailEventData`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L159)

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

### onOfferFail
Triggers when a post payment offer request fails. `error.data` holds the offer the decision was sent for.

```typescript
onOfferFail?: (error: FailEventData) => void;
```
**Note:** You can see `error` details on type [`FailEventData`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L159) and the offer on type [`OffersObject`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L746)

```typescript
{
  ...
  events: {
    onOfferFail(error) {
      alert(error.message)
      console.log('Post payment offer failed to process:', error.data.offerId)
    }
  }
}
```

### onInvalidForm
Triggers when form has an invalid field.

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

**Note:** You can see `error` details on type [`IFormInvalid`](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L838)


```typescript
{
  ...
  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.
```typescript
checkout.mount(containerId: string);
```

### refresh
Refreshes the form.
```typescript
checkout.refresh(): Promise<void>;
```

### unmount
Removes the form and deletes it from the DOM.
```typescript
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](https://console.zotlo.com) will apply by default.

**Note:** For more details, please check `IZotloCheckoutStyle` on [types.ts](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L55) file.

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


## Zotlo Card
Update the card information associated with a user's subscription using Zotlo Card.

### Initialize Card Update
```javascript
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:

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

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

**unpkg**
```html
<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**
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zotlo-checkout@latest/dist/zotlo-checkout.css" />
<script src="https://cdn.jsdelivr.net/npm/zotlo-checkout@latest/dist/zotlo-card.min.js"></script>
```

#### Usage example

```html
<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
These parameters specify the parameters and descriptions used in the Zotlo Card.

| Name                      | 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.                                                                                       |
| `subscriberId`            | **yes**  | Default subscriber ID for card update; can be an email, phone number, or UUID v4.                                            |
| `returnUrl`               | no.      | The URL to redirect the user after card update completion.                                                                   |
| `enableDiscountCodeEntry` | no       | Allow users to enter discount code on form.                                                                                  |
| `style`                   | no       | Custom styling on config                                                                                                     |
| `customParameters`        | no       | Send custom parameters to webhooks                                                                                           |
| `events`                  | no       | Event listeners that can be used during the update process.                                                                  |
| `events.onLoad`           | no       | Triggers after form loaded.                                                                                                  |
| `events.onSubmit`         | no       | Triggered after the form is submitted.                                                                                       |
| `events.onSuccess`        | no       | Triggered after a successful update.                                                                                         |
| `events.onFail`           | no       | Triggered when a update fails.                                                                                               |
| `events.onInvalidForm`    | no       | Triggers when form has an invalid field.                                                                                     |
| `events.onError`          | no       | Triggers when pre-init errors occurs.                                                                                        |

**Note:** For more details, please visit [types.ts](https://github.com/Zotlo/zotlo-checkout/blob/master/src/lib/types.ts#L843) file.