Skip to main content
This page covers only the platform adaptation layer around Agent Vault SDK: server credentials, user and card associations, browser boundaries, and rollout checks. Vault SDK can coexist with Browser Pay on the same platform, but choose one path before each payment attempt starts. The SDK state machine and PSP behavior are not repeated here. For attach(), pay(), reconcile(), states, errors, and complete code, see the Agent Vault SDK guide and SDK API reference.
Vault SDK does not require end-user OAuth and does not connect to a user’s MCP. The platform server calls Vault with Clink application credentials through OAuth client_credentials; the user participates only when hosted card setup or merchant verification requires it.

1. Provision credentials and confirm coverage

The SDK runs in a trusted platform service or checkout worker that controls a Playwright or CDP browser. The Agent and merchant page can see only the placeholder card provided by the SDK. Vault SDK uses a dedicated Vault client_id and client_secret issued through Pre-registration; see How to get platform credentials for how to request them. When you request them, also describe your target merchants or PSP scenarios. Keep the Client Secret, cardToken, and server-side card associations only on the trusted platform server. Do not expose them to a model, Agent tool, browser storage, logs, or user-facing messages.

2. Install the SDK and initialize the client

The runtime requires Node.js >=20.19 (ESM-only). When using a Playwright Page, Playwright >=1.40 is also required; it is not needed if you use only raw CDP.
The SDK uses these credentials to obtain and refresh application tokens automatically through client_credentials; the platform does not need to call the OAuth endpoint itself. Create separate clients for UAT and Production, and do not share credentials between them.

3. Plan the user and card data to store

Use the platform’s stable user ID as externalUserId. Do not use an email address as the primary key; when a user changes email, a card must not be silently associated with another platform user. Confirm with Clink how externalUserId, email, and customerId are matched when a user changes email, deletes or freezes a card, or merges accounts. Do not infer these rules from the SDK method names. Card setup sessions and payment windows are Vault’s own hosted flows: they are not user OAuth and cannot access other wallet data, and a payment window is not a Browser Pay purchase authorization (Instruction). When one platform enables both paths, manage credentials, permissions, user actions, card identifiers, and recovery separately for each path, and do not let both paths handle the same checkout at the same time.

4. Bind a card or reuse an existing card

For a returning user, load the saved customerId and cardToken from the server. For first use or an expired payment window, pass email to attach(): pay() returns wait_user / bind_card with a hosted card setup link, and onCardBound returns the card association once card setup completes. You can also create a card setup session before checkout and read the result after the user finishes:
The sessionId and url returned on creation are not card credentials. Save customerId and cardToken only after the session completes: customerId comes from sessions.create(), and cardToken from the completed session. When deciding whether a saved association can be reused, rely on the latest expiresAt and card status returned by the SDK.

5. Attach the platform browser and complete the payment

Each checkout maps to one platform-controlled browser task and one checkout controller. Pass the platform user association and implement callbacks that deliver user actions and read the merchant result:
With raw CDP, call vault.attachToCdp(). Do not share a controller, page session, customerId, or cardToken across platform users. Close or detach the current controller when the checkout ends. During checkout.pay(), first-time card setup and an expired payment window both return the same wait_user / bind_card action. The platform should:
  • deliver the hosted card setup link to the user unchanged;
  • wait for the user to add a card or re-enter the CVV;
  • save the customerId / cardToken returned by onCardBound;
  • continue the same checkout with the SDK placeholder card.
3DS, QR code, and redirect actions belong to the current merchant browser or the user’s device. The platform delivers them as returned by the SDK, and follows the Agent Vault SDK guide to continue and reconcile each payment method.

6. Read the merchant result and reconcile

The platform reads the merchant’s order result through resolveMerchantResult; a PSP tokenization response or SDK status alone does not prove that the order completed. Use reconcile(), and follow the Agent Vault SDK guide to distinguish completed, failed, pending, user-action, and unknown outcomes. While the merchant result is pending or requires user action, keep the same checkout controller and call reconcile() again once the merchant page shows a result. When the result is unknown, verify the original order before doing anything else; do not switch cards or start a second payment. Call retry() only after confirming that no charge occurred, and call it before detach(). Call detach() when the checkout ends; it releases interception resources and does not cancel requests already sent. Store the merchant order number separately from Vault identifiers. The result shown to the user should be based on the merchant result, not only on a PSP response or the result reported to Clink.