メインコンテンツまでスキップ

ドメイン登録

加盟店コンソールで登録したドメインは、決済後の戻り先 returnUrl の検証に使います。

ブラウザには、決済の作成で返ってきた checkoutUrl を渡し、専用決済ページへ画面全体を移します（トップレベル遷移）。決済 ID を使って遷移先を自作しません。

returnUrl の条件​

returnUrl は、決済後に利用者が戻るページの URL です。https:// で始まり、ポート番号と userinfo（user:pass@）を付けず、ホスト名が加盟店コンソールで登録したドメインと完全に一致する（大文字小文字は区別しない。サブドメインは不可）ページを指定します。localhost は使えません。

登録ドメインが shop.example.com の場合の例です。

  • OK：https://shop.example.com/orders/123/return
  • NG：http://shop.example.com/…（https でない）
  • NG：https://other.example.com/…（別のドメイン）
  • NG：https://shop.example.com:8443/…（ポート付き）
  • NG：https://www.shop.example.com/…（サブドメイン）
  • NG：https://user:pass@shop.example.com/…（userinfo 付き）
  • NG：https://localhost/…

利用者を returnUrl へ移すのは、STBLpay の決済ページです。条件が無いと、偽サイトの URL を戻り先にした決済も作れてしまいます。利用者から見れば「STBLpay の画面から移った先」なので、偽サイトでも信用してしまいます（オープンリダイレクト）。戻り先を登録ドメインに限るのは、これを防ぐためです。

ドメインの登録​

EC サイトで決済を受け付けるには、ドメインの登録が必須です。 未登録のまま POST /payment_intents を呼ぶと、409 merchant/domain_required になります。

登録・変更・解除は、加盟店コンソールのメニューの「お店と QR コード」から対象のネットショップを開き、「組み込みの準備」タブにあるドメインの区画で行います。ドメインは加盟店単位なので、どのネットショップから開いても同じ値が出ます。

登録

  1. 「ドメイン（ホスト名）」にホスト名だけを入力する。https://・パス・ポート番号は含めない（例：shop.example.com）。
  2. 「登録する」を押す。

変更

  1. 「新しいドメイン（ホスト名）」に入力する。
  2. 「変更する」を押し、確認ダイアログでも「変更する」を押す。

変更すると、所有の証明は取り消されます。所有の証明を付け直す場合は、新しいトークンの設置と確認が必要です。作成済みの決済の戻り先は変わらず、新しい EC 決済は変更後のドメインで照合します。

解除

  1. 「登録を解除」を押す。
  2. 確認ダイアログで「解除する」を押す。

解除すると、EC サイトからの新しい決済を作成できなくなり、所有の証明も取り消されます。作成済みの決済の戻り先は変わりません。

IP アドレスや、複数のサイトで共有されているドメイン（公開サフィックスそのもの）は登録できません。お使いのサイトのホスト名を入力してください。

所有の証明（任意）​

所有の証明は任意です。登録したドメインの「所有の証明（任意）」に表示されるトークンを、次の 3 つのうち いずれか 1 つの方法で設置してから、「設置した値を確認する」を押します。

方法設置する場所値
DNS の TXT レコードレコード名 _stbl-pay-verification.<ホスト名>トークン
well-known ファイルhttps://<ホスト名>/.well-known/stbl-pay-merchant.txt本文にトークンだけ
HTML の meta タグhttps://<ホスト名>/ の <head> の中（本文の中では確認しない）<meta name="stbl-pay-verification" content="<トークン>">

トークンは加盟店ごとに違うので、加盟店コンソールで確かめます。well-known ファイルと meta タグは、登録したホスト名そのものを https で読みに行きます。リダイレクトはたどりません。

Basic 認証やアクセス制限で非公開にしているサイトは、DNS の TXT レコードを使ってください。 well-known ファイルと meta タグは、認証なしで読めないと確認できません（401・403 は、その場で証明を取り下げます）。定期の再検証も同じ方法で読みに行くので、確認のときだけ認証を外しても、戻したあとの再検証で 401・403 が返った時点で取り下げられます。

結果は、「設置した値を確認する」のボタンを含む折りたたみのすぐ下に出ます。成立すると「所有を確認しました」と、登録しているドメインの横に「所有を証明済み」が出ます。失敗したときは、理由がそこに出ます。

証明が成立すると、決済画面に検証済みの表示が出ます。この表示は、ドメインの所有が証明されていることを示すものです。STBLpay による加盟店の審査済み・公認の表示でも、決済の安全性の保証でもありません。 証明していない加盟店を、否定的な表示にすることはありません。

証明は一度成立すれば終わりではなく、定期的（24 時間ごと）に再検証されます。定期の再検証は、最後に証明が成立した方法だけを確認します。 設置の方法を変えたとき（たとえば DNS から meta タグへ）は、新しい方法で設置してから「設置した値を確認する」を押し直してください。押し直さずに前の方法の設置を外すと、次の再検証で取り下げられます。

  • 設置した値がトークンと一致しないとき（または見つからないとき）は、検証済みの表示をすぐに取り下げます。
  • 次の場合も、1 回ですぐに取り下げます。ドメインの名前解決の結果が、社内向けなどの公開されていないアドレスだったとき。well-known ファイルか meta タグの確認で、4xx（408・429 を除く。401・403 を含む）やリダイレクトが返ったとき。
  • サイトや DNS に到達できない状態（5xx、408、429、接続の失敗、タイムアウト、証明書の確認の失敗）が 3 回続いたときも、取り下げます。一時的な障害を 1〜2 回で取り下げることはありません。
  • 取り下げたあとも再検証は続き、再び確認できれば検証済みの表示が戻ります。
  • ドメインの変更・解除をした場合は、前の証明では復活しません。

「設置した値を確認する」は、1 分間に 5 回までです（common/rate_limited。429）。超えたときは 1 分ほど待ってください。定期の再検証はこの回数に含まれません。

復帰ページの認可は自社で行います。登録ドメインに戻ったことだけで決済成立を判断しないでください。