> ## 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 が扱っていないトークナイゼーションの領域：CARD 以外のトークンタイプ、ウォレット系トークンの追加フィールドと固定の有効期限、トークナイゼーションの送信が拒否される理由、カード名義人名のルール、MIT が CIT と異なる挙動、カード決済がどこにも送信される前に拒否される理由、保存済み決済手段のセルフサービス管理。

[トークナイゼーションとカード決済](/docs/ja/support/tokenization-faq)が主たるページです。トークンとは何か、カードの
バインド方法、トークンのライフサイクル、カードのセッションとトークンの有効性、リクエストレベルでの CIT と MIT の違い、
デフォルトカードの設定を扱っています。**まずそちらをお読みください。**

このページはその補足です。基本的なカード連携を終えた後に出てくる疑問に答えます。カード以外のトークン、
トークナイゼーションの試行が拒否される業務上の理由、マーチャント主導の課金における挙動の違い、そしてカード決済が
どこにも送られる前に止まりうる制限です。

## `tokenType` は常に `CARD` ですか？

いいえ。`CARD` はほとんどの連携が使う値であり、公開仕様が文書化している唯一の値ですが、`tokenType` は汎用の
フィールドです。トークンサービスはカード以外の手段も含む一連のタイプを保持しており、特に**ウォレット系トークン**は
必須フィールドと有効期限について異なるルールに従います（いずれも下記）。

これに対して行うべきこと：

* **`"CARD"` を、コードが生成・解析できる唯一の値としてハードコードしないでください。** 照会レスポンスや通知から
  `tokenType` を読み戻し、見慣れない値は失敗させるのではなく保存して処理してください。
* **あるタイプが利用可能だと仮定しないでください。** 貴社のアカウントが実際にトークン化できるタイプは、決済手段の
  設定に従います。サポートされていないタイプは生成時にパラメーターエラーとして拒否されます。
* API を試して探るのではなく、貴社が保有する決済手段にどのタイプが該当するかを Waffo の連携担当者に確認してください。

## ウォレット系トークンにはカードトークンにない何が必要ですか？

トークンデータ内に 3 つの追加フィールドが必要で、いずれも必須です。

| フィールド | 理由 |
| - | - |
| `payMethodName` | そのトークンがどの決済手段に属するか |
| `payMethodCountry` | その決済手段のどの国の設定か |
| `orderId` | ユーザーがバインドを承認した注文 |

いずれかが欠けると、生成は `A0003` **Parameter validation failed** で失敗します。

`orderId` の要件は理解しておく価値のある構造的な違いです。カードは単独でトークン化できますが、ウォレットのバインドは
ユーザーが**支払いの過程で**承認するものです。したがってウォレットトークンは、何もないところではなく実際の注文に
対して作成されます。実務上は、別立ての「決済手段を追加」のステップではなく、決済の一部としてリクエストします。

## ウォレットトークンはどのくらい有効ですか？

| トークンの種類 | 有効期限 |
| - | - |
| カード | 作成時点からのプラットフォーム固定のトークン有効期間と、カード自身の有効期限月の最終時点の、**早い方** |
| ウォレット系 | 作成時点から**同じ固定**のプラットフォーム有効期間。その日の終わりに切り詰められます |

したがって、ウォレットトークンにはカードの有効期限による上限に相当するものがなく（尊重すべき原資産の有効期限が
存在しないため）、有効期限は月境界ではなく日境界に落ちます。

そこから 2 つのことが導かれます。

* **ウォレットトークンの残存期間をカードのロジックから導出しないでください。** トークンデータに推論の元となる
  `expiry` フィールドはありません。
* ユーザーがウォレット側で承認を解除した場合、計算上の有効期限よりずっと前にトークンが機能しなくなることがあります。
  これは課金が失敗するまで貴社からは見えません。`A0037`（**ユーザーの決済トークンが無効または期限切れ**）は、
  一時的なエラーではなく、再承認を促すシグナルとして扱ってください。

