> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# トークン化とカード決済 FAQ

> Waffo のカードトークン化に関する最もよくある質問への回答：トークンとは何か、取得方法、トークンのライフサイクル、CIT と MIT の違い、初回決済と後続の課金、期限切れまたは無効なトークンの扱い。

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

## カードトークン化とは何ですか？ `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 つの値があります。

| ステータス | 意味 |
| - | - |
| `UNVERIFIED` | カード情報は送信されたが、このトークンでの決済がまだ成功していない。CIT として課金することは可能。 |
| `VERIFIED` | カードが検証済み。 |
| `EXPIRED` | トークンが期限切れ。 |
| `SUSPENDED` | 使用が停止されている。 |

トークンのステータスが変わるか、トークンデータが更新されるたびに `TOKENIZATION_NOTIFICATION` を受信します。
処理後は `success` で応答してください。Waffo が `failed` または `unknown` を受信した場合、Waffo は翌日にかけて
バックオフスケジュールで通知を再試行します。スケジュールは
[Webhook の再試行](/docs/ja/developer-docs/webhook/retry) を参照してください。

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

2 つの異なる時計があり、固定期間なのはそのうち 1 つだけです。

| 対象 | 有効期間 |
| - | - |
| `/api/v1/tokenization/generate` が返す `tokenSessionId` | **短期**（作成からプラットフォーム固定の期間）かつ使い切り。カードが一度送信されると、そのセッションは消費されます。事前ではなく、顧客がカードを入力する直前に開いてください |
| カードの `tokenId` | 次の**いずれか早い方**：トークン作成時から数えたプラットフォーム固定の複数年の有効期間、またはカード自体の有効期限月の最終時刻 |

したがって、有効期限が近いカードは今日登録しても有効期限月の末で使用できなくなるトークンを生成し、
有効期限が遠いカードはプラットフォームの有効期間いっぱい使えるトークンを生成します。

実務上の 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 つの登録呼び出しはいずれも冪等ですが、その方法は異なります。

| 繰り返しの呼び出し | 動作 |
| - | - |
| すでに使用した `tokenRequestId` で `/api/v1/tokenization/generate` を呼び出す | 新しいセッションを開くのではなく、既存のセッションのデータを返します。タイムアウト後に安全に再試行でき、2 つ目のセッションを消費しません。 |
| すでにトークンを持つ `tokenSessionId` に対してカードを送信する | 同じカードであれば同じ結果が返されます。同じセッションに**別の**カードを送信すると、冪等性の競合として拒否されます。カードごとに新しいセッションを 1 つ使用してください。 |

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

| モード | 内容 | 送信方法 |
| - | - | - |
| CIT（Customer Initiated Transaction） | 顧客が能動的に決済に参加する — たとえば、チェックアウトで保存済みカードを使って支払う。 | `userPaymentAccessToken` にトークンを入れて `/api/v1/order/create` を呼び出す。`merchantInitiatedMode` は設定しない。 |
| MIT（Merchant Initiated Transaction） | **顧客の関与なしに**ユーザーに課金する — たとえば、お客様自身がスケジュールする更新や従量課金の引き落とし。 | `userPaymentAccessToken` **と** `merchantInitiatedMode`（`scheduled` または `unscheduled`）を設定して `/api/v1/order/create` を呼び出す。 |

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` が存在する場合は常に
ユーザーのステップが残っていると想定してください。

| | 保存済みトークンでの CIT | MIT |
| - | - | - |
| ホスト型チェックアウト | 使用される — ユーザーは `orderAction` から操作を完了する | 使用されない。MIT 注文は意図的にチェックアウトへ到達しないようブロックされる |
| 作成レスポンス | 一般に `AUTHORIZATION_REQUIRED` と `orderAction` | 課金試行はサーバー側で実行される。ユーザーのステップもチェックアウト URL もない |
| CVV の再入力 | 通常、ホスト型ページで求められる | 求められない |
| `threeDsDecision` | カード / ApplePay / GooglePay で尊重される | 無視される |
| 失敗後の再試行 | アカウントでユーザー再試行が有効な場合、ホスト型ページが同じ注文でユーザーにもう一度の試行を提示できる | 同じ注文では再試行されない。再試行するには新しい注文を作成する |

顧客が不在の状態で課金する必要がある場合、それこそが `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` を呼び出します。

| 操作 | 効果 |
| - | - |
| `SET_DEFAULT` | そのカードをユーザーのデフォルトにします。ユーザーごとのデフォルトは最大 1 つなので、以前のデフォルトは置き換えられます。 |
| `SUSPEND` | 保存済みカードを停止し、提示されないようにします。 |

デフォルトカードは、顧客がチェックアウトで見る保存済みカード一覧の並び順に使用されます。期限切れのカードは一覧の末尾に移動します。

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

使えると想定しないでください。Waffo は現在、発行側の更新情報から保存済みカードを自動的に更新することはないため、
再登録を計画してください。

* トークンが使用不能になったことを報告するトークン化通知や決済通知を監視し、ユーザーにカードの再登録を促してください。
* ウォレット側または発行側でカードの連携が解除された場合、保存済み認証情報は使用不能になり、再有効化はできません。
* **期限切れのトークン**はもう課金できませんが、ユーザーに新しいカード情報を求める前に、`/api/v1/tokenization/remove` を
  呼び出して登録を解除することは可能です。

サブスクリプションでは、サブスクリプションにバックアップの決済手段を持たせることが実務的な安全策です。
[サブスクリプションのライフサイクル](/docs/ja/support/subscription-lifecycle-management) を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.