> ## 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.

# チェックアウトのフォーム、事前入力、エラー処理

> Waffo のチェックアウトで顧客が実際に入力する必要があるもの：貴社が送信した情報が事前入力されるか、決済手段の選択ページがスキップされるのはいつか、カードフォームの検証ルールと文字数、保存済みカードの動作、QR コードの有効期間、そしてどのチェックアウトエラーがリトライされ、どれが直接失敗ページに送られるか。

このページは、顧客が何を入力する必要があるか、そして何かが間違っていたときに何が起こるかについて説明します。どの決済手段がどの順序で表示されるかは「チェックアウトの決済手段表示ルール」ページで、ページレベルのブランディングは「チェックアウトページのカスタマイズ」ドキュメントで、再度開かれたリンク、処理中の状態、結果のリダイレクトは「チェックアウトページのライフサイクルと領収書」ページで扱っています。

## 注文作成時に顧客のメールアドレスと氏名を送信しています。なぜチェックアウトはまだそれらの入力を求めるのですか？

貴社が送信した値の再利用は、**デフォルトでオフのアカウントレベルの設定**であり、項目ごとに設定されるためです。貴社アカウントで有効化されるまで、チェックアウトは貴社の値を決済用のデータとして扱い、顧客に表示し返すものとしては扱いません。

このように動作する理由：連携のかなりの割合が、プレースホルダーや合成の連絡先情報を送信しています。明らかに偽のメールアドレスを購入者に表示し返すことは、最悪のタイミングで信頼を損ねますし、そうした値の一部は下流でいずれにせよ却下されます。項目ごとのオプトインにより、それらが購入者の目に触れないようにしています。

再利用できる項目は次のとおりで、個別に選択します。

| 項目 |
| - |
| `userInfo.userEmail` |
| `userInfo.userPhone` |
| `userInfo.userFirstName` |
| `addressInfo.postcode` |
| `addressInfo.address` |
| `addressInfo.city` |
| `addressInfo.region` |
| `addressInfo.addressCountryCode` |

排他的な **none** オプションがあります。項目を列挙するか、何も再利用しないと宣言するかのどちらかです。「none」と項目リストを組み合わせることはできません。

first name にはフルネームが入ることに注意してください。last name なしで first name を送信した場合、last name は推測されるのではなく空のまま保存されます。

貴社アカウントでこの設定を変更するには、再利用したい項目のリストを添えて Waffo の担当者にお問い合わせください。

## 顧客が私の送信したメールアドレスを編集した場合、どちらの値が使われますか？

顧客の値です。購入者がチェックアウトページで変更した値は、その決済の残りの処理において、決済手段に渡される内容を含め、貴社が送信した値を置き換えます。これは意図的なものです。自分の連絡先を知っているのは購入者であり、住所を検証したり確認メールを送信する決済手段では、古い値を使うと決済が失敗してしまいます。

貴社の元の注文データは変更されません。元々何を送信したかを知る必要がある場合は、注文レコードを確認してください。

## リピーターの顧客は毎回すべてを入力し直す必要がありますか？

いいえ。2 つの別々の仕組みがあり、混同されやすいものです。

| 仕組み | 誰のデータか | 制御するもの |
| - | - | - |
| **保存された情報** | 顧客が以前の購入時に入力した内容 | 顧客自身。フォームの「情報を保存する」オプションによる |
| **加盟店の事前入力** | 貴社が注文で送信した内容 | 上記の貴社アカウント設定 |

## チェックアウトが決済手段の選択ページをスキップするのはいつですか？

3 つのルールが、この順序で評価されます。

| 状況 | 顧客が最初に見るもの |
| - | - |
| 注文がちょうど **1 つのグループに解決され、それがカードグループ**である | カードフォームが直接表示されます |
| 注文がちょうど **1 つのグループ、かつちょうど 1 つの決済手段**に解決され、その決済手段がフォームを必要とする | その決済手段のフォームが直接表示されます |
| それ以外 | 選択ページ |

さらに、注文で `payMethodId` を渡し、その決済手段が入力を必要とする場合、チェックアウトは選択ページではなくその決済手段のフォームを直接開きます。入力を必要としない `payMethodId` を渡した場合は、選択ページでそのグループが事前選択されます。

`payMethodId` が渡されない場合、事前選択されるのは、利用可能な決済手段を持つ最初のグループ内の**最初に利用可能な**決済手段です。利用できない決済手段が事前選択されることはありません。

## カードフォームの正確な検証ルールは何ですか？

