カードバインドとトークン管理

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

このフローはサーバー側（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 認証を取得している場合、フロントエンド 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 を使用する必要があり、バックエンドから直接カード番号を渡すことはできません

はじめに

コアコンセプト

インテグレーション

Webhook

SDK

ツールとリファレンス

カードバインドとトークン管理

主要なフロー

カードバインドフロー

代替案：PCI-DSS 加盟店による直接送信

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

トークン管理

セキュリティメカニズム

​主要なフロー

​カードバインドフロー

​代替案：PCI-DSS 加盟店による直接送信

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

​トークン管理

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

主要なフロー

カードバインドフロー

代替案：PCI-DSS 加盟店による直接送信

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

トークン管理

セキュリティメカニズム