> ## 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 のチェックアウトを使わず、自社で決済ページを構築する

> 加盟店が自社で構築するチェックアウトが Waffo から得られるもの・得られないもの：orderAction.actionData に値が入るのはいつで空になるのはいつか、どの決済手段が生データとして返ってくるのか、必須の顧客フィールドを検証するのは誰か、決済手段の利用可否と金額範囲を自分で照会する方法、ホスト型と自社構築を注文ごとに併用できるか、そして Waffo のホスト型チェックアウトでしか行われない処理。

[連携方式の選択](/docs/ja/developer-docs/use-cases/checkout-solution)
では 2 つのモードを比較し、それぞれが必要とするリクエストパラメーターを説明しています。
このページは、自社ページを構築すると決めた**後**に出てくる質問に答えます。実際にどのデータを受け取るのか、
自分で何をしなければならないのか、そしてフローのどの部分に加盟店側の代替手段がないのかです。

`orderAction.actionData` のフィールドごとのリファレンスは
[API リファレンステーブル](/docs/ja/support/api-reference-tables) にあります。
このページでは繰り返しません。

## 自社の決済ページを構築する場合、何を受け取り、何を処理する必要がありますか？

次の順序で 4 つです。

| ステップ | 行うこと | データの出所 |
| - | - | - |
| 1. 決済手段を決める | 自社ページで顧客の選択を収集する | 照会した一覧から構築した自社 UI（下記参照） |
| 2. 注文を作成する | `POST /api/v1/order/create` に `payMethodType` を、特定のウォレットの場合は `payMethodName` を渡す | [チェックアウトのカスタマイズ](/docs/ja/developer-docs/integration/checkout/customization) |
| 3. 決済手段の情報を提示する | `orderAction` を読み取る。顧客をリダイレクトする（`actionType` = `WEB` / `DEEPLINK`）か、`actionData` から生の情報を描画する | [リダイレクトと `actionType`](/docs/ja/support/cashier-redirect-and-action-type-faq) |
| 4. 結果を確認する | 決済通知（Webhook）、または `POST /api/v1/order/inquiry` | [決済結果](/docs/ja/support/payment-results-faq) |

自社ページを構築しても、ステップ 4 については何も変わりません。顧客が自社ページに戻ってきたことは決済の証明ではなく、
QR コードを描画したことも決済の証明ではありません。通知と照会が、引き続き唯一の正本です。

## `orderAction.actionData` に実際に値が入るのはいつですか？

**作成時点で注文が 1 つの特定の決済手段に確定していた場合のみ**です。これは加盟店構築のチェックアウトにとって最も重要な
ルールであり、見落とされやすい点です。

| `/api/v1/order/create` で送ったもの | 返ってくるもの |
| - | - |
| 特定の決済手段（`payMethodType`、およびタイプに複数のサブ決済手段がある場合は `payMethodName`） | リダイレクトのフィールドを持つ `orderAction`、**および**その決済手段に引き渡すべき情報がある場合は `actionData` |
| 決済手段なし — 選択を顧客に委ねた | Waffo のホスト型チェックアウトを指す `orderAction`。`actionData` は**空** |

理由は機械的です。顧客がまだ選択していなければ、決済手段への支払いは送信されておらず、口座番号も QR ペイロードも
有効期限も返せません。これらは決済手段が選ばれて初めて存在します。選択を顧客に委ねる場合、その選択は Waffo の
ホスト型ページで行われ、その時点でデータはそのページ以外に行き場がありません。

したがって、`actionData` が空で内容を期待していた場合は、まず作成リクエストの決済手段のパラメーターを確認してください。

## どの決済手段が生データとして返り、どれがリダイレクトを強制しますか？

`actionData` は、ルーティングされた決済手段が生成するものを運びます。大まかには：

| 決済手段の種類 | 期待できるもの |
| - | - |
| QR コード系 | `paymentQr` の QR ペイロード — 画像ではなく**文字列** |
| 店頭払い・コード系 | `paymentCode` および / または `paymentBarCode` |
| 銀行振込・バーチャル口座 | `bankAccount`、`bankName`、`bankBeneficiary`、`referenceNumber` |
| 自身の画面で承認するウォレット | 情報なし — 代わりにリダイレクト URL、または URL がまったくないアプリへのプッシュ |
| カード | 情報なし。カードデータの収集を `actionData` に委ねることはできない |

計画しておくべき 2 つの結果：

* **QR の描画は自社で行います。** `paymentQr` は生のペイロード文字列です。クライアント側で、スマートフォンのカメラで
  読み取れるサイズのスキャン可能なコードにエンコードしてください。
* **決済手段によっては複数のフィールドが埋まることも、どれも埋まらないこともあります。** どのフィールドが届くかは、
  取引がルーティングされた決済手段の性質であり、国やお客様のアカウントの性質ではありません。存在するフィールドを描画し、
  どれもない場合はリダイレクトにフォールバックするようページを構築してください。

