绑卡与 Token 管理

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

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

核心流程

商户后端 → 调用 Generate API → 获取 tokenSessionId
前端 → 使用 @waffo/payment-sdk 提交卡片信息 → 卡片数据加密传输
处理结果 → 获取 tokenId（可能需要 3DS 验证）
后续支付 → 在 order/create 中传入 tokenId 代替卡号

绑卡流程

商户后端调用 Generate API

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

前端提交卡片信息

使用 @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/2025',    // MM/YYYY
    cvv: '123'            // 可选
  },
  billingAddress: {        // 可选
    countryCode: 'USA',
    region: 'CA',
    city: 'San Francisco',
    postalCode: '94102',
    address: '123 Main St'
  }
});

SDK 自动对卡片数据加密。商户服务器不接触明文卡号，因此无需 PCI DSS 认证。

处理绑卡结果

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

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

绑卡完成后，Waffo 通过 notifyUrl 向商户后端发送通知，包含最终的 tokenId。商户必须保存该 tokenId 以用于后续支付。

替代方案：PCI-DSS 商户直接提交

若商户已通过 PCI-DSS 认证，可通过 Generate API 的 tokenData 字段直接从后端提交卡号等敏感信息，无需使用前端 SDK。此时 API 将直接返回 tokenId。

使用 Token 支付

获取 tokenId 后，在创建订单时传入以代替卡号：

const response = await waffo.order().create({
  paymentRequestId: '...',
  merchantOrderId: 'ORDER_001',
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  tokenId: 'tok_xxxxxxxxxxxx',  // 使用 Token 代替卡号
  notifyUrl: 'https://your-site.com/webhook',
  // ... 其他参数
});

支持一次性支付（ONE_TIME_PAYMENT）和订阅支付（SUBSCRIPTION）。

Token 管理

操作	API	说明
查询	POST /api/v1/tokenization/inquiry	获取用户已绑定的 Token 列表
解绑	POST /api/v1/tokenization/remove	删除已绑定的 Token

安全机制

前端 SDK 自动对卡片数据加密，商户服务器不接触明文卡号
所有 API 请求和响应均使用 SHA256WithRSA 签名验证
支持 3DS 验证，提升支付安全性
非 PCI-DSS 商户必须使用前端 SDK，不得直接从后端传入卡号

快速开始

核心概念

集成

Webhook

SDK

工具与参考

核心流程

绑卡流程

替代方案：PCI-DSS 商户直接提交

使用 Token 支付

Token 管理

安全机制

​核心流程

​绑卡流程

​替代方案：PCI-DSS 商户直接提交

​使用 Token 支付

​Token 管理

​安全机制

核心流程

绑卡流程

替代方案：PCI-DSS 商户直接提交

使用 Token 支付

Token 管理

安全机制