Skip to main content
Use this page with the Agent Elements SDK guide, which explains the flows and how to handle each event.
The SDK runs in the browser, in the host page. The Clink-hosted iframe handles cards, credentials, and 3DS; the host receives identifiers and events only.

Install

new AgentElements(options)

Creates the SDK instance and resolves the Clink app address for the environment.
'sandbox' | 'production'
required
Which Clink app address to use. See Environment mapping.
PresetOptions
Appearance and locale settings. See Preset options.

Preset options

'en-US' | 'zh-CN'
default:"en-US"
UI language and antd locale.
string
default:"#1677ff"
Component primary color, as a CSS color value.
number
default:"8"
Corner radius for components, in px.
number
default:"8"
Corner radius for the card container, in px.
Preset options are applied when the SDK sends init. setLocale updates the language at runtime; the color and radius options cannot change after construction.

Element credentials

Credentials are passed per element when calling createElement:
string
required
A card-session token issued by your server (scope card:manage, 1799s). Required and non-empty; held in memory only.
string
required
A server-issued one-time session id (valid for about 30 minutes). The element exchanges it for a vault token; the host never holds that token.

Methods

AgentElement<T>
Creates the element for type with its credentials: paymentMethods takes { token }, vault takes { vaultId }. An instance can create one element; a second call throws, and missing or empty credentials throw. The element is not rendered until mount() is called.
void
Updates the locale. Before mount, it is sent with the next init. After mount, the iframe receives set-locale immediately.
void
Unmounts the element, closes any open 3DS overlay, removes message listeners, and clears event subscriptions. Idempotent. The instance cannot be reused; createElement and setLocale throw after destroy().

Errors

AgentElement

An element is created by createElement and owns its event subscriptions.
ElementType
The element type: 'paymentMethods' or 'vault'.
void
paymentMethods only. Updates the element’s card-session token: before mount, it is sent with the next init; after mount, the iframe receives set-token and reloads its card data. An empty value throws. The vault credential is a one-time vaultId and cannot be refreshed.
void
Subscribes to one of the element’s events. Register before mount() so no event is missed.
void
Removes a subscription.
void
Mounts the iframe. target is a CSS selector or an HTMLElement. The container must exist. See Mount options.
void
Removes the wrapper and iframe. Event subscriptions are kept, so the element can be mounted again. A remount reloads the iframe.
HTMLIFrameElement | null
Returns the current iframe, or null while unmounted.

Mount options

Display switches and primary button styling passed to mount(). They are applied to the next mount only. The option type depends on the element type, so passing a field the element does not support fails at compile time.

paymentMethods

boolean
default:"false"
Hides the loading skeleton.
boolean
default:"false"
Hides the saved-card list.
boolean
default:"false"
Hides delete actions.
boolean
default:"false"
Hides the set-default action.
AgentElementButtonOptions
Appearance of the primary action button. See Button options.

vault

boolean
default:"false"
Hides the loading skeleton.
boolean
default:"false"
Hides the “Select a card” title and subtitle.
AgentElementButtonOptions
Appearance of the primary action button. See Button options.
Mount options are display flags, not secrets. The SDK serializes them onto the iframe URL; do not put tokens or other sensitive values there.

Button options

The primary action button is the “Add card”, “Unlock card”, or “Continue” button at the bottom of the element.
number
default:"40"
Button height, in px.
number
default:"16"
Button font size, in px.
number
default:"presetOptions.radius.components"
Button corner radius, in px.
Fields you leave out keep their defaults, so a host that only needs a taller button can pass height alone. Values that are not numbers or fall outside the supported range (height 16–200, font size 8–40, radius 0–100) are ignored. List action buttons (set default, delete) and retry buttons are not affected.

Events

Events are scoped to the element. The event name and payload are inferred from the element type.

paymentMethods events

vault events

error.source: Subscriptions survive unmount() and are cleared only by destroy().

Environment mapping

environment is required: use sandbox (UAT) while integrating and production after go-live.

Module exports

version is injected at build time. When the SDK is used directly from source, it reports 0.0.0-dev.

Types

Package formats

The package has no CommonJS build. The internal iframe bridge is bundled into the output, so the published package has no private runtime dependency.

Script tag

When loaded with a <script> tag, the SDK is exposed on the ClinkAgentElements global. Pin @<version> to a concrete version in production.