tokenType は常に CARD ですか？
いいえ。CARD はほとんどの連携が使う値であり、公開仕様が文書化している唯一の値ですが、tokenType は汎用の
フィールドです。トークンサービスはカード以外の手段も含む一連のタイプを保持しており、特にウォレット系トークンは
必須フィールドと有効期限について異なるルールに従います（いずれも下記）。
これに対して行うべきこと：
"CARD"を、コードが生成・解析できる唯一の値としてハードコードしないでください。 照会レスポンスや通知からtokenTypeを読み戻し、見慣れない値は失敗させるのではなく保存して処理してください。- あるタイプが利用可能だと仮定しないでください。 貴社のアカウントが実際にトークン化できるタイプは、決済手段の 設定に従います。サポートされていないタイプは生成時にパラメーターエラーとして拒否されます。
- API を試して探るのではなく、貴社が保有する決済手段にどのタイプが該当するかを Waffo の連携担当者に確認してください。
ウォレット系トークンにはカードトークンにない何が必要ですか？
トークンデータ内に 3 つの追加フィールドが必要で、いずれも必須です。
いずれかが欠けると、生成は
A0003 Parameter validation failed で失敗します。
orderId の要件は理解しておく価値のある構造的な違いです。カードは単独でトークン化できますが、ウォレットのバインドは
ユーザーが支払いの過程で承認するものです。したがってウォレットトークンは、何もないところではなく実際の注文に
対して作成されます。実務上は、別立ての「決済手段を追加」のステップではなく、決済の一部としてリクエストします。
ウォレットトークンはどのくらい有効ですか？
したがって、ウォレットトークンにはカードの有効期限による上限に相当するものがなく（尊重すべき原資産の有効期限が
存在しないため）、有効期限は月境界ではなく日境界に落ちます。
そこから 2 つのことが導かれます。
- ウォレットトークンの残存期間をカードのロジックから導出しないでください。 トークンデータに推論の元となる
expiryフィールドはありません。 - ユーザーがウォレット側で承認を解除した場合、計算上の有効期限よりずっと前にトークンが機能しなくなることがあります。
これは課金が失敗するまで貴社からは見えません。
A0037（ユーザーの決済トークンが無効または期限切れ）は、 一時的なエラーではなく、再承認を促すシグナルとして扱ってください。
同じユーザーが同じウォレットを再度承認した場合、同じトークンが返りますか？
必ずしもそうではありません。ここがウォレットトークンとカードの最も大きな違いです。ウォレット系トークンの再利用キーには、 貴社のマーチャント ID（送信している場合はサブマーチャント ID も）、merchantUserId、トークンタイプ、決済手段に加えて、
バインドが行われた注文が含まれます。
新しい承認は新しい注文で行われるため、同じユーザーによる同じウォレットの 2 回目のバインドは通常新しい tokenId を
生成します。カードトークンは異なる挙動をします。そのキーは認証情報そのものに基づくため、同じカードを再バインドすると
既存のトークンが返ります（カード FAQ を参照）。
設計上の帰結：
- 保存は
tokenIdをキーにしてください。 ユーザーが時間とともに複数のウォレットトークンを蓄積することを想定してください。 - 膨らんでいく山ではなく、管理可能な一覧をユーザーに表示してください。 不要になったものは一時停止または バインド解除します（このページの最後のセクション）。
- トークンの存在を、ユーザーがウォレットのバインドをちょうど 1 つ持っている証拠として使わないでください。
カード以外のトークンの照会と削除では何を送る必要がありますか？
どちらのエンドポイントも、1 つの必須識別子ではなく条件付きの形をとります。
実務上の読み方：この 2 つの呼び出しにおいて
tokenType は飾りではありません。カードを前提に連携を構築して
tokenType を渡していない場合、2 つ目のトークン種別を追加すると、「トークンが存在しない」ように見える形で
検索が壊れます。
3 つのトークンエンドポイントはいずれも、ボディの merchantId が API キーの発行対象のマーチャント ID と一致することを
検証し、不一致は詳細 mid in params is inconsistent with apiKey とともに A0003 として拒否します。
トークナイゼーションの送信が拒否されたのはなぜですか？
署名やフィールドの形式の問題を除くと、カードの送信が拒否される業務上の理由は 3 つあります。3 つとも何かが保存される 前に判定され、3 つともその入力については恒久的です。同じデータで再試行しても同じように失敗します。
人々を驚かせる 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）は
カードトークナイゼーションのページにあります。挙動の違いも同じくらい重要です。
覚えておくべき一文：MIT の課金にはユーザーインターフェースもユーザーも存在しません。 リダイレクト、同意のステップ、
ユーザーが入力するフィールドなど、フローがチェックアウトページに依存しているものはここには存在しません。
MIT の課金が失敗しました。そのまま再試行すればよいですか？
やみくもに再試行しないでください。理由は 3 つあります。- ユーザー側の再試行がありません。 CIT の失敗はユーザーがチェックアウトページで別の手段を選ぶことで終われますが、 MIT の失敗はそこで終わりです。
- 一部の失敗はその認証情報について恒久的です。
A0045（保存された認証情報が使用可能な状態でない）とA0037（トークンが無効または期限切れ）は、再試行しても成功しません。解決策は、顧客主導の新しい承認です。 - 再試行自体がカードスキームのルールでレート制限されています — 次の質問を参照してください。
カード決済が試行される前に拒否されたのはなぜですか？
カードスキームが同じカード決済を何回再試行してよいかについてコンプライアンス上の制限を課しており、Waffo が ローカルでそれを適用しているからです。ある試行が制限に抵触する場合、転送されるのではなくシステムが拒否します。 そのため失敗が通常の拒否より速く返り、カードの明細には何も現れません。 カウントについて知っておくべきこと：- カードスキームごとにカウントされ、さらにそのスキーム自身によるマーチャントの分類に応じて別々にカウントされます。 同じ注文における異なるスキームの 2 枚のカードがまとめられることはありません。
- Waffo はしきい値を公開しておらず、リバースエンジニアリングを試みるべきではありません。しきい値はスキームが設定し、 貴社のアカウントに何の変更がなくても変わりうるものです。
- 失敗は失敗理由
CARD_PAYMENT_RETRY_LIMITとして現れ、API 上はC0005にマッピングされます。
- 拒否されたカード決済を即座に自動再試行しないでください。 異なる答えが得られる見込みがないまま許容回数を 消費します。
- 試行の間に何かを変えてください — 別の決済手段、カードの再入力、後のスケジュール — あるいはユーザーに尋ねてください。
- これに頻繁に当たる場合、問題は上流にあります。承認されないカードに対する再試行が多すぎるのです。
ユーザーは保存済みの決済手段を自分で管理できますか？
はい。注文作成ではなく 1 つのエンドポイントを通じて行います。POST /api/v1/saved-payment-methods/config で、
merchantId、merchantUserId、保存済み手段のトークン、そして action を受け取ります。
/api/v1/tokenization/remove（完全なバインド解除）と併せれば、「決済手段を管理する」画面（一覧、デフォルト設定、
非表示、削除）を一通り構築できます。それぞれがチェックアウトの並び順に与える影響は
カードトークナイゼーションのページにあります。
画面を設計する前に知っておくべき 2 つの境界：
- このエンドポイントは API キーの payin スコープにあるため、バックエンドからの呼び出しです。ブラウザやモバイル クライアントに直接公開しないでください。
- 削除は最終的です。削除されたトークンは検索から除外され、再発行されることはありません。取り消せるように見える 選択肢は一時停止です。削除は恒久的なものとして扱ってください。
どの話題がどちらのページに属しますか？
特定のバインドや課金が拒否された理由がまだ分かりませんか？
tokenRequestId または注文 ID を添えて
サポートにお問い合わせください。失敗理由はいずれにも記録されています。