| 項目 | ルール |
| - | - |
| カード番号 | 必須。入力中にフィールドが挿入するスペースを含め、表示上 **17〜23 文字** |
| 有効期限 | 必須。ちょうど **5 文字**（`MM/YY`）で、日付は未来でなければなりません |
| CVV | 必須。文字数はカードブランドによります。下記を参照 |
| カード名義人 | 必須。**100 文字**まで。ラテン文字のみ |

CVV の文字数は、カード番号からブランドが特定された時点でブランドに基づいて決まります。

| ブランド | CVV の文字数 |
| - | - |
| American Express | ちょうど 4 |
| Visa | ちょうど 3 |
| Mastercard | ちょうど 3 |
| ブランド未特定、またはその他 | 3〜4 を受け付け |

したがって、番号が不完全な時点では受け付けられていた CVV が、ブランドが判明した時点で無効になることがあります。これは想定どおりの動作です。

## 複数の項目が間違っているのに、エラーメッセージが 1 つしか表示されないのはなぜですか？

各項目には**最大 1 つのメッセージ**が表示されます。表示されるのは、必須 → 形式 → 短すぎる → 長すぎる の順で最初に違反したルールです。メッセージは項目が操作された後に表示されます。支払いボタンを押すとすべての項目が操作済みとしてマークされるため、送信時には違反した各項目にそれぞれ 1 つのメッセージが表示されます。

1 つだけ異なる動作をするケースがあります。\*\*「This card is currently not supported」\*\*は、入力中のカード番号に対してリアルタイムで評価されるため、フィールドを離れる前に表示されることがあります。しかしこれもカード番号フィールド上のメッセージであるため、番号自体の文字数や形式の問題が先に報告されます。番号を修正すると、残るのはカード非対応のメッセージです。

このメッセージは、フォームの形式が不正なのではなく、カード自体が対象外（種類、ブランド、発行地域が受け付けられない）であることを意味します。同じフィールドで表示される可能性のある関連コード：

| コード | 意味 |
| - | - |
| `008001B027` | このカードは現在サポートされていません |
| `008001B028` | カードの種類がサポートされていません |
| `008001B029` | カードの発行地域が受け付けられません |
| `008001B030` | カードのブランドがサポートされていません |
| `008001B125` | カード名義人は英字のみで入力する必要があります |

## 保存済みカードを持つ顧客には何が表示されますか？

注文で `userPaymentAccessToken` を渡した場合、チェックアウトは短い完了ステップに直接進みます。カードはマスクされて表示され、顧客が入力する必要がある**唯一**の項目は **CVV** です。カード照会ステップは完全にスキップされるため、このページではキー入力ごとのカードチェックは行われません。

決済手段を指定**しない**場合、選択ページには、貴社アカウント下でその顧客に紐付けられているカードが、新しいカードを追加するオプションとともに一覧表示されます。各顧客は加盟店ごとに 1 枚のデフォルトカードを持つことができ、チェックアウトはそれを事前選択します。API を通じて、特定の注文で提示する保存済みカードを制限することもできます。

削除済みまたは期限切れのトークンは、黙って無視されるのではなく却下されます。コード `008001B113` は、カードが削除されたことを意味します。

## 顧客は次回のためにカードを保存することを選択できますか？

フォームには保存オプションが提示され、表示されるかどうかは決済手段と貴社アカウントによります。

| 決済手段の種類 | 保存オプションが表示される条件 |
| - | - |
| クレジット / デビットカード | その決済手段について、貴社アカウントでカード保存が有効になっている |
| それ以外すべて | 貴社アカウントで、顧客が入力した情報の保存が有効になっている |

注文からこれを制御することもできます。`paymentInfo.bindForFutureUse`（`0` = いいえ、`1` = はい）は、その決済において決済手段を将来の利用のために紐付けることを要求します。黙って保存されることはありません。顧客はフォーム上でオプションを確認します。

保存されたカードがその後どこに表示され、後でどのように課金するかは、トークン化のドキュメントで扱っています。

## 注文で固定のカード番号プレフィックスを渡しています。フォームは変わりますか？

はい。注文でカード番号の先頭の数字が固定されている場合、チェックアウトはその数字を入力欄の前に編集不可のプレフィックスとして表示し、番号フィールドが受け付ける文字数は、すでに表示されている桁数分だけ短くなります。顧客は残りの部分だけを入力し、受け付けられる合計の文字数は変わりません。

## サンドボックスのチェックアウトにテストカードはありますか？

はい。サンドボックスでは、カードフォームのフィールドの上にクイック入力用のカードチップが表示され、クリックすると番号、有効期限、CVV、名義人が入力されます。これらはサンドボックス環境でのみ表示されます。本番環境でこれらを表示するコードパスは存在しないため、本番稼働前に何かをオフにする必要はありません。

