SDK API 参考

本页配合 Agent Vault SDK 指南使用，指南中说明了支付流程和每一步的处理方式。

所有 API 都在开发者服务端调用。ClinkVault 上的入参出参是 camelCase；pay()、reconcile() 等结账过程的返回值是 snake_case。

创建客户端

const vault = new ClinkVault(options);

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

string

必填

Clink 签发的 Client ID。

string

必填

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

string

默认值:"sandbox"

sandbox 或 production。

number

默认值:"15000"

请求超时时间（毫秒）。

number

默认值:"60000"

授权超时时间（毫秒）。

number

默认值:"30000"

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

ClinkVault 方法

Promise<CheckoutController>

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

Promise<CheckoutController>

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

object

在结账外创建绑卡 session，email 必填。返回 { sessionId, type: 'bind', url, expiresAt, customerId }。

object

查询绑卡 session 的结果。返回 { type, status, expiresAt?, cardToken?, card?, window? }。status 取值：pending / opened / completed / failed / locked / expired。

array

列出用户授权给当前开发者的卡。每一项为 { cardToken, brand, last4, expMonth, expYear, status, window? }。有 window: { expiresAt } 表示付款窗口还开着。

object

查询当前开通的 PSP。返回 { psps: [{ psp, mode, status, limits }] }。

attach 的 options

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

string

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

string

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

string

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

string

开发者侧的用户 ID。

function

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

{ 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 转述。

function

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

function

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

function

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

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

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

string

默认值:"context"

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

object

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

function

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

function

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

CheckoutController 方法

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

object

检测页面上的支付方式，结合用户的卡返回每种方式的状态。卡在填写前就能识别（扫描页面加载的 PSP 脚本和卡 iframe）；扫码钱包和 PayPal 只在本地检测，不发给 Clink Vault。返回 { default, methods: [{ method, psp?, status, card?: { brand, last4 }, reason? }] }。status 取值：ready / needs_bind / needs_user / unsupported。

PayStep

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

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

PayStep

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

CheckoutState

调 resolveMerchantResult 读商户订单结果，并上报 Clink Vault。返回 { status, authorization_id?, order_id?, reason? }。各种结果对应的 status 见上报结果并卸载。

void

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

void

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

void

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

CheckoutState

读取当前结账状态。

void

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

pay() 的返回值

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 该怎么处理，见快速接入。 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。

开始使用

接入

Agent 解决方案

配置与上线

介绍

财务信息

创建客户端

ClinkVault 方法

attach 的 options

CheckoutController 方法

pay() 的返回值

错误

​创建客户端

​ClinkVault 方法

​attach 的 options

​CheckoutController 方法

​pay() 的返回值

​错误

创建客户端

ClinkVault 方法

attach 的 options

CheckoutController 方法

pay() 的返回值

错误