FAQ
決済画面も用意する必要がありますか
用意する必要はありません。支払いの確認とパスキーの承認は、STBLpay の決済ページが行います。例：加盟店が作るのは「支払う」ボタンだけで、押したあとの画面は STBLpay のものです。
決済作成 API が返ったら、支払いは完了ですか
完了ではありません。受付票ができただけで、この時点の状態は created（署名待ち）です。完了は Webhook の payment.settled、または状態照会の settled で確認します。通知が届かないときに備えて、状態照会でも確かめられるようにしておきます。例：作成 API の応答を受けた時点では商品を提供せず、settled を確認するまで待ちます。完了判定を参照してください。
orderId は自由に決めてよいですか
orderId は決済を試すたびの ID です（最大 128 文字）。加盟店全体で重ならないように採番してください。同じ orderId で再度作成すると既存の決済が返るので、通信の再送（タイムアウトや二重クリック）では同じ値を使います。failed・expired・canceled のあとで払い直すときは、新しい orderId で作ります（冪等性）。自社の注文番号をそのまま使えるのは、同じ注文で払い直しをしない場合だけです。払い直すなら、注文と決済の試行の対応を自社で管理します。
トップレベル遷移とは何ですか
checkoutUrl へ、通常のリンクのようにページ全体で移動することです。iframe やポップアップには入れないでください。例：window.location.href = checkoutUrl のように移動します。パスキーの承認を正しいページで行わせ、偽の画面に入れ替えられるのを防ぐためです。語の意味は用語集にもあります。
決済が終わったあと、利用者はいつ加盟店サイトに戻りますか
決済が終端に着くと、STBLpay の決済ページに加盟店へ戻るボタンが出ます。成立・失敗・期限切れ・取消・nonce_conflict のどれでも、行き先は決済の作成時に指定した returnUrl です。決済の作成時に returnUrl を指定しなかったときは、ボタンは出ず、「このタブは閉じていただいてかまいません」と表示されます。例：戻り先のページでは「確認中」と表示し、サーバー側の注文状態を見て切り替えます。Webhook とは待ち合わせないので、注文の更新より先に戻ることがあります。戻らない利用者もいます。加盟店の利用停止で決済が中止になった場合は、returnUrl を指定していてもボタンは出ず、「この画面を閉じて、お店のページからご注文をやり直してください。」と表示されます。戻ってきたことを成立の根拠にしないでください。
SDK は必要ですか
不要です。加盟店組込 SDK は提供していません。決済作成後に checkoutUrl へ遷移してください。現在の組み込み方を参照してください。
決済の作成のリクエストを再送できますか
同じ店舗から同じ orderId で既存決済が返ります。通信失敗のたびに新しい番号を作らないでください。既存決済の金額や期限を更新する操作ではありません。返った決済がすでに終端（それ以上進まない状態）のこともあるため、checkoutUrl へ遷移させる前に応答の status を確かめてください。状態ごとの扱いは冪等性にあります。
金額は数値ですか
API の金額は円建ての文字列です。Webhook の金額も文字列です。payment.failed・payment.canceled・payment.expired の通知では fee_jpy と net_received_jpy が "0" になります（金額の扱い）。状態照会 API は金額・手数料を返しません。
署名済みなら商品を提供できますか
できません。signed や deposit_confirmed は途中の状態です。サーバーで成立を確認してから、一度だけ提供します。
Webhook は何が届きますか
成立・失敗・取消・失効の4種類です。nonce_conflict は照会と調査が必要です。署名検証済みボディの id で重複を排除してください。加盟店コンソールから送るテスト通知は、payment.settled の形で本文に test: true が付きます。注文を変えずに 2xx を返してください（テスト通知）。本文の定義は、OpenAPI 仕様書の WebhookEvent と TestWebhookEvent にあります。
キャンセル後に決済が成立しますか
API の canceled は終端なので成立しません。発行体での予約取消を STBLpay が観測できず、まだ issue_pending であるケースとは区別します。
戻ってこない注文はいつ閉じますか
固定の経過時間ではなく、状態照会か Webhook で expired などの終端になったかで判断します（操作期限と着金期限）。自社注文を先に閉じるなら、その後の成立を検出して運用対応へ回してください。
返金 API は使えますか
加盟店サーバーから呼べる返金 API はありません。返金は加盟店コンソールの「取引の詳細」画面から、owner がパスキーで承認して行います。返金先は元の支払人に固定されます。返金の提供範囲を参照してください。
決済 ID は秘密ですか
秘密ではありません。自社注文の閲覧には自社の認証・認可を適用してください。