## 同じユーザーが同じウォレットを再度承認した場合、同じトークンが返りますか？

必ずしもそうではありません。ここがウォレットトークンとカードの最も大きな違いです。ウォレット系トークンの再利用キーには、
貴社のマーチャント ID（送信している場合はサブマーチャント ID も）、`merchantUserId`、トークンタイプ、決済手段に加えて、
バインドが行われた**注文**が含まれます。

新しい承認は新しい注文で行われるため、同じユーザーによる同じウォレットの 2 回目のバインドは通常**新しい** `tokenId` を
生成します。カードトークンは異なる挙動をします。そのキーは認証情報そのものに基づくため、同じカードを再バインドすると
既存のトークンが返ります（カード FAQ を参照）。

設計上の帰結：

* **保存は `tokenId` をキーにしてください。** ユーザーが時間とともに複数のウォレットトークンを蓄積することを想定してください。
* 膨らんでいく山ではなく、**管理可能な一覧をユーザーに表示してください。** 不要になったものは一時停止または
  バインド解除します（このページの最後のセクション）。
* **トークンの存在を、ユーザーがウォレットのバインドをちょうど 1 つ持っている証拠として使わないでください。**

## カード以外のトークンの照会と削除では何を送る必要がありますか？

どちらのエンドポイントも、1 つの必須識別子ではなく条件付きの形をとります。

| 呼び出し | ルール |
| - | - |
| `/api/v1/tokenization/inquiry` | `tokenId`、`merchantUserId`、`tokenRequestId` のうち少なくとも 1 つを指定します。`tokenId` がない場合、`tokenType` が**必須**になります。トークン ID がない場合、検索の範囲を決めるのはタイプだからです。 |
| `/api/v1/tokenization/remove` | `tokenType` が**必須**で、加えて `tokenId` または `merchantUserId` のうち少なくとも 1 つが必要です。 |

実務上の読み方：この 2 つの呼び出しにおいて `tokenType` は飾りではありません。カードを前提に連携を構築して
`tokenType` を渡していない場合、2 つ目のトークン種別を追加すると、「トークンが存在しない」ように見える形で
検索が壊れます。

3 つのトークンエンドポイントはいずれも、ボディの `merchantId` が API キーの発行対象のマーチャント ID と一致することを
検証し、不一致は詳細 `mid in params is inconsistent with apiKey` とともに `A0003` として拒否します。

## トークナイゼーションの送信が拒否されたのはなぜですか？

署名やフィールドの形式の問題を除くと、カードの送信が拒否される**業務上の**理由は 3 つあります。3 つとも何かが保存される
前に判定され、3 つともその入力については恒久的です。同じデータで再試行しても同じように失敗します。

| 理由 | 意味 | 対処 |
| - | - | - |
| カードの発行レンジが認識できない | 先頭の数字から Waffo がカードを識別できなかった | ユーザーに番号の確認、または別のカードの使用を依頼してください。同じ数字で再試行しないでください。 |
| カードのスキームまたはタイプが貴社の設定でカバーされていない | カードは実在するが、そのスキームまたは製品タイプが貴社のアカウントで有効になっていない | `A0031` **Card scheme or type provided by Merchant cannot be supported** として報告されます。これはデータの問題ではなく、Waffo の担当者に相談すべき設定の問題です。 |
| 有効期限が無効、またはすでに過去 | 有効期限は `MM/YYYY` 形式で、月は `01`〜`12`、過去であってはならない | 入力形式を修正するか、有効なカードを求めてください。 |

人々を驚かせる 2 点：

* **チェックディジットはゲートではありません。** 標準のチェックサムを通らないカード番号は警告として記録され、処理は
  続行されます。正式な判定は発行レンジの照会から来ます。したがってチェックサムによる拒否を期待しないでください。
  ただし、ユーザーのために早い段階で打ち間違いを捕捉できるよう、クライアント側のチェックサム検証は維持してください。
