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

# 自社アプリ内でチェックアウトを読み込む（WebView、アプリ起動、復帰）

> WebView インテグレーションガイドが答えていないアプリ側の疑問に答えます：Waffo は WebView を検出して顧客に警告するのか、どのドメインを許可すべきか、顧客が戻ってこない場合にアプリはどう決済結果を知るのか、ウォレットアプリを往復した後にチェックアウトは自動で更新されるのか、決済リダイレクトリンクは 2 回開けるのか、ウォレットが開かないときに何を記録すべきか、なぜアプリ起動をサンドボックスでテストできないのか、そして決済手段をアプリ環境だけで非表示にできるのか。

チェックアウトをアプリの WebView に埋め込む仕組み — WebView が許可すべきもの、Android と iOS で
非 HTTP(S) スキームをインターセプトする方法、`net::ERR_UNKNOWN_URL_SCHEME` のトリアージ方法 — は
[チェックアウトのインテグレーション手順](/docs/ja/developer-docs/integration/checkout/steps#app-webview-integration-considerations)
に、決済手段ごとの例外は
[決済手段のインテグレーションノート](/docs/ja/developer-docs/tools-and-references/references/payment-method-integration-notes)
にあります。まずそれらをお読みください。このページは、それらの周辺で出てくる疑問に答えます。

## WebView インテグレーションをリリースする前に実行できるチェックリストはありますか？

はい — 以下は決済フローが依存しうる機能です。アプリがブロックする機能が 1 つあるごとに、
段階的に劣化するのではなく、決済手段が使えなくなります。

| 機能 | 決済フローがそれを必要とする理由 | 詳細の場所 |
| - | - | - |
| 非 HTTP(S) スキームから外部アプリを開く | 自身のアプリ内で認可するウォレット系決済手段 | [手順 → カスタムスキーム](/docs/ja/developer-docs/integration/checkout/steps#handle-wallet-app-custom-schemes) |
| 外部ブラウザを開く | 加盟店アプリの WebView 内では動作しないと明記されている決済手段 | [決済手段のインテグレーションノート](/docs/ja/developer-docs/tools-and-references/references/payment-method-integration-notes) |
| ダウンロード、コピー、長押し保存 | QR コード、支払いコード、銀行口座情報 | 手順 → WebView の考慮事項 |
| URL とすべてのクエリパラメーターを保持する | 一部の決済手段はリダイレクトに必須の値を付加する | 手順 → WebView の考慮事項 |
| iframe にも埋め込む場合は `allow="payment"` と `strict-origin-when-cross-origin` のリファラー | ブラウザ決済 API とリファラーに敏感な決済手段 | [手順 → iframe](/docs/ja/developer-docs/integration/checkout/steps#iframe-embedding-considerations) |
| `userInfo.userTerminal` を正確に送信する | 端末種別が、そもそもどの決済手段が対象になるかを決める | [リダイレクトと `actionType`](/docs/ja/support/cashier-redirect-and-action-type-faq) |

## チェックアウト側で WebView 内にいるかどうかを検出できますか？Waffo は顧客に警告しますか？

チェックアウトはアプリの WebView 全般を検出しようとはせず、それらに対して「ブラウザで開いてください」という
案内も表示しません。例外が 1 つあります。決済フローが動作しないことがわかっている**メッセージングアプリの
内蔵ブラウザ**内でチェックアウトが開かれた場合、顧客に別の場所でリンクを開くよう求めるブロッキングダイアログを
表示し、リンク全体を表示してコピーボタンを提供します。そのページで続けても失敗するため、このダイアログは閉じられません。

自社アプリについては、検出はお客様側の責務です。WebView を制御しているのはお客様なので、すでにわかっているはずです。
その情報を注文作成時に活用してください — 後述のアプリ環境で決済手段を非表示にする質問を参照してください。

## WebView でどのドメインを許可する必要がありますか？

Waffo のチェックアウトドメインを許可してください。そして、決済フローの制御手段としてドメインの許可リストを使わないでください。

チェックアウトの URL は Waffo ドメイン上の HTTPS ですが、その後の決済ステップでは決済手段自身のドメインへ遷移し、
ウォレット起動の場合は決済ページが実行時に決定する非 HTTP(S) スキームへ遷移します。この下流の集合は各決済手段の
属性であり、お客様側の変更なしに変わるため、固定できるリストは存在しません。固定されたホスト集合だけを許可するアプリは、
インテグレーションテストには合格しても、テストしていない決済手段で失敗します。

サポートされる形は
[手順 → カスタムスキーム](/docs/ja/developer-docs/integration/checkout/steps#handle-wallet-app-custom-schemes)
にあるものです。HTTP(S) のナビゲーションは WebView 内に留め、検証済みの非 HTTP(S) ナビゲーションは OS に渡してください。

## 顧客が WebView を離れてウォレットアプリで支払いました。アプリはどうやって結果を知るのですか？

WebView ではなく、お客様のサーバー経由です。信頼性の順序は固定されており、アプリの文脈でも変わりません。

| シグナル | 用途 |
| - | - |
| `notifyUrl` への決済通知 | 正式な結果。サーバーがアプリに伝える |
| `POST /api/v1/order/inquiry` | 確認や追いつき — たとえばアプリの復帰時 |
| `successRedirectUrl` / `failedRedirectUrl` / `cancelRedirectUrl` | 顧客の画面のナビゲーションのみ |

実務的なアプリのパターン：アプリがフォアグラウンドに戻ったとき、WebView から何かを読み取るのではなく、
自社バックエンド（通知または照会で状態を知っている）に注文状態を問い合わせてください。これは、顧客がリダイレクトに
従わず手動でアプリに切り替えて戻ってきた場合にも機能するパターンです。

リダイレクトが結果ではない理由の詳細は [決済結果](/docs/ja/support/payment-results-faq) を参照してください。

## 顧客がリダイレクトを経由せず、直接アプリに戻ってきました。この注文はどう扱えばよいですか？

特別なことは何もありません — とくに、失敗として扱わないでください。プラットフォームの視点では、注文は決済手段が
残した状態そのままであり、リダイレクトがスキップされたことはその状態について何も教えてくれません。

* 注文を照会するか、通知を待ってください。どちらも実際の状態を返します。
* 顧客が戻ってこなかったからといって、注文をクローズ、キャンセル、再作成しないでください。それが重複決済の起こり方です。
* 支払いがまだ保留中なら、顧客は注文の有効期間内に、ウォレットアプリで後から完了させる可能性が十分にあります。

## 顧客が WebView に戻ってきました。チェックアウト画面は自動で結果を更新しますか？

はい。チェックアウトが保留状態 — リダイレクト待ち、QR コードなどの支払い案内の待機、処理中 — にある間、
ページはバックオフ間隔で注文状態をポーリングし、結果が届くと自動的にページを進めます。顧客が通常非常に速く支払う
一部の QR コード決済手段では、コード表示直後にはより積極的にポーリングします。

リダイレクトページには明示的な再確認アクションもあります。押すと即座に注文を照会し、支払いがまだ完了していなければ、
完了したふりをせずにそのことを表示します。

したがって顧客は何もリロードする必要がなく、アプリも復帰時に WebView を強制リロードすべきではありません —
正常に進んでいたフローを再開させてしまうことがあります。

## 同じ決済リダイレクトリンクを 2 回開けますか？顧客がもう一度支払いをタップしたら動かなくなりますか？

決済手段によって異なり、お客様が制御することはできません。一部の決済手段は\*\*使い捨て（single-use）\*\*の
リダイレクト URL を発行し、一度消費されると再度開いても動作しません。他の決済手段は再度開くことを許可します。

ホスト型チェックアウトはどちらのケースに当たるかを把握しており、それを反映します。再度開くことが許可されている場合、
ページは顧客がウォレットに戻れるように **Pay** ボタンを引き続き表示します。許可されていない場合、ページは再確認
アクションのみを提供し、失敗する URL に顧客を送らないようにします。

2 つの帰結があります。

* ホスト型チェックアウトでは何もする必要がありません — ページがすでに両方のケースを処理しています。
* 加盟店が構築したチェックアウトでは、**リダイレクト URL を使い捨てとして扱ってください**。この属性は意図的に
  加盟店向けの `orderAction` に含まれていないため、分岐に使えるものはありません。リダイレクトは一度だけ提示し、
  その後は注文の照会にフォールバックしてください。

## 顧客が WebView で支払いをタップしましたが何も起きませんでした。サポートに連絡する前に何を記録すべきですか？

失敗した瞬間に以下の 5 点を記録してください。これらがなければ、報告を通常の「顧客が気を変えた」と区別できません。

1. WebView が受け取った**最後のナビゲーション URL**、完全かつ未変更のもの — スキームとすべてのクエリパラメーターを含む
2. その URL に対して WebView のナビゲーションコールバックがそもそも発火したか
3. 端末にインストールされたアプリのいずれかがそのスキームを処理できるか
4. 注文 ID とタイムスタンプ
5. 顧客がいたのは自社アプリの WebView か、外部ブラウザか、別のアプリのアプリ内ブラウザか

[手順 → トラブルシューティング](/docs/ja/developer-docs/integration/checkout/steps#troubleshoot-err_unknown_url_scheme-and-forbidden)
のトリアージ表が、よくある症状を原因に対応付けています。そこにあるルールに注意してください。端末機種や OS バージョンではなく、
失敗した URL のスキームと WebView によるその処理から診断してください。同じアプリビルドが OS バージョンによって異なる
挙動を示す場合、ほぼ常にナビゲーションコールバックへの到達方法の違いであり、プラットフォームレベルのブロックではありません。

## サンドボックスでウォレットアプリの起動を再現できないのはなぜですか？

サンドボックスは実際の決済手段に接続しないためです。サンドボックスのチェックアウトはシミュレーターです。ボタンを押して
結果を宣言するもので、実際の決済手段の選択、カード入力、ウォレットアプリへの引き渡しはありません。
[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator) を参照してください。

したがって、インテグレーションのアプリ起動部分 — スキームのインターセプト、URL の OS への引き渡し、復帰 — は、
本番環境で少額の実決済を使って検証する必要があります。サンドボックスが*役立つ*のはその周辺すべてです。
注文作成、通知処理、アプリ復帰ロジック、そして自社の復帰時注文状態確認フローです。

アプリへの引き渡しを伴う決済手段ごとに本番のスモークテストを計画し、実際のウォレットアカウントが必要になることを
見込んでおいてください。

## 自社のアプリ環境でだけ決済手段を非表示にできますか？

設定によっては不可能で、チェックアウトに「環境」パラメーターはありません。できること — そしてプラットフォームが
前提として設計されていること — は、注文ごとに決めることです。

* 自社アプリは自分がアプリであることを知っています。サーバーから `/api/v1/order/create` で `payMethodType` を、
  特定のウォレットには `payMethodName` を渡し、その環境で動作するものだけを注文で提示するようにしてください。
* `userInfo.userTerminal` を正確に送信してください。送信した端末種別をサポートしない決済手段は、そもそも提示されません。

いずれにせよ、注文ごとのフィルタリングはアカウントレベルのスイッチより堅牢です。同じアカウントは通常、そうした制限のない
Web フローも担っているからです。パラメーターのルールは
[チェックアウトのカスタマイズ](/docs/ja/developer-docs/integration/checkout/customization#payment-method-filtering) にあります。

## 最初から外部ブラウザでチェックアウトを開くべきですか？

正当な設計であり、一部の決済手段ではそれが唯一動作する方法です — 決済手段ごとのノートには、その決済手段自身のフローが
加盟店アプリの WebView 内で動作しないケースが列挙されています。

検討すべきトレードオフ：

| | アプリ内 WebView | 最初から外部ブラウザ |
| - | - | - |
| 顧客がアプリ内に留まる | はい | いいえ — 目に見えるアプリ切り替えが発生 |
| ウォレットアプリの起動 | アプリ側でスキームのインターセプトが必要 | ブラウザが処理 |
| ダウンロード / コピー / 長押し保存 | WebView で明示的な対応が必要 | 動作する |
| 支払い後のアプリへの復帰 | 自社のリダイレクト処理 | 顧客次第、またはディープリンクのリダイレクト URL |
| 加盟店アプリの WebView を拒否する決済手段 | 非表示にするか外部で開く必要がある | 特別な処理は不要 |

多くのインテグレーションが落ち着く中間的な方法：WebView 内で動作するフローには WebView を使い続け、
決済手段がそれを要求する注文だけ外部ブラウザで開く — 決済手段を選んだのはお客様なので、作成時点でわかります。

なお、`successRedirectUrl`、`failedRedirectUrl`、`cancelRedirectUrl` は HTTPS URL だけでなくディープリンクも
受け付けるため、外部ブラウザのフローでも顧客をアプリに戻すことができます。

## アプリ側の起動処理をラップしてくれる SDK はありますか？

Waffo のフロントエンド SDK がカバーするのは Web の領域 — カード項目のレンダリングと、ページへのチェックアウトの埋め込み — です。
アプリ側の部分 — WebView での非 HTTP(S) ナビゲーションのインターセプトと OS への引き渡し — は自社アプリ内のプラットフォーム API
であり、それを代替する Waffo のライブラリはありません。Android と iOS 双方のプラットフォームドキュメントへのリンクは
[手順 → カスタムスキーム](/docs/ja/developer-docs/integration/checkout/steps#handle-wallet-app-custom-schemes) にあります。

## チェックアウトリンクを SMS やメールで顧客に直接送れますか？

それは支払いリンクの用途であり、独自の有効期限と再利用ルールを持つ別のプロダクト領域です —
[支払いリンク](/docs/ja/support/payment-link-faq) を参照してください。API で作成した注文のチェックアウト URL を送信用リンクとして
流用しないでください。それは 1 つの注文に属し、その注文とともに期限切れになり、注文が最終状態に到達するとリンクは
期限切れ画面を表示します。

***

原因を特定できない WebView の失敗に遭遇していますか？上記の記録リストの 5 項目を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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