绑卡与 Token 管理

将用户银行卡信息安全转换为 Token，后续支付无需再次输入卡号。

本流程横跨服务端（调用 Generate / Inquiry / Remove API）与前端（通过 @waffo/payment-sdk 提交卡信息）两端。

核心流程

商户后端 —— 调用 Generate API，获取 tokenSessionId。
商户前端 —— 将明文卡信息传给 @waffo/payment-sdk，由 SDK 加密后提交。
绑卡结果 —— 获取初始状态为 UNVERIFIED 的 tokenId（可能需要 3DS 验证）。
卡片验证 —— 完成一笔成功的 CIT，Token 状态变为 VERIFIED。
后续支付 —— 在 order/create 中通过 paymentInfo.userPaymentAccessToken 传入 tokenId。

绑卡流程

商户后端调用 Generate API

调用 POST /api/v1/tokenization/generate，传入 tokenRequestId、merchantUserId、tokenType: "CARD" 等参数。成功后返回 tokenSessionId。

前端提交卡片信息

使用 @waffo/payment-sdk 的 tokenizationSubmit 方法将卡片数据加密后提交至 Waffo 服务器：

import WaffoSDK from '@waffo/payment-sdk';

const sdk = new WaffoSDK('your-client-api-key', {
  env: 'prod',
  locale: 'en'
});

const result = await sdk.tokenizationSubmit('tokenSessionId', {
  tokenData: {
    pan: '4111111111111111',
    name: 'John Doe',
    expiry: '12/2028',    // MM/YYYY
    cvv: '123'            // 可选
  },
  billingAddress: {        // 可选
    countryCode: 'USA',
    region: 'CA',
    city: 'San Francisco',
    postalCode: '94102',
    address: '123 Main St'
  }
});

商户前端会将明文卡信息传给 SDK。SDK 在发送前加密卡片数据。在前端 SDK 绑卡模式下，只要商户后端不保留、不流转明文卡信息，商户就无需具备 PCI DSS 资质。

处理绑卡结果

if (result.success) {
  const { tokenRequestId, validateUrl } = result.data;

  if (validateUrl) {
    // 需要 3DS 验证，重定向用户
    window.location.href = validateUrl;
  } else {
    // 绑卡成功，等待 Webhook 获取 tokenId
  }
}

如果 Generate 请求提供了 notifyUrl，Waffo 会在绑卡完成、Token 状态变化或卡片摘要信息更新时发送 TOKENIZATION_NOTIFICATION。商户应以 result.tokenId 为幂等键，保存最新的 tokenStatus 和 Token 数据。该通知不仅用于返回首次绑卡结果。

Token 状态

绑卡成功后，Token 的初始状态为 UNVERIFIED。你需要完成一笔成功的 CIT（持卡人发起交易）后，才能将状态变为 VERIFIED。验证交易可以是金额为 0 或 0.01 的独立 ONE_TIME_PAYMENT，也可以是正常的 CIT 支付。

UNVERIFIED：已生成 Token，但尚未完成成功的 CIT。此状态不能用于 scheduled 或 unscheduled MIT，否则返回 A0045。
VERIFIED：已完成成功的 CIT，可用于后续支付。
EXPIRED：卡片到达有效期后，Token 状态会变为 EXPIRED。
SUSPENDED：Waffo 已暂停该 Token 的使用。公开契约未定义具体触发条件。

使用 Token 支付

获取 tokenId 后，在创建订单时通过 paymentInfo.userPaymentAccessToken 传入以代替卡号：

const response = await waffo.order().create({
  paymentRequestId: '...',
  merchantOrderId: 'ORDER_001',
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  notifyUrl: 'https://your-site.com/webhook',
  userInfo: {
    userId: 'USER_001',  // 必须与 Generate API 传入的 merchantUserId 一致
  },
  paymentInfo: {
    productName: 'ONE_TIME_PAYMENT',
    userPaymentAccessToken: 'tok_xxxxxxxxxxxx',  // 使用 Token 代替卡号
  },
  // ... 其他参数
});

tokenId 只能与 Waffo 的 ONE_TIME_PAYMENT 产品配合使用，不能传给 Waffo 的 SUBSCRIPTION 产品。如果你自行管理周期性计费计划，可在 Token 变为 VERIFIED 后，按计划重复创建 ONE_TIME_PAYMENT 订单。MIT 订单还需要设置 paymentInfo.merchantInitiatedMode。

Token API 用法

操作	API	说明
发起绑卡	POST /api/v1/tokenization/generate	创建一次绑卡会话，获取前端 SDK 所需的 `tokenSessionId`
查询	POST /api/v1/tokenization/inquiry	通过 `tokenId` 查询单个 Token，或通过 `merchantUserId` 查询用户的 Token 列表
解绑	POST /api/v1/tokenization/remove	通过 `tokenId` 删除单个 Token，或通过 `merchantUserId` 删除用户的全部 Token

安全机制

商户前端将明文卡信息传给 SDK，SDK 在发送前加密；商户后端不接触明文卡号
所有 API 请求和响应均使用 SHA256WithRSA 签名验证
支持 3DS 验证，提升支付安全性

快速开始

核心概念

集成

Webhook

SDK

工具与参考

点卡充值 API

核心流程

绑卡流程

Token 状态

使用 Token 支付

Token API 用法

安全机制

​核心流程

​绑卡流程

​Token 状态

​使用 Token 支付

​Token API 用法

​安全机制

核心流程

绑卡流程

Token 状态

使用 Token 支付

Token API 用法

安全机制