* **入力では `MM/YY` が受け付けられます**（収集 SDK において）。ただし照会と通知は常に `MM/YYYY` を返します。
  4 桁の形式で保存してください。

バインド時ではなく決済時に目にする可能性のある関連コード：`A0029`（カードデータが無効）、`A0030`（カードの発行レンジが
見つからない）、`A0032`（決済トークンのデータが無効）、`A0023`（トークンの期限切れにより注文を作成できない）。

## カード名義人名が拒否されるのはなぜですか？

ラテン文字以外の文字が含まれているからです。ルールは厳格で、カード名義人名は**英字のみ**を含む必要があります。
アクセント付き文字を含む名前や、ラテン文字以外の文字体系の名前は、失敗理由 `INVALID_CARDHOLDER_NAME` と
メッセージ *Cardholder name must contain only English letters* で拒否され、API 上では `A0029` として現れます。

うまく扱う方法：

* **収集時点で翻字してください。** 「カードに記載されているとおり」の名前を求めてください。カードはラテン文字で
  刻印されているため、正しい値はほぼ必ず存在します。
* ユーザーが決済時に気付くのではなく、**貴社自身のフォームで明確なメッセージとともに検証してください。**
* 名前はカードトークンの再利用キーの一部であることを覚えておいてください。同じカードでも綴りが異なる名前で送信されると
  別の認証情報として扱われ、独自のトークンが割り当てられます。

## MIT の課金は CIT の課金と何が異なりますか？

リクエストレベルの違い（`merchantInitiatedMode`、およびすでに使用可能な認証情報を要求する `A0045`）は
[カードトークナイゼーションのページ](/docs/ja/support/tokenization-faq)にあります。**挙動**の違いも同じくらい重要です。

| | CIT | MIT |
| - | - | - |
| Waffo のチェックアウトページに到達するか | フローが必要とする場合は到達する | **決して到達しない** — MIT の課金は設計上チェックアウトページからブロックされます |
| 3DS | リスクに応じて `threeDsDecision`（`3DS_FORCE` / `NO_3DS`）で影響を与えられる | `threeDsDecision` は**黙って無視されます** |
| 失敗後にユーザーが別の決済手段を選べるか | はい、チェックアウトページで | いいえ — ページもユーザーも存在しません |
| ユーザーの入力を必要とする税の収集 | チェックアウトページで収集可能 | この経路では利用できません |

覚えておくべき一文：**MIT の課金にはユーザーインターフェースもユーザーも存在しません。** リダイレクト、同意のステップ、
ユーザーが入力するフィールドなど、フローがチェックアウトページに依存しているものはここには存在しません。

## MIT の課金が失敗しました。そのまま再試行すればよいですか？

やみくもに再試行しないでください。理由は 3 つあります。

1. **ユーザー側の再試行がありません。** CIT の失敗はユーザーがチェックアウトページで別の手段を選ぶことで終われますが、
   MIT の失敗はそこで終わりです。
2. **一部の失敗はその認証情報について恒久的です。** `A0045`（保存された認証情報が使用可能な状態でない）と
   `A0037`（トークンが無効または期限切れ）は、再試行しても成功しません。解決策は、顧客主導の新しい承認です。
3. **再試行自体がカードスキームのルールでレート制限されています** — 次の質問を参照してください。

うまくいくパターン：失敗を分類してください。認証情報の問題は「ユーザーに再承認を依頼する」、本当に一時的な失敗は
「スケジュールに従って後で再試行する」です。短いループで再試行しないこと、そして MIT の拒否を、依頼なしにユーザーが
解決できるものとして扱わないことです。

サブスクリプションについては、自前で構築しないでください。Waffo 自身のリトライスケジュールとバックアップ決済手段の
処理がすでにそれを行っています。
[サブスクリプションのライフサイクルと決済手段の管理](/docs/ja/support/subscription-lifecycle-management)を参照してください。

