所有 API 都在开发者服务端调用。
ClinkVault 上的入参出参是 camelCase;pay()、reconcile() 等结账过程的返回值是 snake_case。创建客户端
ClinkVault 方法
挂到 Playwright
Page(本地或云浏览器),开始拦截支付请求。参数见 attach 的 options。不用 Playwright,直接挂到 CDP 连接。
cdp 是 flatten 模式的 CDP 连接,pageSessionId 是结账页的 session。参数同 attach 的 options,不含 routeScope 和 detectPaymentMethods。查询绑卡 session 的结果。返回
{ type, status, expiresAt?, cardToken?, card?, window? }。status 取值:pending / opened / completed / failed / locked / expired。列出用户授权给当前开发者的卡。每一项为
{ cardToken, brand, last4, expMonth, expYear, status, window? }。有 window: { expiresAt } 表示付款窗口还开着。attach 的 options
vault.attach() 和 vault.attachToCdp() 的参数。
需要用户参与时回调。
action 结构:type 是 bind_card / pay_qr / 3ds / redirect。pay_qr 带 PNG 二维码图片,PayPal 是 redirect 加批准链接。链接和二维码由开发者代码直接给用户,不要交给 LLM 转述。reconcile() 时调用,按以下任一形式返回商户订单结果:completed 时必须带商户订单号 order_id。页面没有订单号时改带 confirmation,authorization_id 取 state.authorization_id。两者都没有,或 authorization_id 不匹配时,reconcile() 不上报结果,状态变为 outcome_unknown(merchant_result_unknown)。扫码支付只有 failed 且 payment_confirmed_unpaid: true 时才会回退到卡。自定义
getPaymentMethods() 的卡识别逻辑,返回 [{ method, psp?, source }]。传入后替换 SDK 自带的卡识别,扫码钱包和 PayPal 仍由 SDK 识别。只用于 attach。自定义从页面提取二维码或 PayPal 链接的方法。二维码的
image_base64 必须是 base64 的 PNG / JPEG / GIF / WebP,SVG 和远程 URL 会被拒绝。CheckoutController 方法
vault.attach() 和 vault.attachToCdp() 返回 CheckoutController,对应一次结账。
检测页面上的支付方式,结合用户的卡返回每种方式的状态。卡在填写前就能识别(扫描页面加载的 PSP 脚本和卡 iframe);扫码钱包和 PayPal 只在本地检测,不发给 Clink Vault。返回
{ default, methods: [{ method, psp?, status, card?: { brand, last4 }, reason? }] }。status 取值:ready / needs_bind / needs_user / unsupported。推进支付,每次返回下一步要做的事,见 pay() 的返回值。
method:card(默认)/paynow/wechat_pay/upi_qr/bcmc_mobile/pix/paypalfallback:card
主动发起绑卡(用户要加卡或换卡),attach 时需传
email。新卡和已有卡重输 CVV 用同一个链接;未完成的 session 会复用。返回 wait_user / bind_card,链接通过 onUserAction 下发。没传 email 时返回 failed / card_not_bound;支付已经开始后调用,返回 failed / invalid_checkout_state。调
resolveMerchantResult 读商户订单结果,并上报 Clink Vault。返回 { status, authorization_id?, order_id?, reason? }。各种结果对应的 status 见上报结果并卸载。pay() 的返回值
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。