Browser Pay platform setup

This page covers the platform layer around Browser Pay: credentials, per-user OAuth connections, tenant isolation, and deployment checks. Browser Pay can coexist with Vault SDK in the same platform; route a checkout to one path before the payment attempt starts. It does not repeat the payment state machine. For the checkout flow, credential handling, result reporting, and recovery, use the Browser Pay guide.

A platform has two OAuth concerns. Its server uses the platform credential pair to manage user connections; each user then authorizes a separate MCP connection with Authorization Code + PKCE. Clink may register the same client_id for both roles, but the client_secret never goes through the user authorization flow.

Prepare the platform integration

Ask Clink to provide or confirm the following for each environment:

Item	Platform requirement
Partner credentials	`client_id` and `client_secret` for the server-side platform token. Keep the secret on the server.
User OAuth client	A public OAuth client for Authorization Code + PKCE. Confirm whether its `client_id` is the partner `client_id` or a separately registered value.
MCP resource	The MCP URL and matching OAuth resource for the same environment.
Callback	A fixed HTTPS `redirect_uri` registered for the user connection.
Credential encryption	An RSA public key in PEM X.509 SubjectPublicKeyInfo format (`BEGIN PUBLIC KEY`) when Clink returns encrypted credentials. Register it separately from OAuth client configuration.

For the user OAuth client, choose CIMD, pre-registration, or DCR as described in MCP connection and OAuth. OAuth client registration and RSA public-key registration are separate steps. Browser Pay normally needs these user scopes:

wallet:read payment:execute instruction:read instruction:write events:read events:consume offline_access

Add wallet:setup when the platform changes a user’s default card. The registered OAuth client must allow every scope requested by the authorization flow. Scope details and tool-specific requirements belong in the Browser Pay guide and Browser Pay API reference.

Establish each user connection

Keep the platform token and user token in separate stores. The platform token calls the partner connection endpoints; the user token represents one user when the platform calls MCP. The platform connection has two phases: the server creates or manages the Clink session, then the user completes Authorization Code + PKCE. Keep the callback state tied to the platform user before opening the MCP connection.

Get a platform token

Use the partner credentials with client_credentials:

POST {API_BASE_URL}/agent/cwallet/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={PLATFORM_CLIENT_ID}
&client_secret={PLATFORM_CLIENT_SECRET}
&scope=agent-platform:account

Cache access_token until expires_in and obtain a new one after expiry. This token manages platform sessions; it cannot call a user’s MCP tools directly.

Create or resume a user session

When a user enables Clink, generate a random state and PKCE code_verifier, calculate the S256 code_challenge, and bind them temporarily to that platform user. Use a verified user email and your stable external_user_id:

POST {API_BASE_URL}/agent/cwallet/platform/sessions
Authorization: Bearer {PLATFORM_ACCESS_TOKEN}
Content-Type: application/json

{
  "email": "user@example.com",
  "external_user_id": "platform-user-123",
  "redirect_uri": "https://agent.example.com/oauth/clink/callback",
  "state": "{RANDOM_STATE}",
  "code_challenge": "{S256_CODE_CHALLENGE}",
  "code_challenge_method": "S256"
}

Read data.status from the response. Clink must confirm the formal data schema and field return conditions during enablement:

status	Platform action
`authorized`	Save `customer_id`, the user `access_token`, its expiry, and the returned `refresh_token`. If no new refresh token is returned, keep the existing valid value.
`authorization_required`	Save and show `authorization_url`; keep `state` and `code_verifier` until the callback completes.

When the callback returns code, state, and iss, verify that the state belongs to the user who started the connection and that iss matches the issuer in the Authorization Server Metadata for the same environment. Do not persist a cancelled or failed connection. Exchange the code at the token_endpoint from Authorization Server Metadata as a public client. Do not send a client_secret:

POST {TOKEN_ENDPOINT}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={OAUTH_CLIENT_ID}
&code={AUTHORIZATION_CODE}
&redirect_uri={REGISTERED_REDIRECT_URI}
&code_verifier={SAVED_CODE_VERIFIER}
&resource={MCP_RESOURCE}

redirect_uri must exactly match the registered and authorized value. Read token_endpoint and the issuer from {API_BASE_URL}/.well-known/oauth-authorization-server instead of hardcoding them, and never mix UAT and Production. The resource and MCP URL must belong to the same environment.

Persist platform state safely

Use one record per platform user, environment, and OAuth client. Keep the association with external_user_id in the platform database; Clink’s customer_id is not a substitute for the platform user ID.

Data	Storage and purpose
`external_user_id`	Stable platform key used to find the user’s connection.
`customer_id`	Clink customer association for this environment and user.
User `access_token`, `refresh_token`, expiry	Encrypted server-side credentials. Never share between users or environments.
`state`, `code_verifier`	Short-lived callback state. Delete after a successful or failed callback.
Checkout facts, `operation_id`, payment identifiers	Recovery context for the same purchase; use the Browser Pay guide for their lifecycle.