## カード決済が試行される前に拒否されたのはなぜですか？

カードスキームが**同じカード決済を何回再試行してよいかについてコンプライアンス上の制限**を課しており、Waffo が
ローカルでそれを適用しているからです。ある試行が制限に抵触する場合、転送されるのではなくシステムが拒否します。
そのため失敗が通常の拒否より速く返り、カードの明細には何も現れません。

カウントについて知っておくべきこと：

* **カードスキームごと**にカウントされ、さらにそのスキーム自身によるマーチャントの分類に応じて別々にカウントされます。
  同じ注文における異なるスキームの 2 枚のカードがまとめられることはありません。
* Waffo はしきい値を公開しておらず、リバースエンジニアリングを試みるべきではありません。しきい値はスキームが設定し、
  貴社のアカウントに何の変更がなくても変わりうるものです。
* 失敗は失敗理由 `CARD_PAYMENT_RETRY_LIMIT` として現れ、API 上は `C0005` にマッピングされます。

正しい対処は数値ではなく行動によるものです。

* **拒否されたカード決済を即座に自動再試行しないでください。** 異なる答えが得られる見込みがないまま許容回数を
  消費します。
* 試行の間に**何かを変えてください** — 別の決済手段、カードの再入力、後のスケジュール — あるいはユーザーに尋ねてください。
* これに頻繁に当たる場合、問題は上流にあります。承認されないカードに対する再試行が多すぎるのです。

## ユーザーは保存済みの決済手段を自分で管理できますか？

はい。注文作成ではなく 1 つのエンドポイントを通じて行います。`POST /api/v1/saved-payment-methods/config` で、
`merchantId`、`merchantUserId`、保存済み手段のトークン、そして `action` を受け取ります。

| アクション | 効果 |
| - | - |
| `SET_DEFAULT` | その保存済み手段をユーザーのデフォルトにします。ユーザーごとのデフォルトは最大 1 つなので、以前のデフォルトは置き換えられます。 |
| `SUSPEND` | その保存済み手段がユーザーに提示されないようにします。 |

`/api/v1/tokenization/remove`（完全なバインド解除）と併せれば、「決済手段を管理する」画面（一覧、デフォルト設定、
非表示、削除）を一通り構築できます。それぞれがチェックアウトの並び順に与える影響は
[カードトークナイゼーションのページ](/docs/ja/support/tokenization-faq)にあります。

画面を設計する前に知っておくべき 2 つの境界：

* このエンドポイントは API キーの **payin** スコープにあるため、バックエンドからの呼び出しです。ブラウザやモバイル
  クライアントに直接公開しないでください。
* 削除は最終的です。削除されたトークンは検索から除外され、再発行されることはありません。取り消せるように見える
  選択肢は一時停止です。削除は恒久的なものとして扱ってください。

## どの話題がどちらのページに属しますか？

| 質問 | ページ |
| - | - |
| トークンとは何か、カードのバインド方法、セッションとトークンの有効性、同じカードの再バインド、デフォルトカード | [トークナイゼーションとカード決済](/docs/ja/support/tokenization-faq) |
| リクエストレベルの CIT と MIT、`A0045`、バインド結果の通知先 | [トークナイゼーションとカード決済](/docs/ja/support/tokenization-faq) |
| `CARD` 以外のトークンタイプ、ウォレットトークンのフィールドと有効期限、ウォレットの再承認 | このページ |
| トークナイゼーション送信の業務上の失敗、カード名義人名のルール | このページ |
| MIT の挙動、リトライ方針、スキームのリトライ制限 | このページ |
| 各エラーコードの一般的な意味 | [よくあるエラーのトラブルシューティング](/docs/ja/support/errors-troubleshooting-guide) |
| どの決済手段がどの返金を許可するか | [決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq) |

特定のバインドや課金が拒否された理由がまだ分かりませんか？ `tokenRequestId` または注文 ID を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。失敗理由はいずれにも記録されています。


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