## 現地の銀行口座番号 — CLABE、IBAN、バーチャル口座 — を取得できますか？

はい、同じフィールド `bankAccount` で取得できます。顧客が振り込むべき口座を、現地のシステムが使う形式で運びます —
メキシコの CLABE、他地域の IBAN、ルーティング番号と口座番号、あるいはその注文専用に生成されたバーチャル口座などです。
`bankName`、`bankBeneficiary`、`referenceNumber` が併せて返されます。

2 つの注意点：

* これは**それを返す銀行振込型・バーチャル口座型の決済手段**について値が入ります。任意の決済手段に対して要求できる
  フィールドではなく、抽象的に「CLABE をください」と言っても答えはありません。問いは常に、連携しようとしている特定の
  決済手段が `bankAccount` を返すかどうかです。画面を作る前に、決済手段ごとにサンドボックスで確認してください。
* 上記のルールは依然として適用されます。注文で決済手段を指定した場合にのみ取得できます。

ある決済手段が銀行振込のデータを返すかどうかを Waffo サポートに問い合わせる際は、使用予定の決済手段と送信予定の
`userInfo.userTerminal` を含めてください。端末タイプによってそもそも対象となる決済手段が変わるため、PC とモバイルの
セッションで答えが異なることがあります。

顧客が振り込んだ後にこれらのフィールドがどう振る舞うか — 有効期限、金額の相違、`referenceNumber` での照合 — は
[銀行振込とバーチャル口座](/docs/ja/support/bank-transfer-and-virtual-account-faq) を参照してください。

## `apiMethod` が `POST` です。フォームを自分で組み立てて送信する必要がありますか？

加盟店構築のチェックアウトでは、はい。`orderAction` はリダイレクトを完全に記述しており、`POST` のリダイレクトには
3 つの要素すべてが必要です。

| フィールド | 用途 |
| - | - |
| `actionType` | `WEB` → `webUrl` を使う。`DEEPLINK` → `deeplinkUrl` を使う |
| `apiMethod` | `GET` → その URL へ遷移する。`POST` → その URL へフォームを送信する |
| `formBody` | `a=1&b=2` 形式のフォームフィールド。分割して、ペアごとに hidden input を 1 つ出力する |

この際、パラメーターを削除したり再エンコードしたりしないでください。いくつかの決済手段は URL やボディに必須の値を
持っており、書き換えられた URL は Waffo ではなく決済手段側で失敗します。

代わりに Waffo のホスト型チェックアウトを使用する場合、これは自動的に処理されます。ページ自身がフォームを組み立てて
送信します。

## 決済手段の利用可否と金額上限を自分で照会する必要がありますか？

はい。これが加盟店構築のチェックアウトの主な継続コストであり、最も過小評価されがちな部分です。

| 維持すべきもの | 取得方法 |
| - | - |
| 自社アカウントが提供できる決済手段（国・通貨ごと） | `POST /api/v1/paymethodconfig/inquiry` — [決済手段の設定と上限](/docs/ja/support/payment-method-config-and-limits-faq) を参照 |
| 各決済手段が受け付ける金額範囲 | 注文作成前の、同じレスポンス |
| 決済手段が一時的に利用できないかどうか | 同じレスポンスのステータスフィールド |
| 新たに契約した決済手段 | 追加するまで自社ページには何も表示されません |

Waffo のホスト型チェックアウトでは、この 4 つすべてが自動です。利用できない決済手段はグレーアウトされ、金額範囲外の
決済手段は提示されず、新たに契約した決済手段はコード変更なしで表示されます。自社ページでは、古い一覧は顧客がすでに
決めた注文の失敗につながります。

## 決済手段が必要とする顧客フィールドは誰が検証しますか？

送信するフィールドについては、お客様です。いくつかの決済手段には、`/api/v1/order/create` 上では任意と記載されているが
**その決済手段では必須**となるフィールドがあります — 国民識別番号、電話番号、郵便番号、メールアドレスなど。自社ページで
それらを収集する場合、書式検証の責任はお客様にあり、Waffo からのフィードバックは注文作成呼び出しの拒否のみです。

どのフィールドがどの決済手段タイプで必須になるかの一覧は
[条件付き必須フィールド](/docs/ja/support/conditional-required-fields-faq) にあり、不足フィールドエラーに現れうる
フィールドパスも同じ場所にあります。

Waffo のホスト型チェックアウトでは、これらのフィールドはページ上で収集され、決済手段自身の書式ルールがその場で
適用されてから決済が送信されます。

## 両方を併用できますか — 一部の決済手段は自社構築、他はホスト型？

はい。しかもアカウント単位ではなく注文単位で決まります。同じ `/api/v1/order/create` エンドポイントで、
どちらの動作にもなります。