Refresh each user’s token serially, including across server instances. Each refresh returns a new refresh_token and retires the old one: store the new value before using the new Access Token, and never send a retired token again. If a retired token is sent again, Clink revokes every Refresh Token from that authorization and the user must authorize again. If refresh fails, stop new MCP work for that user and restart authorization. See Refresh tokens and recover. When a user disconnects, stop new work, revoke the Refresh Token with the configured OAuth client at /agent/cwallet/oauth/revoke, and remove local credentials. A user with an empty wallet is still connected; a readable wallet or default card does not authorize a purchase. Connect MCP with the user’s token and read the current tool list and clink://skill/rules. If the Host cannot read resources, call get_skill_manifest with include_rules: true. The platform should make a read-only get_account_state call before enabling payment actions. For a Node.js smoke test, use Node.js 20.19 or later and @modelcontextprotocol/client@2: connect to the environment’s MCP URL with the user’s Access Token, list tools, call get_account_state with {}, and inspect structuredContent. Treat isError: true as a failed connection. connected: true plus a readable wallet proves the connection; cardCount: 0 means the wallet is empty, not that OAuth failed. Use the platform’s normal per-user refresh flow after this check.

Minimal Node.js wallet smoke test

npm install @modelcontextprotocol/client@2

import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const token = process.env.CLINK_USER_ACCESS_TOKEN;
if (!token) throw new Error("Set CLINK_USER_ACCESS_TOKEN.");

const client = new Client({ name: "clink-wallet-check", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
  new URL(process.env.CLINK_MCP_URL ?? "https://uat-api.clinkbill.com/mcp"),
  { authProvider: { token: async () => token } },
);

try {
  await client.connect(transport);
  const { tools } = await client.listTools();
  if (!tools.some(tool => tool.name === "get_account_state")) {
    throw new Error("get_account_state is unavailable.");
  }
  const result = await client.callTool({ name: "get_account_state", arguments: {} });
  if (result.isError) throw new Error("Wallet read failed.");
  const account = result.structuredContent;
  if (!account || !Array.isArray(account.paymentMethods)) {
    throw new Error("Unexpected wallet response.");
  }
  console.log({ connected: true, walletReadable: true, cardCount: account.paymentMethods.length });
} finally {
  try {
    await transport.terminateSession();
  } finally {
    await client.close();
  }
}

OAuth grants access to Clink tools; it does not authorize a purchase. A purchase instruction or a one-time user action defines what the Agent may spend. Passkey and other user actions returned by Browser Pay must be presented to the correct user and resumed through the same Operation.

Hand off a checkout to Browser Pay

The platform remains responsible for the merchant browser and the user experience. The canonical Browser Pay guide defines the payment flow; the platform adapter must provide these inputs and handoffs:

Read the merchant’s final amount, currency, merchant details, and checkout facts. Use minor currency units and preserve the same facts when resuming an Operation.
Refresh the wallet before choosing a specific paymentInstrumentId; let the user confirm the card and use only a card marked agent_pay_support: true.
Deliver next_action.params.redirect_url and QR or user-device actions unchanged. Never open a USER_DEVICE_ONLY link in the Agent’s browser.
Preserve the issuing Operation and payment identifiers before filling the merchant form. Keep encrypted credentials and decrypted card fields out of model input, logs, and ordinary records.
Report the result observed on the merchant page with confirm_result. A Clink report or PSP response does not replace merchant confirmation.

For amount checks, credential decryption, next_action handling, result enums, and duplicate-payment recovery, continue to the Browser Pay guide. For card and purchase authorization management, use Wallet Service.

Validate before rollout

Run these checks in Sandbox UAT and repeat the relevant checks in Production:

Two platform users can share an OAuth client while seeing only their own wallet, Operations, and payment context.
An already authorized user can obtain a credential; a user action can be presented and resumed through the same Operation.
The registered RSA public key decrypts a credential in the trusted platform component, while the secret key and card fields stay out of the Agent and logs.
Access Token expiry, Refresh Token rotation, callback replay, user disconnect, and authorization failure have explicit handling.
Success, failure, unsubmitted, and unknown merchant outcomes are reported with the correct Clink identifiers and never trigger an automatic duplicate payment.

Confirm with Clink

Before production, confirm the /platform/sessions data schema, the relationship between partner and public OAuth client_id, the OAuth scope registration, the environment resource values, and the public-key registration process. Keep these values in deployment configuration rather than inferring them from examples.

Browser Pay guide: payment mechanics, credential protection, reporting, and recovery.
MCP connection and OAuth: protocol connection details.
Browser Pay API reference: tool fields and response shapes.
Operations and recovery: Operation states and recovery rules.

Get Started

Integration

Agent Solutions

Configure & Launch

Guides

Finance

Prepare the platform integration

Establish each user connection

Get a platform token

Create or resume a user session

Persist platform state safely

Hand off a checkout to Browser Pay

Validate before rollout

Confirm with Clink

​Prepare the platform integration

​Establish each user connection

​Get a platform token

​Create or resume a user session

​Persist platform state safely

​Hand off a checkout to Browser Pay

​Validate before rollout

​Confirm with Clink

​Related docs

Prepare the platform integration

Establish each user connection

Get a platform token

Create or resume a user session

Persist platform state safely

Hand off a checkout to Browser Pay

Validate before rollout

Confirm with Clink

Related docs