> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK API 参考

> Agent Vault SDK 的客户端参数、账户级 API、attach 参数与结账方法。

本页配合 [Agent Vault SDK 指南](https://docs.clinkbill.com/cn/guides/agent/vault_sdk) 使用，指南中说明了支付流程和每一步的处理方式。

> [!NOTE]
>
> 所有 API 都在开发者服务端调用。`ClinkVault` 上的入参出参是 camelCase；`pay()`、`reconcile()` 等结账过程的返回值是 snake\_case。

## 创建客户端

```typescript theme={null}
const vault = new ClinkVault(options);
```

创建客户端，自动换取和刷新 OAuth token。

**clientId** `string` *required*

Clink 签发的 Client ID。

**clientSecret** `string` *required*

Clink 签发的 Client Secret，只放在服务端。

**environment** `string` (default: sandbox)

`sandbox` 或 `production`。

**timeoutMs** `number` (default: 15000)

请求超时时间（毫秒）。

**authorizationTimeoutMs** `number` (default: 60000)

授权超时时间（毫秒）。

**submitTimeoutMs** `number` (default: 30000)

`submit` 后等待 PSP 请求或 PayPal 批准链接的时间（毫秒）。

## ClinkVault 方法

**vault.attach(page, options)** `Promise\<CheckoutController\>`

挂到 Playwright `Page`（本地或云浏览器），开始拦截支付请求。参数见 [attach 的 options](#attach-的-options)。

**vault.attachToCdp(cdp, pageSessionId, options)** `Promise\<CheckoutController\>`

不用 Playwright，直接挂到 CDP 连接。`cdp` 是 flatten 模式的 CDP 连接，`pageSessionId` 是结账页的 session。参数同 [attach 的 options](#attach-的-options)，不含 `routeScope` 和 `detectPaymentMethods`。

**vault.sessions.create(\{ email, externalUserId })** `object`

在结账外创建绑卡 session，`email` 必填。

返回 `{ sessionId, type: 'bind', url, expiresAt, customerId }`。

**vault.sessions.retrieve(sessionId)** `object`

查询绑卡 session 的结果。

返回 `{ type, status, expiresAt?, cardToken?, card?, window? }`。`status` 取值：`pending` / `opened` / `completed` / `failed` / `locked` / `expired`。

**vault.cards.list(\{ customerId })** `array`

列出用户授权给当前开发者的卡。

每一项为 `{ cardToken, brand, last4, expMonth, expYear, status, window? }`。有 `window: { expiresAt }` 表示付款窗口还开着。

**vault.getCoverage()** `object`

查询当前开通的 PSP。

返回 `{ psps: [{ psp, mode, status, limits }] }`。

## attach 的 options

`vault.attach()` 和 `vault.attachToCdp()` 的参数。

**customerId** `string`

已绑卡用户的标识，首次使用可以不传。

**cardToken** `string`

用户已保存的卡 token，首次使用可以不传。

**email** `string`

没有可用的卡时，用它创建绑卡 session；不传时 `pay()` 直接返回 `failed`（`card_not_bound` 或 `window_expired`）。

**externalUserId** `string`

开发者侧的用户 ID。

**onUserAction(action)** `function`

需要用户参与时回调。`action` 结构：

```typescript theme={null}
{ type, url?, expires_at?, customer_id?, card_token?, authorization_id?,
  method?, qr_image_base64?, qr_data? }
```

`type` 是 `bind_card` / `pay_qr` / `3ds` / `redirect`。`pay_qr` 带 PNG 二维码图片，PayPal 是 `redirect` 加批准链接。链接和二维码由开发者代码直接给用户，不要交给 LLM 转述。

**onCardBound(card)** `function`

绑卡完成并确认卡后回调一次，`card` 为 `{ customerId, cardToken }`，用于持久化。

**onStateChange(state)** `function`

结账状态变化时回调，`state` 同 `getState()`。

**resolveMerchantResult(state)** `function`

`reconcile()` 时调用，按以下任一形式返回商户订单结果：

```typescript theme={null}
{
  status: 'completed' | 'failed' | 'pending' | 'unknown';
  order_id?;
  payment_confirmed_unpaid?;
}
// or
{ status: 'requires_user_action'; reason: '3ds' | 'redirect' }
```

扫码支付只有 `failed` 且 `payment_confirmed_unpaid: true` 时才会回退到卡。

**routeScope** `string` (default: context)

`context` 覆盖跨域 iframe；`page` 只覆盖当前页面。只用于 `attach`。

**rules** `object`

自定义识别规则；不传时从 Clink Vault 同步。

**detectPaymentMethods(page)** `function`

自定义 `getPaymentMethods()` 的卡识别逻辑，返回 `[{ method, psp?, source }]`。传入后替换 SDK 自带的卡识别，扫码钱包和 PayPal 仍由 SDK 识别。只用于 `attach`。

**resolveQrCode, resolvePayNowQr, resolvePayPalUrl** `function`

自定义从页面提取二维码或 PayPal 链接的方法。二维码的 `image_base64` 必须是 base64 的 PNG / JPEG / GIF / WebP，SVG 和远程 URL 会被拒绝。

## CheckoutController 方法

`vault.attach()` 和 `vault.attachToCdp()` 返回 `CheckoutController`，对应一次结账。

**getPaymentMethods()** `object`

检测页面上的支付方式，结合用户的卡返回每种方式的状态。卡在填写前就能识别（扫描页面加载的 PSP 脚本和卡 iframe）；扫码钱包和 PayPal 只在本地检测，不发给 Clink Vault。

返回 `{ default, methods: [{ method, psp?, status, card?: { brand, last4 }, reason? }] }`。`status` 取值：`ready` / `needs_bind` / `needs_user` / `unsupported`。

**pay(options?)** `PayStep`

推进支付，每次返回下一步要做的事，见 [pay() 的返回值](#pay-的返回值)。

* `method`：`card`（默认）/ `paynow` / `wechat_pay` / `upi_qr` / `bcmc_mobile` / `pix` / `paypal`
* `fallback`：`card`

**bind()** `PayStep`

主动发起绑卡（用户要加卡或换卡），attach 时需传 `email`。新卡和已有卡重输 CVV 用同一个链接；未完成的 session 会复用。返回 `wait_user` / `bind_card`，链接通过 `onUserAction` 下发。没传 `email` 时返回 `failed` / `card_not_bound`；支付已经开始后调用，返回 `failed` / `invalid_checkout_state`。

**reconcile()** `CheckoutState`

调 `resolveMerchantResult` 读商户订单结果，并上报 Clink Vault。返回 `{ status, authorization_id?, order_id?, reason? }`。各种结果对应的 `status` 见[上报结果并卸载](https://docs.clinkbill.com/cn/guides/agent/vault_sdk#快速接入)。

**retry()** `void`

确认没扣款后开始新一次尝试。只在 `declined` / `failed` / `cancelled` / `unsupported` 时可用，其他状态抛 `retry_not_allowed`。

**requestUserAction(reason)** `void`

页面在拿到卡 token 后才弹出 3DS 或跳转时，手动进入等待用户的状态。`reason` 为 `3ds` 或 `redirect`。

**cancel()** `void`

取消还没拿到结果的支付。如果卡请求可能已经发到 PSP，且无法确认取消成功，状态会变为 `outcome_unknown`。

**getState()** `CheckoutState`

读取当前结账状态。

**detach()** `void`

卸载拦截，结账结束时必须调用。

## pay() 的返回值

```typescript theme={null}
interface PayStep {
  status:
    | 'requires_action' | 'succeeded' | 'declined'
    | 'outcome_unknown' | 'unsupported' | 'failed';
  next_action?:
    // fill_card 下发的是占位卡，不是真卡
    | { type: 'fill_card'; card: { number; exp_month; exp_year; cvc } }
    | { type: 'submit' }
    | {
        type: 'wait_user';
        reason: 'bind_card' | 'pay_qr' | '3ds' | 'redirect';
        expires_at;
        url?;
        qr_image_base64?;
        qr_data?;
      }
    | { type: 'select_method'; method };
  authorization_id?: string;
  // 本次实际使用的支付方式
  method_used?: string;
  // 是否已回退到卡
  fell_back?: boolean;
  // 二维码 PNG（data URL），由宿主直接展示
  qr_image_base64?: string;
  // 解码后的二维码内容，浏览器支持 BarcodeDetector 时才有
  qr_data?: string;
  // 原因，如 card_not_bound、3ds、redirect
  reason?: string;
}
```

每种 `next_action` 该怎么处理，见[快速接入](https://docs.clinkbill.com/cn/guides/agent/vault_sdk#快速接入)。

`CheckoutState.status` 的取值：`idle` / `awaiting_user` / `ready_to_submit` / `processing` / `requires_user_action` / `awaiting_merchant` / `completed` / `declined` / `outcome_unknown` / `cancelled` / `unsupported` / `failed`。

## 错误

出错时 SDK 抛 `VaultError`：`code` 是错误码（如 `card_not_bound`、`window_expired`、`rule_not_matched`、`retry_not_allowed`、`api_error`），`message` 已去掉卡号和 CVV。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.