加盟店側のカード登録

@waffo/payment-sdk を使用して加盟店ページでカードを独立して登録し、カード情報を安全に Token へ変換します。このフローでは、同じ操作で通常決済を行う必要はありません。

このフローはサーバー側（Generate / Inquiry / Remove API の呼び出し）とフロントエンド（@waffo/payment-sdk によるカード情報の送信）の両方にまたがります。

このフローが適しているケース

カードを先に登録し、請求タイミングを後から決める場合。
独自ページにカード登録 UI を設ける場合。
Waffo Checkout を使用しない、または今回の決済とは別にカードを登録する場合。

Waffo Checkout をすでに導入しており、初回決済の成功後に以降の MIT 用 Token を取得する場合は、Waffo Checkout でのカード登録を使用してください。

主要なフロー

フェーズ 1：カード登録 —— 加盟店バックエンドが tokenSessionId を取得し、フロントエンドが @waffo/payment-sdk でカード情報を送信します。返される tokenId のステータスは UNVERIFIED です。このフェーズでは 3DS は発生しません。
フェーズ 2：0 円決済による検証 —— バックエンドが Token を使用して 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 が含まれる場合、カードバインドの完了時、Token ステータスの変更時、またはカード概要情報の更新時に、Waffo は TOKENIZATION_NOTIFICATION を送信します。result.tokenId を冪等性キーとして通知を処理し、最新の tokenStatus と Token データを保存してください。この通知は初回のバインド結果だけに使用されるものではありません。

0 円の検証決済を作成する

SDK によるカード登録フェーズでは 3DS は発生しません。UNVERIFIED の tokenId を受け取った後、POST /api/v1/order/create を呼び出し、orderAmount を 0 に設定して、Token を 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 の用途

セキュリティメカニズム