Skip to main content
@clink-ai/agent-elements embeds Clink’s wallet card UI inside a host application. The host server issues credentials per element type, and the frontend creates one element and mounts it into a container. Card forms, card data, and 3DS all live in the Clink-hosted iframe, so the host page never handles card data.
Pin the @clink-ai/agent-elements version in production. For every option and method, see the SDK reference.

The full chain

Agent Elements replaces only the frontend card UI. Credentials must still be issued by your server, because obtaining them requires the client secret Clink assigned to you. Never send the client secret or portal token from step 2 to the browser. The frontend receives exactly one of two things: a card-session token for paymentMethods, or a vaultId for vault.

Who owns what

1. Server: issue element credentials

The two elements get their credentials from different endpoints, both behind the same platform auth.

1.1 Client token and portal token

A client token comes from client_credentials; a portal token is then scoped to a user email.
  • client_id / client_secret are assigned by Clink and stay on the server.
  • Portal tokens accept email only, not customer_id.
  • The email must already be authorized for the client. Otherwise the call returns 71211003 The redirect URI is not registered for this client.
  • Both the client token and the portal token live for 3600s.

1.2 paymentMethods: create a card-session

The returned access_token (scope card:manage) is the paymentMethods credential and lives for 1799s. It only reaches the current user’s card endpoints, so it can be sent to the browser.

1.3 vault: create a vault session

  • Send vault_id to the vault element. It is valid for about 30 minutes.
  • url is the passwordless card-binding page for direct browser use; SDK integrations do not use it.
  • The iframe exchanges vaultId for a vault token (about 899s); the host never sees that token.
Keep the client secret, client token, and portal token on the server. Your wrapper endpoint should return only { token } or { vaultId }.

2. Frontend: initialize and mount

Environments

environment decides which Clink app the iframe loads, and which API your server calls. environment is required: use sandbox (UAT) while integrating and production after go-live. Never mix credentials across environments; mixing returns 401. The app origin comes from environment only; the SDK accepts no runtime override.

Install

The package ships ESM and an IIFE build; see Package formats.

Create the instance

One AgentElements instance creates one element. Create two instances to use both elements.

Create the element

The element type decides the credential and the available mount options. Credentials are passed to createElement, are required, and cannot be empty.

Mount

The container can be a CSS selector or an HTMLElement and needs a stable width. The SDK sets the height and it grows with the content, so do not fix it. The host must run in a current browser with iframe and postMessage support. Mount options apply to the next mount only. Unmount and mount again to change them. Mount options are presentation only and are encoded into the iframe URL. Never put tokens or other secrets in them.

3. Events and state sync

Events are scoped to the element and subscribed with element.on / element.off. Register listeners before mount() so none are missed.
error.source is one of:

Token expiry

On token-expired, paymentMethods fetches a new card-session token from your backend and calls setToken:
The iframe reloads its card data after the new token arrives and resets the once-per-cycle counter. Calling setToken before mount only updates the in-memory value, which is sent with the next init. vault has no refreshable token: when the session expires, request a new vaultId and rebuild the element.

Clean up

destroy() removes the iframe, closes any open 3DS overlay, and clears the element’s listeners. The instance cannot be reused. unmount() only removes the iframe and wrapper; subscriptions survive and the element can be mounted again.

4. Appearance

Appearance is set when the instance is created:
Options are applied when the SDK sends init. setLocale updates the language at runtime; the other options cannot change after construction.

5. Limits

  • One element per AgentElements instance. Create two instances to mount paymentMethods and vault together.
  • The card UI cannot be restyled beyond the preset options; there is no custom CSS hook.
  • 3DS runs in an iframe overlay only; popup and full-page redirect modes are not supported.
  • The host server owns token / vaultId acquisition and refresh.