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

NPM

npm install zotlo-checkout

Yarn

yarn add zotlo-checkout

2. Import and Initialize

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) {}
  }
});

3. Mount to a DOM Element

HTML

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

JavaScript

cardUpdate.mount('zotlo-card');

Using via CDN

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>

Usage:

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>

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

Note: When success.show = false, you must handle all redirects inside the onSuccess callback.

Event Listeners

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

onLoad

Triggered when the card update form is fully loaded.

JavaScript

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

onSubmit

Triggered when the form is submitted.

JavaScript

onSubmit?: () => void;

onSuccess

Triggered after a successful card update.

JavaScript

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

onFail

Triggered when the card update fails.

JavaScript

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

onInvalidForm

Triggered if the user submits the form with invalid fields.

JavaScript

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

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.