## 顧客は QR コードを保存して後で支払うことができますか？

いいえ。これは貴社自身のサポート用テンプレートに入れておく価値があります。

* QR コードは**その決済試行のみ**に有効です。再利用可能な支払先アドレスではなく、後の注文のために再提示することはできません。
* 注文が期限切れまたは成功した後は、チェックアウトリンクを再度開いても QR コードは一切表示されません。リンクは実際の注文状態に応じて失敗ページまたは成功ページに解決されます。
* **QR コード画像を保存**ボタンは**モバイルのみ**で提供されます。デスクトップでは表示されません。デスクトップで保存されたスクリーンショットこそが、顧客に期限切れのコードで支払おうとさせる原因だからです。

## チェックアウトページにエラーが表示されていますが、ぐるぐる回り続けています。止まっているのですか？

いいえ。それはリトライ可能な経路です。チェックアウトに届くすべてのエラーにはリトライ可能フラグが付いており、ページはそれぞれで異なる動作をします。

| エラーの種類 | 顧客が見るもの |
| - | - |
| **リトライ不可** — 拒否、限度額、検証、期限切れリンク | 結果は最終的です。ページは理由とともに**失敗ページ**に移動します |
| **リトライ可能** — タイムアウト、システムエラー、同時操作の競合 | ページは**処理中ビュー**に留まり、理由を表示し、Waffo はバックグラウンドでリトライを続けます。リトライで結果が得られると、ページは自動的に進みます |

リトライ可能な経路では顧客が再送信する必要はなく、貴社がその上にクライアント側のリトライを構築するべきではありません。最終状態の正としては、ページがある時点で表示していた内容ではなく、決済通知または注文照会を扱ってください。

## どのチェックアウトエラーコードを認識しておくべきですか？

完全なリストは長く、その大半はイシュアー起因です。以下は連携テストでよく出てくる、原因が貴社側または顧客側にあるものです。

| コード | メッセージ | 通常の意味 |
| - | - | - |
| `008000S006` | Timeout. Please try again later | 一時的。リトライ可能 |
| `008001B003` | Payment link expired. Please create another payment | チェックアウトリンクの有効期間が過ぎた |
| `008001B007` | You have submitted, please refresh the page | 同じステップの重複送信 |
| `008001B011` | Please input the correct phone number | 電話番号の形式が却下された |
| `008001B025` | Sorry your payment order has expired | リンクだけでなく注文が期限切れになった |
| `008001B049` | Order has expired, please place a new order | 同上。決済ステップから |
| `008001B058` | OTP has expired. Please request a new one | ワンタイムコードがタイムアウトした |
| `008001B059` | OTP verification failed. Please try again | ワンタイムコードが誤っている |
| `008001B092` | No payment methods are available for this region | 解決された国に一致するものが貴社の契約にない |
| `008001B099` | The transaction currency is not supported | 解決された決済手段でその通貨が有効になっていない |
| `008001B101` | Invalid postcode | 郵便番号が決済手段の形式チェックに失敗した |
| `008001B116` | Receipt link expired | 領収書リンクの有効期間が過ぎた。領収書のドキュメントを参照 |
| `008001B124` | Today's verification attempts have reached the limit | 日次の検証回数上限に達した。顧客は翌日にリトライする必要がある |

`008001B03x`〜`008001B09x` 範囲のコードは、ほぼすべてがイシュアーまたはウォレットの判断をそのまま中継したものです。顧客にはそのまま表示され、同じ決済手段でリトライしても成功に変えることはできません。

## 一部の決済で顧客にメールアドレスやメールの認証コードを求めるのはなぜですか？

特定の決済手段は、決済を受け付ける前に検証済みのメールアドレスを必要とするため、チェックアウトはそれを収集し、必要な場合はそのアドレスに送信されたワンタイムコードで検証します。これはルーティングされた決済手段の要件であり、Waffo が加盟店ごとに追加しているものではありません。

想定される動作：

* 利用可能な `userInfo.userEmail` を送信した場合、それがフィールドに事前入力されることがあります。一部の決済手段では、アドレスはその決済に対して固定され、顧客は置き換えることができません。この場合、同じステップで別のアドレスを送信すると却下されます。
* ワンタイムコードの有効期間は短いです。検証に成功すると、その注文において一定期間記憶されるため、顧客は決済を完了する間に検証を繰り返す必要はありません。
* このステップでのメールアドレスは 50 文字が上限です。
* 顧客がチェックアウトセッション内で決済手段を選択すると、その選択はそのセッションの間固定されます。

***

再現できない検証メッセージが表示されていますか？
注文 ID、表示された正確なコード、顧客がモバイルかデスクトップかを添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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