Skip to main content
このページでは、カードの登録（バインド）とトークンベースの決済について、加盟店から最も多く寄せられる質問に答えます。 フィールドレベルの契約は トークン化 API 仕様 と アクワイアリング API 仕様 にあります。

​
カードトークン化とは何ですか？ tokenId とは何ですか？

トークン化は、ユーザーの生のカード情報を再利用可能な tokenId に置き換えます。 tokenId はお客様側で安全に保管し、ユーザー決済やバックエンドからの引き落としを開始する際に、 カード情報の代わりに使用します。サポートされている tokenType は CARD です。トークンを保持していれば、 ワンタイム決済にも、お客様自身が管理するサブスクリプション型の課金（定期・不定期）にも使用できます。

​
カードを登録してトークンを取得するにはどうすればよいですか？

標準的なフローでは、生のカードデータがお客様のサーバーを通過しません。
  1. 一意の tokenRequestId（冪等キー）、お客様の merchantUserId、tokenType: "CARD"、notifyUrl を指定して /api/v1/tokenization/generate を呼び出します。レスポンスで tokenSessionId が返されます。
  2. フロントエンドで Waffo JavaScript SDK（@waffo/payment-sdk）を初期化し、 tokenizationSubmit(tokenSessionId, tokenData) を呼び出します。 SDK はカードデータを暗号化してから Waffo に送信します。カードの expiry は MM/YYYY（入力時は MM/YY も可）を 受け付けますが、照会と通知では常に MM/YYYY が返されます。
  3. Waffo は tokenId、tokenStatus、マスクされたカード情報（maskedCardInfo、cardBin、cardScheme、cardType など）を含む TOKENIZATION_NOTIFICATION Webhook を notifyUrl にプッシュします。
  4. /api/v1/tokenization/inquiry を使用して、いつでもトークンの詳細を照会できます。tokenId（1 件を返す）または merchantUserId（複数件を返すことがある）で照会します。
お客様の組織が生のカード会員データを扱うために必要な PCI-DSS 認証を保持している場合は、代わりに /api/v1/tokenization/generate の tokenData オブジェクトに pan、name、expiry、cvv を直接渡すこともできます。 その場合、tokenId は API レスポンスで同期的に返されます。

​
トークンのライフサイクルはどのようになっていますか？

tokenStatus には 4 つの値があります。 トークンのステータスが変わるか、トークンデータが更新されるたびに TOKENIZATION_NOTIFICATION を受信します。 処理後は success で応答してください。Waffo が failed または unknown を受信した場合、Waffo は翌日にかけて バックオフスケジュールで通知を再試行します。スケジュールは Webhook の再試行 を参照してください。

​
tokenSessionId と tokenId はどのくらいの期間有効ですか？

2 つの異なる時計があり、固定期間なのはそのうち 1 つだけです。 したがって、有効期限が近いカードは今日登録しても有効期限月の末で使用できなくなるトークンを生成し、 有効期限が遠いカードはプラットフォームの有効期間いっぱい使えるトークンを生成します。 実務上の 2 つの結果：
  • トークン自体の有効期限タイムスタンプは /api/v1/tokenization/inquiry のレスポンスには含まれません。 返されるのは tokenStatus と、トークンデータ内のカードの expiry です。更新失敗の前にユーザーへ警告したい場合は、 上記のルールを自分で導出するのに十分な情報です。
  • tokenStatus はトークンが失効した正確な秒ではなく、定期的なスイープによって EXPIRED に移されます。そのため、 計算上の有効期限をわずかに過ぎたトークンが、まだ使用可能と表示されることがあります。有効期限ルールに基づいて スケジュールし、ステータスと注文作成時のエラーコードを最終判断としてください。

​
同じユーザーが同じカードを 2 回登録すると、tokenId が 2 つできますか？

いいえ。カードトークンは再登録時に重複排除されます。削除されていないトークンに対して次のすべてが一致する場合、 既存の tokenId が返されます — お客様の merchantId（送信している場合は subMerchantId も）、同じ merchantUserId、 同じカード、同じカード名義人、同じ tokenType。 設計時に考慮すべき点：
  • 保存カード一覧の重複排除を自分で行う必要はありません。ただし、2 回目の登録は新しいトークンではなく最初のトークンを 返すため、お客様側のストレージは tokenId をキーにしてください。
  • merchantUserId はキーの一部であるため、同じ物理カードを登録した 2 つの異なる merchantUserId は 2 つの異なる tokenId を受け取ります。結合に使えるユーザー横断のカード識別子は公開されていません。
  • 同じカードでカード名義人が異なる場合は別の認証情報として扱われ、新しいトークンが生成されます。
  • /api/v1/tokenization/remove の後、そのトークンは照会から除外され、再利用されることはありません。同じカードを 再登録すると、新しい tokenId が発行されます。
2 つの登録呼び出しはいずれも冪等ですが、その方法は異なります。

​
CIT と MIT の違いは何ですか？ それぞれいつ使いますか？

