準備

語の意味は用語集にあります。

このガイドは、本ガイドの記述どおりに動く環境を対象にします。接続前に、その環境のバージョンと利用できる機能を問い合わせ先に確認してください。

接続情報

情報	用途
API のベース URL	サーバー間の決済作成・状態照会
加盟店の API キー	決済作成の x-stbl-api-key ヘッダ。店舗ごとに、加盟店コンソールで発行する
加盟店の登録ドメイン（ホスト名。例：shop.example.com。ドメイン登録）	EC 決済の作成に必須（未登録だと 409 merchant/domain_required）。returnUrl のホスト名の照合にも使う
Webhook 受信先と署名鍵（任意。推奨）	サーバーでの結果通知受信。使わない場合は、状態照会で settled を確かめてから注文を確定する

ブラウザへ API キーを渡さないでください。試すときは Sandbox を使えます。決済ページの URL は作成応答から取得します。

加盟店側の準備

最初に、ネットショップのお店を作ります。加盟店コンソールのメニューの「お店と QR コード」で「お店をつくる」を押し、お店の名前（128 文字まで）を入れ、お店の種類に「ネットショップ」を選びます。API キー、ドメイン、Webhook の設定は、ネットショップのお店の「組み込みの準備」タブにだけあります。「店頭 QR」のお店には出ません。お店の種類はあとから変えられません。店頭の QR 決済でも使うときは、お店をもう 1 つ作ります。

1. 注文を認証・認可し、金額をサーバーで計算する。
2. 注文と決済 ID の対応を保存する DB を用意する。
3. 決済後に戻るページを用意する（URL の条件と例はドメイン登録）。
4. Webhook を使う場合は、HTTPS の Webhook 受信先で raw body（受け取ったままの本文）を保持できるようにする。URL は直接 POST を受けられる最終 URL にする。HTTPS のみ、ユーザー名・パスワード（userinfo）を含めない、内部アドレスに解決されない、リダイレクト（3xx）は追わない（送信先 URL の条件）。
5. 注文の定期突合を実装する。Webhook を使う場合は、署名検証、受信イベントの永続化、重複排除も実装する。使わない場合は、状態照会で settled を確かめてから注文を確定する。