* 特定の決済手段を渡す → 顧客は Waffo の選択ページを見ることなく、自社画面を動かすための情報またはリダイレクトを受け取ります。
* 決済手段を渡さない → 顧客は Waffo のホスト型チェックアウトに着地し、そこで選択します。

よくある構成は、取引量の大半を占める 2〜3 の決済手段には自社ページを使い、ロングテールはホスト型チェックアウトに
フォールバックさせるというものです。これは、新しい決済手段がお客様側の変更なしに機能することも意味します。

できないのは、注文の途中で切り替えることです。チェックアウトセッションが決済手段に確定したら、そのセッションでは
その選択は固定です。

## 店頭払いの店舗選択ページを自分で作れますか？

セルフサービスの連携としてはできません。顧客が特定の店舗や取扱店を選ぶ店頭払いの決済手段では、店舗一覧は決済ステップ中に
Waffo のホスト型チェックアウトが提示します。`actionData` が返すのは顧客がカウンターに持っていく決済コードであり、
それを受け付ける場所の一覧ではありません。

したがって、加盟店構築のページはコードと案内を提示できますが、その元となる選択ステップには加盟店向けの代替手段がありません。
自社 UI 内にその画面が必要な場合は、パラメーターを探すのではなく、プロダクト要望として Waffo の担当者にご相談ください。

## カード決済用に自社ページを構築できますか？

PCI DSS の適用範囲に入る覚悟がある場合に限ります。それが
[連携方式の比較](/docs/ja/developer-docs/use-cases/checkout-solution#comparison) におけるトレードオフです。
Waffo のホスト型チェックアウトであれば、カードデータがお客様のシステムに触れることはありません。

適用範囲に入らずにページを制御できる中間的な選択肢が 2 つあります。

* **カードトークン化**：カードの入力欄を Waffo のフロントエンド SDK が自社ページ内に描画します。
  [トークン化](/docs/ja/support/tokenization-faq) を参照してください。
* **埋め込み型チェックアウト**：Waffo のチェックアウトが自社ページを置き換えるのではなく、自社ページ内に描画されます。
  [チェックアウト連携の手順](/docs/ja/developer-docs/integration/checkout/steps#iframe-embedding-considerations) を
  参照してください。

## Apple Pay は加盟店構築のチェックアウトで利用できますか？

はい — 自社の Apple 加盟店 ID を使った Apple Pay の直接連携は、Waffo のチェックアウトへのリダイレクト、
App WebView での読み込み、Waffo フロントエンド SDK による iframe での読み込みと並ぶ、サポートされた選択肢のひとつです。
4 つの選択肢とそれぞれの要件は
[Apple Pay の連携](/docs/ja/developer-docs/integration/apple-pay/overview) に記載されています。

利用できないのは、Apple Pay 向けにチェックアウト URL を単純に iframe に入れることです。この経路にはフロントエンド SDK と、
事前に手配されたドメイン検証が必要です。

## 自社構築のチェックアウトは、レポート、領収書、返金に影響しますか？

いいえ。決済後はすべて同一です。注文が同じ注文だからです。

| 領域 | 動作 |
| - | - |
| 決済通知 | 同じイベント、同じペイロード |
| 注文照会 | 同じエンドポイント、同じステータス |
| 返金 | 同じ `/api/v1/order/refund` と、同じ決済手段ごとの返金ルール |
| Portal の取引一覧とエクスポート | 取引は同じように表示される |
| 領収書 | 顧客がどのページで支払ったかではなく、領収書の設定に従う |

異なるのはすべて表示側です。決済手段の選択、必須フィールドの収集、決済情報の描画、ステータスのポーリング、そして結果画面です。

## ホスト型チェックアウトが行っていて、自分で作り直す必要があるものは何ですか？

着手前のチェックリストとして読む価値があります。

* 決済手段の選択、グルーピング、国ごとのランキング、および現在利用できない決済手段の非表示またはグレーアウト
* 各決済手段の必須顧客フィールドの収集と検証
* QR コードとバーコードの描画、およびコピー・保存操作の提供
* 決済結果のポーリングと、結果が届いた時点でのページの遷移。顧客が行き止まりの画面に取り残されないようにする
* 再試行可能なエラーの経路。一時的な失敗をバックグラウンドで再試行し、ページが自動的に進む
* 失敗後に、新しい注文を作らずに顧客が別の決済手段を選べるようにすること
* 金額の内訳 — 価格、割引、為替レートを適用した小計、顧客手数料、税、合計
* 表示言語。`cashierLanguage` を送信しなかった場合の言語選択も含む
* 顧客が後から再度開いたリンクに対する、期限切れ画面と支払い済み画面

***

まだ検討中ですか？ [連携方式の選択](/docs/ja/developer-docs/use-cases/checkout-solution)
に並列比較があります。加盟店構築の方式を選び、特定の決済手段が何を返すか確認が必要な場合は、決済手段、国、
送信予定の `userInfo.userTerminal` を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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