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

再送ポリシー

同じ通知が 2 回以上届くことがあります（at-least-once）。たとえば、加盟店のサーバーが処理を終えたのに、2xx の応答がタイムアウトや通信の切断で STBLpay に届かなかった場合です。STBLpay からは、通知が届かなかったのか、応答だけが失われたのかを区別できないため、もう一度送ります。送り直さない作りにすると、今度は通知が失われるおそれがあります。重複した通知は、イベントの id で除いてください。

一方で、再送には回数の上限があるため、最終的に届くことは保証しません。届かない場合に備えて、未確定の注文は状態照会で確かめてください。

送信先 URL の条件​

送信先の URL は、直接 POST を受けられる最終的な URL を登録してください。

  • HTTPS のみです。ユーザー名・パスワード（userinfo）を含む URL は設定できません。
  • 証明書は、一般に信頼されている認証局が発行した有効なものにしてください。期限が切れていないこと、ホスト名が URL と一致していること、中間証明書も含めて送ることが条件です。自己署名の証明書や社内の認証局が発行した証明書では接続できません。この場合は失敗として再送し、上限に達すると打ち切ります。配信履歴には「TLS の確認の失敗」と表示されます。
  • 内部・予約済みのアドレスへ解決される URL や、ホスト名を解決できない URL は設定できません。送信のたびにも同じ検証を行います。
  • リダイレクトは追いません。 3xx の応答は失敗として扱い、再送します。転送先の URL を登録してください。
  • 2xx を成功として扱います。応答をどこまで待つか（タイムアウト）と、失敗として扱う応答（3xx・4xx・5xx、タイムアウト、接続や TLS の失敗）は、OpenAPI 仕様書の webhooks.paymentEvent にあります。

再送の間隔​

失敗後の間隔は 3秒 → 10秒 → 30秒 → 120秒 → 600秒の5段階です。初回と合わせて6回試行し、以降は打ち切ります。再送ではボディとイベント ID を保ち、送信時刻と署名は試行ごとに更新します。

応答の順序​

署名と入力を検証し、イベントを耐久性のある DB またはキューへ保存してから 2xx を返してください。先に応答すると、直後の停止で通知を失っても STBLpay は再送しません。

受信 → 署名・入力検証 → event.id で重複排除しつつ永続化 → 2xx
                                      ↓
                              ワーカーが注文を更新

永続化に失敗した場合は成功を返しません。商品提供やメール送信など時間のかかる処理は、永続化したイベントを元に別のワーカーで実行します。

打ち切り・障害復旧​

次の場合、通知は打ち切られます。再送の上限（初回を含む 6 回）に達したとき、および「webhook を解除」したときです。解除で打ち切った通知は、設定し直しても再開しません。送信先の URL を変更したときは、未配信・再送待ちの通知も新しい URL へ送ります。Webhook を設定していない間に起きた決済の通知は、あとから送られません。加盟店コンソールの「組み込みの準備」タブの「お支払い完了のお知らせ先」にある「配信履歴」で、通知ごとの状態を確認できます。

通知の配信状態は決済状態と別です。通知が届かなくても settled は成立済みです。未確定注文を 状態照会で定期的に突合し、長期停止からの復旧後にも確認します。

通知順序に依存せず、注文の更新も冪等にしてください。