メインコンテンツへスキップ
ユーザーの銀行カード情報を安全にトークン化することで、以降の決済時にカード番号を再入力する必要がなくなります。

​
主要なフロー

1. 加盟店バックエンド → Generate API を呼び出し → tokenSessionId を取得
2. フロントエンド → @waffo/payment-sdk を使用してカード情報を送信 → カードデータを暗号化して送信
3. 処理結果 → tokenId を取得（3DS 認証が必要な場合あり）
4. 以降の決済 → order/create に tokenId を渡してカード番号の代わりに使用

​
カードバインドフロー

1

加盟店バックエンドから Generate API を呼び出す

POST /api/v1/tokenization/generate を呼び出し、tokenRequestId、merchantUserId、tokenType: "CARD" などのパラメータを渡します。成功すると tokenSessionId が返されます。詳細は Generate API を参照してください。
2

フロントエンドからカード情報を送信する

@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 認証も不要です。
3

カードバインド結果のハンドリング

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 認証を取得している場合、フロントエンド SDK を使用せずに、Generate API の tokenData フィールドを通じてバックエンドから直接カード番号などの機微情報を送信できます。この場合、API は tokenId を直接返します。

​
トークンを使用して決済する

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）をサポートしています。

​
トークン管理

操作API説明
照会POST /api/v1/tokenization/inquiryユーザーがバインド済みのトークン一覧を取得
削除POST /api/v1/tokenization/removeバインド済みトークンを削除

​
セキュリティメカニズム

  • フロントエンド SDK がカードデータを自動的に暗号化。加盟店サーバーはカード番号の平文に触れない
  • すべての API リクエストとレスポンスで SHA256WithRSA 署名検証を使用
  • 3DS 認証をサポートし、決済のセキュリティを強化
  • PCI-DSS 非認証の加盟店は必ずフロントエンド SDK を使用する必要があり、バックエンドから直接カード番号を渡すことはできません