@siglume/direct-request-payment 0.4.19 → 0.4.20

package/templates/express/siglume-sdrp-routes.ts

@@ -13,14 +13,28 @@ export interface SiglumeCheckoutOrder {
   currency: DirectRequestPaymentCurrency | string;
 }
 
+export interface SiglumeCheckoutAttempt extends SiglumeCheckoutOrder {
+  order_id: string;
+  attempt_id: string;
+  stable_nonce: string;
+  checkout_url?: string;
+  checkout_session_id?: string;
+}
+
 export interface SiglumeSdrpOrderStore {
-  getOrderForCheckout(orderId: string, req: express.Request): Promise<SiglumeCheckoutOrder | null>;
+  beginCheckoutAttempt(orderId: string, req: express.Request): Promise<SiglumeCheckoutAttempt | null>;
   markCheckoutPending(input: {
     order_id: string;
+    attempt_id: string;
+    stable_nonce: string;
     challenge_hash: string;
     checkout_session_id: string;
+    checkout_url: string;
   }): Promise<void>;
-  recordWebhookEventOnce(eventId: string): Promise<boolean>;
+  processWebhookEventOnce(
+    eventId: string,
+    handler: () => Promise<void>,
+  ): Promise<"processed" | "duplicate">;
   findOrderByChallengeHash(challengeHash: string): Promise<{ id: string } | null>;
   markOrderPaidOnce(input: {
     order_id: string;
@@ -41,9 +55,10 @@ export interface SiglumeSdrpRouterOptions {
   webhook_secret: string;
   shop_public_origin: string;
   order_store: SiglumeSdrpOrderStore;
+  allow_metered_payments?: boolean;
 }
 
-export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): express.Router {
+export function createSiglumeSdrpCheckoutRouter(options: SiglumeSdrpRouterOptions): express.Router {
   const router = express.Router();
   const merchant = new DirectRequestPaymentMerchantClient({
     auth_token: options.merchant_auth_token,
@@ -52,26 +67,39 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
   router.post("/checkout/siglume/start", express.json(), async (req, res, next) => {
     try {
       const orderId = String(req.body?.order_id || "");
-      const order = await options.order_store.getOrderForCheckout(orderId, req);
-      if (!order) {
+      const attempt = await options.order_store.beginCheckoutAttempt(orderId, req);
+      if (!attempt) {
         res.status(404).json({ error: "order_not_found" });
         return;
       }
 
+      if (!options.allow_metered_payments && !isStandardCheckoutAmount(attempt.currency, attempt.amount_minor)) {
+        res.status(409).json({ error: "METERED_INTEGRATION_REQUIRED" });
+        return;
+      }
+
+      if (attempt.checkout_url && attempt.checkout_session_id) {
+        res.json({ checkout_url: attempt.checkout_url, session_id: attempt.checkout_session_id });
+        return;
+      }
+
       const session = await merchant.createCheckoutSession({
         merchant: options.merchant,
-        amount_minor: order.amount_minor,
-        currency: order.currency,
-        nonce: `${order.id}-attempt_${Date.now()}`,
+        amount_minor: attempt.amount_minor,
+        currency: attempt.currency,
+        nonce: attempt.stable_nonce,
         success_url: `${options.shop_public_origin}/checkout/siglume/success`,
         cancel_url: `${options.shop_public_origin}/checkout/siglume/cancel`,
-        metadata: { order_id: order.id },
+        metadata: { order_id: attempt.order_id, attempt_id: attempt.attempt_id },
       });
 
       await options.order_store.markCheckoutPending({
-        order_id: order.id,
+        order_id: attempt.order_id,
+        attempt_id: attempt.attempt_id,
+        stable_nonce: attempt.stable_nonce,
         challenge_hash: session.challenge_hash,
         checkout_session_id: session.session_id,
+        checkout_url: session.checkout_url,
       });
 
       res.json({ checkout_url: session.checkout_url, session_id: session.session_id });
@@ -80,7 +108,19 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
     }
   });
 
-  router.post("/webhooks/siglume", express.raw({ type: "application/json" }), async (req, res, next) => {
+  router.use((error: unknown, _req: express.Request, res: express.Response, next: express.NextFunction) => {
+    if (error instanceof HostedCheckoutNotAvailableError) {
+      res.status(409).json({ error: "hosted_checkout_not_enabled" });
+      return;
+    }
+    next(error);
+  });
+
+  return router;
+}
+
+export function createSiglumeSdrpWebhookHandler(options: SiglumeSdrpRouterOptions): express.RequestHandler {
+  return async (req, res, next) => {
     try {
       const { event } = await verifyDirectRequestPaymentWebhook(
         options.webhook_secret,
@@ -88,70 +128,104 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
         req.header("siglume-signature") || "",
       );
 
-      if (!(await options.order_store.recordWebhookEventOnce(event.id))) {
+      const result = await options.order_store.processWebhookEventOnce(event.id, async () => {
+        await processSiglumeWebhookEvent(options, event);
+      });
+
+      if (result === "duplicate") {
         res.status(204).send();
         return;
       }
 
-      if (event.type === "direct_payment.confirmed") {
-        const confirmation = classifyDirectPaymentConfirmation(event);
-
-        if (confirmation.kind === "standard_settled") {
-          const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
-          if (order) {
-            await options.order_store.markOrderPaidOnce({
-              order_id: order.id,
-              requirement_id: confirmation.requirement_id,
-              chain_receipt_id: confirmation.chain_receipt_id,
-            });
-          } else {
-            await options.order_store.flagPaymentReview({
-              reason: "unknown_challenge_hash",
-              requirement_id: confirmation.requirement_id,
-            });
-          }
-        } else if (confirmation.kind === "metered_usage_accepted") {
-          const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
-          if (order) {
-            await options.order_store.markOrderFulfilledUnsettledOnce({
-              order_id: order.id,
-              requirement_id: confirmation.requirement_id,
-              pricing_band: confirmation.pricing_band,
-            });
-          } else {
-            await options.order_store.flagPaymentReview({
-              reason: "unknown_metered_challenge_hash",
-              requirement_id: confirmation.requirement_id,
-            });
-          }
-        } else if (confirmation.kind === "metered_batch_settled") {
-          await options.order_store.flagPaymentReview({
-            reason: "metered_batch_settled_reconcile_statement_api",
-            settlement_batch_id: confirmation.settlement_batch_id,
-            chain_receipt_id: confirmation.chain_receipt_id,
-          });
-        } else {
-          await options.order_store.flagPaymentReview({
-            reason: confirmation.reason,
-            requirement_id: confirmation.requirement_id,
-            settlement_batch_id: confirmation.settlement_batch_id,
-          });
-        }
-      }
-
       res.status(204).send();
     } catch (error) {
       next(error);
     }
-  });
+  };
+}
 
-  router.use((error: unknown, _req: express.Request, res: express.Response, next: express.NextFunction) => {
-    if (error instanceof HostedCheckoutNotAvailableError) {
-      res.status(409).json({ error: "hosted_checkout_not_enabled" });
+export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): express.Router {
+  const router = createSiglumeSdrpCheckoutRouter(options);
+  router.post(
+    "/webhooks/siglume",
+    express.raw({ type: "application/json" }),
+    createSiglumeSdrpWebhookHandler(options),
+  );
+  return router;
+}
+
+async function processSiglumeWebhookEvent(
+  options: SiglumeSdrpRouterOptions,
+  event: Awaited<ReturnType<typeof verifyDirectRequestPaymentWebhook>>["event"],
+): Promise<void> {
+  if (event.type !== "direct_payment.confirmed") {
+    return;
+  }
+
+  const confirmation = classifyDirectPaymentConfirmation(event);
+
+  if (confirmation.kind === "standard_settled") {
+    const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
+    if (order) {
+      await options.order_store.markOrderPaidOnce({
+        order_id: order.id,
+        requirement_id: confirmation.requirement_id,
+        chain_receipt_id: confirmation.chain_receipt_id,
+      });
+    } else {
+      await options.order_store.flagPaymentReview({
+        reason: "unknown_challenge_hash",
+        requirement_id: confirmation.requirement_id,
+      });
+    }
+    return;
+  }
+
+  if (confirmation.kind === "metered_usage_accepted") {
+    if (!options.allow_metered_payments) {
+      await options.order_store.flagPaymentReview({
+        reason: "metered_integration_required",
+        requirement_id: confirmation.requirement_id,
+        pricing_band: confirmation.pricing_band,
+      });
       return;
     }
-    next(error);
+    const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
+    if (order) {
+      await options.order_store.markOrderFulfilledUnsettledOnce({
+        order_id: order.id,
+        requirement_id: confirmation.requirement_id,
+        pricing_band: confirmation.pricing_band,
+      });
+    } else {
+      await options.order_store.flagPaymentReview({
+        reason: "unknown_metered_challenge_hash",
+        requirement_id: confirmation.requirement_id,
+      });
+    }
+    return;
+  }
+
+  if (confirmation.kind === "metered_batch_settled") {
+    await options.order_store.flagPaymentReview({
+      reason: "metered_batch_settled_reconcile_statement_api",
+      settlement_batch_id: confirmation.settlement_batch_id,
+      chain_receipt_id: confirmation.chain_receipt_id,
+    });
+    return;
+  }
+
+  await options.order_store.flagPaymentReview({
+    reason: confirmation.reason,
+    requirement_id: confirmation.requirement_id,
+    settlement_batch_id: confirmation.settlement_batch_id,
   });
+}
 
-  return router;
+function isStandardCheckoutAmount(currency: string, amountMinor: number): boolean {
+  if (!Number.isSafeInteger(amountMinor)) return false;
+  const normalizedCurrency = String(currency || "").toUpperCase();
+  if (normalizedCurrency === "JPY") return amountMinor >= 501;
+  if (normalizedCurrency === "USD") return amountMinor >= 301;
+  return false;
 }

package/templates/fastapi/README.md

@@ -10,12 +10,16 @@ from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
 
 app = FastAPI()
 app.include_router(
-    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore(), allow_metered_payments=False),
     prefix="/payments",
 )
 ```
 
 Replace `siglume_order_store_example.py` with your real order database adapter.
+Keep `process_webhook_event_once()` transactional: record the webhook event as
+processed only after the order update or review write succeeds. The generated
+route defaults to Standard-only. Enable `allow_metered_payments` only after you
+implement Micro / Nano settlement reconciliation and past-due handling.
 The route paths become:
 
 - `POST /payments/checkout/siglume/start`

package/templates/fastapi/siglume_order_store_example.py

@@ -11,22 +11,45 @@ _processed_events: set[str] = set()
 
 
 class ExampleSiglumeOrderStore:
-    async def get_order_for_checkout(self, order_id: str, request: Request) -> dict[str, Any] | None:
-        return _orders.get(order_id)
+    async def begin_checkout_attempt(self, order_id: str, request: Request) -> dict[str, Any] | None:
+        order = _orders.get(order_id)
+        if order is None:
+            return None
+        order.setdefault("attempt_id", f"{order['id']}_attempt_1")
+        order.setdefault("stable_nonce", f"{order['id']}-attempt_1")
+        return {
+            **order,
+            "order_id": order["id"],
+            "attempt_id": order["attempt_id"],
+            "stable_nonce": order["stable_nonce"],
+        }
 
-    async def mark_checkout_pending(self, *, order_id: str, challenge_hash: str, checkout_session_id: str) -> None:
+    async def mark_checkout_pending(
+        self,
+        *,
+        order_id: str,
+        attempt_id: str,
+        stable_nonce: str,
+        challenge_hash: str,
+        checkout_session_id: str,
+        checkout_url: str,
+    ) -> None:
         order = _orders.get(order_id)
         if not order:
             return
         order["status"] = "pending"
+        order["attempt_id"] = attempt_id
+        order["stable_nonce"] = stable_nonce
         order["challenge_hash"] = challenge_hash
         order["checkout_session_id"] = checkout_session_id
+        order["checkout_url"] = checkout_url
 
-    async def record_webhook_event_once(self, event_id: str) -> bool:
+    async def process_webhook_event_once(self, event_id: str, handler) -> str:
         if event_id in _processed_events:
-            return False
+            return "duplicate"
+        await handler()
         _processed_events.add(event_id)
-        return True
+        return "processed"
 
     async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None:
         for order in _orders.values():

package/templates/fastapi/siglume_sdrp_routes.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import os
-import time
-from typing import Any, Protocol
+from typing import Any, Awaitable, Callable, Literal, Protocol
 
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse, Response
+from starlette.concurrency import run_in_threadpool
 from siglume_direct_request_payment import (
     DirectRequestPaymentMerchantClient,
     HostedCheckoutNotAvailableError,
@@ -15,16 +15,33 @@ from siglume_direct_request_payment import (
 
 
 class SiglumeSdrpOrderStore(Protocol):
-    async def get_order_for_checkout(self, order_id: str, request: Request) -> dict[str, Any] | None: ...
-    async def mark_checkout_pending(self, *, order_id: str, challenge_hash: str, checkout_session_id: str) -> None: ...
-    async def record_webhook_event_once(self, event_id: str) -> bool: ...
+    async def begin_checkout_attempt(self, order_id: str, request: Request) -> dict[str, Any] | None: ...
+    async def mark_checkout_pending(
+        self,
+        *,
+        order_id: str,
+        attempt_id: str,
+        stable_nonce: str,
+        challenge_hash: str,
+        checkout_session_id: str,
+        checkout_url: str,
+    ) -> None: ...
+    async def process_webhook_event_once(
+        self,
+        event_id: str,
+        handler: Callable[[], Awaitable[None]],
+    ) -> Literal["processed", "duplicate"]: ...
     async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None: ...
     async def mark_order_paid_once(self, *, order_id: str, requirement_id: str, chain_receipt_id: str) -> None: ...
     async def mark_order_fulfilled_unsettled_once(self, *, order_id: str, requirement_id: str, pricing_band: str) -> None: ...
     async def flag_payment_review(self, data: dict[str, Any]) -> None: ...
 
 
-def create_siglume_sdrp_router(order_store: SiglumeSdrpOrderStore) -> APIRouter:
+def create_siglume_sdrp_router(
+    order_store: SiglumeSdrpOrderStore,
+    *,
+    allow_metered_payments: bool = False,
+) -> APIRouter:
     router = APIRouter()
     merchant_key = os.environ["SIGLUME_DIRECT_PAYMENT_MERCHANT"]
     shop_origin = os.environ["SHOP_PUBLIC_ORIGIN"]
@@ -36,27 +53,41 @@ def create_siglume_sdrp_router(order_store: SiglumeSdrpOrderStore) -> APIRouter:
     async def start_checkout(request: Request) -> JSONResponse:
         body = await request.json()
         order_id = str(body.get("order_id") or "")
-        order = await order_store.get_order_for_checkout(order_id, request)
-        if not order:
+        attempt = await order_store.begin_checkout_attempt(order_id, request)
+        if not attempt:
             return JSONResponse({"error": "order_not_found"}, status_code=404)
 
+        if not allow_metered_payments and not _is_standard_checkout_amount(str(attempt["currency"]), int(attempt["amount_minor"])):
+            return JSONResponse({"error": "METERED_INTEGRATION_REQUIRED"}, status_code=409)
+
+        if attempt.get("checkout_url") and attempt.get("checkout_session_id"):
+            return JSONResponse({
+                "checkout_url": attempt["checkout_url"],
+                "session_id": attempt["checkout_session_id"],
+            })
+
         try:
-            session = merchant.create_checkout_session(
-                merchant=merchant_key,
-                amount_minor=int(order["amount_minor"]),
-                currency=str(order["currency"]),
-                nonce=f"{order['id']}-attempt_{int(time.time() * 1000)}",
-                success_url=f"{shop_origin}/checkout/siglume/success",
-                cancel_url=f"{shop_origin}/checkout/siglume/cancel",
-                metadata={"order_id": order["id"]},
+            session = await run_in_threadpool(
+                lambda: merchant.create_checkout_session(
+                    merchant=merchant_key,
+                    amount_minor=int(attempt["amount_minor"]),
+                    currency=str(attempt["currency"]),
+                    nonce=str(attempt["stable_nonce"]),
+                    success_url=f"{shop_origin}/checkout/siglume/success",
+                    cancel_url=f"{shop_origin}/checkout/siglume/cancel",
+                    metadata={"order_id": attempt["order_id"], "attempt_id": attempt["attempt_id"]},
+                )
             )
         except HostedCheckoutNotAvailableError:
             return JSONResponse({"error": "hosted_checkout_not_enabled"}, status_code=409)
 
         await order_store.mark_checkout_pending(
-            order_id=str(order["id"]),
+            order_id=str(attempt["order_id"]),
+            attempt_id=str(attempt["attempt_id"]),
+            stable_nonce=str(attempt["stable_nonce"]),
             challenge_hash=session["challenge_hash"],
             checkout_session_id=session["session_id"],
+            checkout_url=session["checkout_url"],
         )
         return JSONResponse({"checkout_url": session["checkout_url"], "session_id": session["session_id"]})
 
@@ -68,40 +99,72 @@ def create_siglume_sdrp_router(order_store: SiglumeSdrpOrderStore) -> APIRouter:
             request.headers.get("Siglume-Signature", ""),
         )["event"]
 
-        if not await order_store.record_webhook_event_once(str(event["id"])):
-            return Response(status_code=204)
+        async def handler() -> None:
+            await _process_siglume_webhook_event(
+                order_store,
+                event,
+                allow_metered_payments=allow_metered_payments,
+            )
 
-        if event["type"] == "direct_payment.confirmed":
-            confirmation = classify_direct_payment_confirmation(event)
-            if confirmation["kind"] == "standard_settled":
-                order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
-                if order:
-                    await order_store.mark_order_paid_once(
-                        order_id=str(order["id"]),
-                        requirement_id=confirmation["requirement_id"],
-                        chain_receipt_id=confirmation["chain_receipt_id"],
-                    )
-                else:
-                    await order_store.flag_payment_review({
-                        "reason": "unknown_challenge_hash",
-                        "requirement_id": confirmation["requirement_id"],
-                    })
-            elif confirmation["kind"] == "metered_usage_accepted":
-                order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
-                if order:
-                    await order_store.mark_order_fulfilled_unsettled_once(
-                        order_id=str(order["id"]),
-                        requirement_id=confirmation["requirement_id"],
-                        pricing_band=confirmation["pricing_band"],
-                    )
-                else:
-                    await order_store.flag_payment_review({
-                        "reason": "unknown_metered_challenge_hash",
-                        "requirement_id": confirmation["requirement_id"],
-                    })
-            else:
-                await order_store.flag_payment_review(dict(confirmation))
+        if await order_store.process_webhook_event_once(str(event["id"]), handler) == "duplicate":
+            return Response(status_code=204)
 
         return Response(status_code=204)
 
     return router
+
+
+async def _process_siglume_webhook_event(
+    order_store: SiglumeSdrpOrderStore,
+    event: dict[str, Any],
+    *,
+    allow_metered_payments: bool,
+) -> None:
+    if event["type"] != "direct_payment.confirmed":
+        return
+
+    confirmation = classify_direct_payment_confirmation(event)
+    if confirmation["kind"] == "standard_settled":
+        order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
+        if order:
+            await order_store.mark_order_paid_once(
+                order_id=str(order["id"]),
+                requirement_id=confirmation["requirement_id"],
+                chain_receipt_id=confirmation["chain_receipt_id"],
+            )
+        else:
+            await order_store.flag_payment_review({
+                "reason": "unknown_challenge_hash",
+                "requirement_id": confirmation["requirement_id"],
+            })
+    elif confirmation["kind"] == "metered_usage_accepted":
+        if not allow_metered_payments:
+            await order_store.flag_payment_review({
+                "reason": "metered_integration_required",
+                "requirement_id": confirmation["requirement_id"],
+                "pricing_band": confirmation["pricing_band"],
+            })
+            return
+        order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
+        if order:
+            await order_store.mark_order_fulfilled_unsettled_once(
+                order_id=str(order["id"]),
+                requirement_id=confirmation["requirement_id"],
+                pricing_band=confirmation["pricing_band"],
+            )
+        else:
+            await order_store.flag_payment_review({
+                "reason": "unknown_metered_challenge_hash",
+                "requirement_id": confirmation["requirement_id"],
+            })
+    else:
+        await order_store.flag_payment_review(dict(confirmation))
+
+
+def _is_standard_checkout_amount(currency: str, amount_minor: int) -> bool:
+    normalized_currency = currency.upper()
+    if normalized_currency == "JPY":
+        return amount_minor >= 501
+    if normalized_currency == "USD":
+        return amount_minor >= 301
+    return False