MIT 固有の注意点が 2 つあります。
  • CIT は新しく作成したトークンで動作します — 初回決済がカードを検証するものであるため、「verified」状態を待つ必要はありません。
  • MIT にはすでに使用可能な保存済み認証情報が必要です。 トークンで決済が一度も成功していない場合（または保存済み認証情報が 無効になっている場合）、MIT の課金は A0045 で拒否されます。実務的には、初回課金を CIT として実行し、以降の課金に MIT を使用します。
  • threeDsDecision フィールド（3DS_FORCE / NO_3DS）は、カード / ApplePay / GooglePay の CIT 決済にのみ有効で、MIT では無視されます。

​
初回決済と後続の課金はどのように組み合わせますか？

  1. カードを登録し、tokenId を取得します（上記参照）。
  2. トークンが課金可能な状態になるのを待ちます — TOKENIZATION_NOTIFICATION を監視するか、/api/v1/tokenization/inquiry を ポーリングします。
  3. ユーザーが参加する決済では、userPaymentAccessToken を指定して CIT 注文を作成します。
  4. お客様自身が開始する後続の課金では、merchantInitiatedMode（お客様が管理する固定周期なら scheduled、 イベント駆動の引き落としなら unscheduled）を指定して MIT 注文を作成します。

​
保存済みトークンで課金されず、/order/create が AUTHORIZATION_REQUIRED を返したのはなぜですか？

保存済みトークンに対する CIT は、サーバー側の課金ではないためです。merchantInitiatedMode なしで userPaymentAccessToken を送信すると、Waffo は注文を作成し、orderStatus: AUTHORIZATION_REQUIRED と 値の入った orderAction を返します。まだお金は動いておらず、カード会員が完了すべきステップが残っています。 これはワンクリック CIT の通常の結果であり、エラーではありません。 対応方法：
  1. orderAction を解析して actionType を読み取ります — WEB はユーザーを webUrl へ、DEEPLINK は deeplinkUrl へ リダイレクトすることを意味します。
  2. Waffo のホスト型チェックアウトでは、保存済みカードがすでに選択されマスク表示されています。通常、ユーザーが入力する必要が あるのは CVV のみです。その後に 3DS チャレンジが続くことがあります。
  3. AUTHORIZATION_REQUIRED を非最終状態として扱い、結果は決済通知（または注文照会のポーリング）で待ちます。
「/order/create が成功を返したか」だけで分岐しないでください。orderStatus で分岐し、orderAction が存在する場合は常に ユーザーのステップが残っていると想定してください。 顧客が不在の状態で課金する必要がある場合、それこそが merchantInitiatedMode の用途です。上記の CIT/MIT のセクションを参照してください。

​
トークンが期限切れになった、または決済が拒否されました。どうすればよいですか？

  • 注文作成時の A0037（ユーザー決済トークンが無効 / 期限切れ）または A0023（トークンの期限切れにより注文を作成できない）： 保存済みトークンは使用できなくなっています。/api/v1/tokenization/remove を呼び出して登録を解除し（tokenId 指定、または merchantUserId でユーザーの全トークン）、ユーザーに新しいカードの登録を依頼してください。
  • 登録時の B1002（カードの有効期限切れ）または B1001（無効なカード情報）：カード自体が問題です。ユーザーは有効なカードを 提供する必要があります。
  • B1005（トークンセッション ID の期限切れ）：generate で取得した tokenSessionId が無効になっています。 /api/v1/tokenization/generate を再度呼び出してください。
  • B1003（カード登録上限超過）と B1004（現在の加盟店契約でサポートされていないカードスキーム）：これらは契約上の設定に 依存します。Merchant Portal を確認するか、連携サポートにお問い合わせください。

​
決済中にカードを登録します。トークン化の結果はどこに通知されますか？

Merchant Portal（Settings → Integration）で、API キーに対して専用のトークン化通知 URLを設定してください。Waffo は そのキーで作成された各注文にこの URL のスナップショットを保存し、カード登録の結果はそこに通知されます。
  • これは独立したチャネルです。決済結果の notifyUrl は従来どおり決済通知を受け取り続けます。
  • 注文作成のパラメーターではありません。注文ごとに上書きすることはできません。
  • 設定されていない場合、トークン化通知の動作は変わりません。

​
ユーザーのデフォルトカードを設定できますか？

はい。注文作成時ではなく、専用のエンドポイントで行います。トークンと希望する操作を指定して /api/v1/saved-payment-methods/config を呼び出します。 デフォルトカードは、顧客がチェックアウトで見る保存済みカード一覧の並び順に使用されます。期限切れのカードは一覧の末尾に移動します。

​
ユーザーのカードが銀行によって更新されました。保存済みトークンはまだ使えますか？

使えると想定しないでください。Waffo は現在、発行側の更新情報から保存済みカードを自動的に更新することはないため、 再登録を計画してください。
  • トークンが使用不能になったことを報告するトークン化通知や決済通知を監視し、ユーザーにカードの再登録を促してください。
  • ウォレット側または発行側でカードの連携が解除された場合、保存済み認証情報は使用不能になり、再有効化はできません。
  • 期限切れのトークンはもう課金できませんが、ユーザーに新しいカード情報を求める前に、/api/v1/tokenization/remove を 呼び出して登録を解除することは可能です。
サブスクリプションでは、サブスクリプションにバックアップの決済手段を持たせることが実務的な安全策です。 サブスクリプションのライフサイクル を参照してください。