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

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

このフローはサーバー側（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 が含まれる場合、カードバインドの完了時、Token ステータスの変更時、またはカード概要情報の更新時に、Waffo は TOKENIZATION_NOTIFICATION を送信します。result.tokenId を冪等性キーとして通知を処理し、最新の tokenStatus と Token データを保存してください。この通知は初回のバインド結果だけに使用されるものではありません。

Token ステータス

カードバインドが成功すると、Token の初期ステータスは UNVERIFIED になります。VERIFIED に変更するには、CIT（カード会員起点取引）を正常に完了する必要があります。検証には、金額が 0 または 0.01 の独立した ONE_TIME_PAYMENT、または通常の CIT 決済を使用できます。

UNVERIFIED: Token は生成済みですが、CIT がまだ正常に完了していません。scheduled または unscheduled MIT には使用できず、使用すると A0045 が返されます。
VERIFIED: CIT が正常に完了しており、以降の決済に使用できます。
EXPIRED: カードが有効期限に達すると、Token ステータスは EXPIRED になります。
SUSPENDED: Waffo が 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',  // カード番号の代わりにトークンを使用
  },
  // ... その他のパラメータ
});

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 API の用途

セキュリティメカニズム

​主要なフロー

​カードバインドフロー

​Token ステータス

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

​Token API の用途

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

主要なフロー

カードバインドフロー

Token ステータス

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

Token API の用途

セキュリティメカニズム