@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 forpaymentMethods, 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 fromclient_credentials; a portal token is then scoped to a user email.
client_id/client_secretare assigned by Clink and stay on the server.- Portal tokens accept
emailonly, notcustomer_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
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_idto thevaultelement. It is valid for about 30 minutes. urlis the passwordless card-binding page for direct browser use; SDK integrations do not use it.- The iframe exchanges
vaultIdfor a vault token (about 899s); the host never sees that token.
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
Create the instance
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 tocreateElement, are required, and cannot be empty.
Mount
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 withelement.on / element.off. Register listeners before mount() so none are missed.
error.source is one of:
Token expiry
Ontoken-expired, paymentMethods fetches a new card-session token from your backend and calls setToken:
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
AgentElementsinstance. Create two instances to mountpaymentMethodsandvaulttogether. - 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/vaultIdacquisition and refresh.