# Card Update SDK

The Card Update flow allows you to replace the payment card associated with an active subscription. This is useful when your application manages subscription states internally and you need to give users a secure way to update their billing details without exposing sensitive card data.

Only subscriptions paid with **credit cards** are eligible for card updates.\
One-time purchases are **not supported**.

## **Quick Start**

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

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

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

{% endcode %}

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

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

{% endcode %}

### 2. Import and Initialize

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

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

const cardUpdate = await ZotloCard({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  subscriberId: 'SUBSCRIBER_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: {},
  style: {
    design: {
      backgroundColor: '#f5f7fa'
    },
    success: {
      show: true,
      genericButton: {
        url: 'https://yourapp.com/dashboard'
      }
    }
  },
  events: {
    onSuccess(result) {},
    onFail(error) {}
  }
});
```

{% endcode %}

### 3. Mount to a DOM Element

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

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

{% endcode %}

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

```javascript
cardUpdate.mount('zotlo-card');
```

{% endcode %}

## Using via CDN

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

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

{% endcode %}

#### **Usage:**

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

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

<script>
  ZotloCard({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    subscriberId: 'SUBSCRIBER_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en'
  }).then(function (cardUpdate) {
    cardUpdate.mount('zotlo-card');
  });
</script>
```

{% endcode %}

## **Configuration Parameters**

These parameters define the configuration options for initializing the Card Update flow.

| Name                 | Required | Description                                                            |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| **token**            | Yes      | Checkout token from Zotlo Dashboard → Developer Tools → Checkout SDK   |
| **packageId**        | Yes      | ID of the subscription package whose card will be updated              |
| **subscriberId**     | Yes      | Subscriber identifier (email, phone number, or UUID v4)                |
| **returnUrl**        | No       | URL to redirect the user after 3DS authentication or after card update |
| **language**         | No       | Interface language (e.g. `en`, `tr`)                                   |
| **customParameters** | No       | Custom key-value parameters sent to webhooks                           |
| **style**            | No       | Custom styling configuration (see below)                               |
| **events**           | No       | Callback events for the update lifecycle                               |

## **Style Configuration**

#### **style.design**

Customize the UI appearance of the card update form.

| Field                  | Required | Description                                     |
| ---------------------- | -------- | ----------------------------------------------- |
| **backgroundColor**    | No       | Background color of the form                    |
| **showLabel**          | No       | Show/hide input labels (boolean)                |
| **adaptDarkMode**      | No       | Automatically adapt to browser dark mode        |
| **buttonColor**        | No       | Background color of primary button              |
| **buttonTextColor**    | No       | Text color of primary button                    |
| **buttonCornerRadius** | No       | Border radius of the main button (px)           |
| **footerFontSize**     | No       | Footer text font size (px)                      |
| **fontType**           | No       | Custom font family (e.g., Inter, Roboto, Arial) |

#### **style.success**

Success screen customization.

| Field                 | Required | Description                            |
| --------------------- | -------- | -------------------------------------- |
| **show**              | No       | Show success screen after card update  |
| **genericButton.url** | No       | Redirect URL for success action button |

{% hint style="info" %}
**Note:** When `success.show = false`, you must handle all redirects inside the `onSuccess` callback.
{% endhint %}

## **Event Listeners**

Events allow you to track user actions and customize the update flow.

#### **onLoad**

Triggered when the card update form is fully loaded.

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

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

{% endcode %}

#### **onSubmit**

Triggered when the form is submitted.

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

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

{% endcode %}

#### **onSuccess**

Triggered after a successful card update.

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

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

{% endcode %}

#### **onFail**

Triggered when the card update fails.

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

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

{% endcode %}

#### **onInvalidForm**

Triggered if the user submits the form with invalid fields.

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

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

{% endcode %}

## **Methods**

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

Renders the card update form.

#### **unmount()**

Removes the form from the DOM.

#### **refresh() → Promise**

Refreshes the card update form instance.

## **Notes & Best Practices**

* Only credit-card–based subscriptions support card updates.
* One-time purchases are *not* eligible.
* `returnUrl` is mainly for 3DS authentication.
* If you hide the success screen (`success.show: false`), redirect the user manually using `onSuccess`.