net::ERR_UNKNOWN_URL_SCHEME のトリアージ方法 — は
チェックアウトのインテグレーション手順
に、決済手段ごとの例外は
決済手段のインテグレーションノート
にあります。まずそれらをお読みください。このページは、それらの周辺で出てくる疑問に答えます。
WebView インテグレーションをリリースする前に実行できるチェックリストはありますか？
はい — 以下は決済フローが依存しうる機能です。アプリがブロックする機能が 1 つあるごとに、 段階的に劣化するのではなく、決済手段が使えなくなります。チェックアウト側で WebView 内にいるかどうかを検出できますか？Waffo は顧客に警告しますか？
チェックアウトはアプリの WebView 全般を検出しようとはせず、それらに対して「ブラウザで開いてください」という 案内も表示しません。例外が 1 つあります。決済フローが動作しないことがわかっているメッセージングアプリの 内蔵ブラウザ内でチェックアウトが開かれた場合、顧客に別の場所でリンクを開くよう求めるブロッキングダイアログを 表示し、リンク全体を表示してコピーボタンを提供します。そのページで続けても失敗するため、このダイアログは閉じられません。 自社アプリについては、検出はお客様側の責務です。WebView を制御しているのはお客様なので、すでにわかっているはずです。 その情報を注文作成時に活用してください — 後述のアプリ環境で決済手段を非表示にする質問を参照してください。WebView でどのドメインを許可する必要がありますか？
Waffo のチェックアウトドメインを許可してください。そして、決済フローの制御手段としてドメインの許可リストを使わないでください。 チェックアウトの URL は Waffo ドメイン上の HTTPS ですが、その後の決済ステップでは決済手段自身のドメインへ遷移し、 ウォレット起動の場合は決済ページが実行時に決定する非 HTTP(S) スキームへ遷移します。この下流の集合は各決済手段の 属性であり、お客様側の変更なしに変わるため、固定できるリストは存在しません。固定されたホスト集合だけを許可するアプリは、 インテグレーションテストには合格しても、テストしていない決済手段で失敗します。 サポートされる形は 手順 → カスタムスキーム にあるものです。HTTP(S) のナビゲーションは WebView 内に留め、検証済みの非 HTTP(S) ナビゲーションは OS に渡してください。顧客が WebView を離れてウォレットアプリで支払いました。アプリはどうやって結果を知るのですか？
WebView ではなく、お客様のサーバー経由です。信頼性の順序は固定されており、アプリの文脈でも変わりません。
実務的なアプリのパターン：アプリがフォアグラウンドに戻ったとき、WebView から何かを読み取るのではなく、
自社バックエンド（通知または照会で状態を知っている）に注文状態を問い合わせてください。これは、顧客がリダイレクトに
従わず手動でアプリに切り替えて戻ってきた場合にも機能するパターンです。
リダイレクトが結果ではない理由の詳細は 決済結果 を参照してください。
顧客がリダイレクトを経由せず、直接アプリに戻ってきました。この注文はどう扱えばよいですか？
特別なことは何もありません — とくに、失敗として扱わないでください。プラットフォームの視点では、注文は決済手段が 残した状態そのままであり、リダイレクトがスキップされたことはその状態について何も教えてくれません。- 注文を照会するか、通知を待ってください。どちらも実際の状態を返します。
- 顧客が戻ってこなかったからといって、注文をクローズ、キャンセル、再作成しないでください。それが重複決済の起こり方です。
- 支払いがまだ保留中なら、顧客は注文の有効期間内に、ウォレットアプリで後から完了させる可能性が十分にあります。
顧客が WebView に戻ってきました。チェックアウト画面は自動で結果を更新しますか？
はい。チェックアウトが保留状態 — リダイレクト待ち、QR コードなどの支払い案内の待機、処理中 — にある間、 ページはバックオフ間隔で注文状態をポーリングし、結果が届くと自動的にページを進めます。顧客が通常非常に速く支払う 一部の QR コード決済手段では、コード表示直後にはより積極的にポーリングします。 リダイレクトページには明示的な再確認アクションもあります。押すと即座に注文を照会し、支払いがまだ完了していなければ、 完了したふりをせずにそのことを表示します。 したがって顧客は何もリロードする必要がなく、アプリも復帰時に WebView を強制リロードすべきではありません — 正常に進んでいたフローを再開させてしまうことがあります。同じ決済リダイレクトリンクを 2 回開けますか？顧客がもう一度支払いをタップしたら動かなくなりますか？
決済手段によって異なり、お客様が制御することはできません。一部の決済手段は**使い捨て（single-use）**の リダイレクト URL を発行し、一度消費されると再度開いても動作しません。他の決済手段は再度開くことを許可します。 ホスト型チェックアウトはどちらのケースに当たるかを把握しており、それを反映します。再度開くことが許可されている場合、 ページは顧客がウォレットに戻れるように Pay ボタンを引き続き表示します。許可されていない場合、ページは再確認 アクションのみを提供し、失敗する URL に顧客を送らないようにします。 2 つの帰結があります。- ホスト型チェックアウトでは何もする必要がありません — ページがすでに両方のケースを処理しています。
- 加盟店が構築したチェックアウトでは、リダイレクト URL を使い捨てとして扱ってください。この属性は意図的に
加盟店向けの
orderActionに含まれていないため、分岐に使えるものはありません。リダイレクトは一度だけ提示し、 その後は注文の照会にフォールバックしてください。
顧客が WebView で支払いをタップしましたが何も起きませんでした。サポートに連絡する前に何を記録すべきですか？
失敗した瞬間に以下の 5 点を記録してください。これらがなければ、報告を通常の「顧客が気を変えた」と区別できません。- WebView が受け取った最後のナビゲーション URL、完全かつ未変更のもの — スキームとすべてのクエリパラメーターを含む
- その URL に対して WebView のナビゲーションコールバックがそもそも発火したか
- 端末にインストールされたアプリのいずれかがそのスキームを処理できるか
- 注文 ID とタイムスタンプ
- 顧客がいたのは自社アプリの WebView か、外部ブラウザか、別のアプリのアプリ内ブラウザか
サンドボックスでウォレットアプリの起動を再現できないのはなぜですか？
サンドボックスは実際の決済手段に接続しないためです。サンドボックスのチェックアウトはシミュレーターです。ボタンを押して 結果を宣言するもので、実際の決済手段の選択、カード入力、ウォレットアプリへの引き渡しはありません。 サンドボックスシミュレーター を参照してください。 したがって、インテグレーションのアプリ起動部分 — スキームのインターセプト、URL の OS への引き渡し、復帰 — は、 本番環境で少額の実決済を使って検証する必要があります。サンドボックスが役立つのはその周辺すべてです。 注文作成、通知処理、アプリ復帰ロジック、そして自社の復帰時注文状態確認フローです。 アプリへの引き渡しを伴う決済手段ごとに本番のスモークテストを計画し、実際のウォレットアカウントが必要になることを 見込んでおいてください。自社のアプリ環境でだけ決済手段を非表示にできますか？
設定によっては不可能で、チェックアウトに「環境」パラメーターはありません。できること — そしてプラットフォームが 前提として設計されていること — は、注文ごとに決めることです。- 自社アプリは自分がアプリであることを知っています。サーバーから
/api/v1/order/createでpayMethodTypeを、 特定のウォレットにはpayMethodNameを渡し、その環境で動作するものだけを注文で提示するようにしてください。 userInfo.userTerminalを正確に送信してください。送信した端末種別をサポートしない決済手段は、そもそも提示されません。
最初から外部ブラウザでチェックアウトを開くべきですか？
正当な設計であり、一部の決済手段ではそれが唯一動作する方法です — 決済手段ごとのノートには、その決済手段自身のフローが 加盟店アプリの WebView 内で動作しないケースが列挙されています。 検討すべきトレードオフ：
多くのインテグレーションが落ち着く中間的な方法：WebView 内で動作するフローには WebView を使い続け、
決済手段がそれを要求する注文だけ外部ブラウザで開く — 決済手段を選んだのはお客様なので、作成時点でわかります。
なお、
successRedirectUrl、failedRedirectUrl、cancelRedirectUrl は HTTPS URL だけでなくディープリンクも
受け付けるため、外部ブラウザのフローでも顧客をアプリに戻すことができます。
アプリ側の起動処理をラップしてくれる SDK はありますか？
Waffo のフロントエンド SDK がカバーするのは Web の領域 — カード項目のレンダリングと、ページへのチェックアウトの埋め込み — です。 アプリ側の部分 — WebView での非 HTTP(S) ナビゲーションのインターセプトと OS への引き渡し — は自社アプリ内のプラットフォーム API であり、それを代替する Waffo のライブラリはありません。Android と iOS 双方のプラットフォームドキュメントへのリンクは 手順 → カスタムスキーム にあります。チェックアウトリンクを SMS やメールで顧客に直接送れますか？
それは支払いリンクの用途であり、独自の有効期限と再利用ルールを持つ別のプロダクト領域です — 支払いリンク を参照してください。API で作成した注文のチェックアウト URL を送信用リンクとして 流用しないでください。それは 1 つの注文に属し、その注文とともに期限切れになり、注文が最終状態に到達するとリンクは 期限切れ画面を表示します。原因を特定できない WebView の失敗に遭遇していますか？上記の記録リストの 5 項目を添えて サポートにお問い合わせください。