商户侧绑卡

通过 @waffo/payment-sdk 在商户页面中独立绑定银行卡，并将卡信息安全地转换为 Token。该流程不要求同时完成一笔正常金额的支付。

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

适用场景

你需要先绑定银行卡，再决定何时发起支付。
你需要在自己的页面中设计绑卡界面。
你不使用 Waffo 收银台，或不希望将绑卡与本次支付绑定。

如果你已经集成 Waffo 收银台，并希望在首次支付成功后直接获得可用于后续 MIT 的 Token，请使用 Waffo 收银台绑卡。

核心流程

阶段一：绑卡 —— 商户后端获取 tokenSessionId，商户前端通过 @waffo/payment-sdk 提交卡片信息，获得状态为 UNVERIFIED 的 tokenId。此阶段不会触发 3DS。
阶段二：0 元支付验证 —— 商户后端使用 tokenId 发起一笔 0 元 CIT。这一步可能需要 3DS。支付成功后，Token 状态变为 VERIFIED。
后续支付 —— 在 order/create 中通过 paymentInfo.userPaymentAccessToken 传入 tokenId。

绑卡流程

商户后端调用 Generate API

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

{
  "tokenRequestId": "TOKEN_202609170001",
  "merchantUserId": "USER_001",
  "tokenType": "CARD",
  "merchantInfo": {
    "merchantId": "YOUR_MERCHANT_ID"
  },
  "notifyUrl": "https://merchant.example.com/webhooks/tokenization"
}

前端提交卡片信息

使用 @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 在发送前加密卡片数据。在商户侧绑卡模式下，只要商户后端不保留、不流转明文卡信息，商户就无需具备 PCI DSS 资质。

处理绑卡结果

if (result.success) {
  const { tokenRequestId } = result.data;
  // 绑卡请求已提交，等待 Webhook 获取 tokenId
}

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

发起 0 元支付验证

SDK 绑卡阶段不会触发 3DS。收到状态为 UNVERIFIED 的 tokenId 后，调用 POST /api/v1/order/create，将 orderAmount 设置为 0，并把 tokenId 传入 paymentInfo.userPaymentAccessToken。

{
  "paymentRequestId": "VERIFY_202609170001",
  "merchantOrderId": "VERIFY_ORDER_202609170001",
  "orderCurrency": "HKD",
  "orderAmount": "0",
  "orderDescription": "Verify bound card",
  "orderRequestedAt": "2026-09-17T02:00:00.000Z",
  "notifyUrl": "https://merchant.example.com/webhooks/payment",
  "successRedirectUrl": "https://merchant.example.com/card/verified",
  "failedRedirectUrl": "https://merchant.example.com/card/verification-failed",
  "merchantInfo": {
    "merchantId": "YOUR_MERCHANT_ID"
  },
  "userInfo": {
    "userId": "USER_001",
    "userEmail": "user@example.com",
    "userTerminal": "WEB"
  },
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx"
  }
}

0 元验证交易是 CIT，不要传 paymentInfo.merchantInitiatedMode。如果响应的 orderStatus 为 AUTHORIZATION_REQUIRED，解析 orderAction 并让用户完成 3DS。通过 PAYMENT_NOTIFICATION 获取支付结果；支付成功后，再以 TOKENIZATION_NOTIFICATION 或 Tokenization Inquiry 确认 Token 已变为 VERIFIED。

Token 状态

绑卡成功后，Token 的初始状态为 UNVERIFIED。你需要使用该 Token 发起一笔金额为 0 的 ONE_TIME_PAYMENT CIT。该支付可能要求用户完成 3DS；支付成功后，Token 状态变为 VERIFIED。

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

发起后续 MIT

发起 MIT 前，确认 Token 状态为 VERIFIED，且商户已通过 Waffo 的 MIT 白名单准入。未完成准入时不可发起 scheduled 或 unscheduled MIT。

调用 POST /api/v1/order/create。继续使用 Generate API 中的同一个 merchantUserId 作为 userInfo.userId，并设置 paymentInfo.userPaymentAccessToken 和 paymentInfo.merchantInitiatedMode。

{
  "paymentRequestId": "MIT_202609170001",
  "merchantOrderId": "MIT_ORDER_202609170001",
  "orderCurrency": "HKD",
  "orderAmount": "49.00",
  "orderDescription": "Scheduled merchant-initiated payment",
  "orderRequestedAt": "2026-09-17T03:00:00.000Z",
  "notifyUrl": "https://merchant.example.com/webhooks/payment",
  "merchantInfo": {
    "merchantId": "YOUR_MERCHANT_ID"
  },
  "userInfo": {
    "userId": "USER_001",
    "userEmail": "user@example.com",
    "userTerminal": "WEB"
  },
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx",
    "merchantInitiatedMode": "scheduled"
  }
}

scheduled：按预先约定的固定计划扣款。
unscheduled：没有固定周期的商户发起扣款。 MIT 不需要用户再次输入卡片或完成 3DS。通过 PAYMENT_NOTIFICATION 接收结果；通知未送达时，调用 POST /api/v1/order/inquiry 查询订单状态。请求体传入 paymentRequestId 或 acquiringOrderId，例如：
{ "paymentRequestId": "MIT_202609170001" }

tokenId 只能与 Waffo 的 ONE_TIME_PAYMENT 产品配合使用，不能传给 Waffo 的 SUBSCRIPTION 产品。

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 签名验证
首笔 0 元 CIT 支持 3DS 验证；SDK 绑卡阶段不触发 3DS

快速开始

核心概念

集成

Webhook

SDK

工具与参考

点卡充值 API

适用场景

核心流程

绑卡流程

Token 状态

发起后续 MIT

Token API 用法

安全机制

​适用场景

​核心流程

​绑卡流程

​Token 状态

​发起后续 MIT

​Token API 用法

​安全机制

适用场景

核心流程

绑卡流程

Token 状态

发起后续 MIT

Token API 用法

安全机制