@siglume/direct-request-payment 0.4.19 → 0.4.20

package/examples/hosted-checkout-python/app.py

@@ -13,9 +13,9 @@ from siglume_direct_request_payment import (
 
 from order_store import (
     all_orders,
+    begin_checkout_attempt,
     find_order_by_challenge_hash,
-    get_order,
-    mark_webhook_event_processed_once,
+    process_webhook_event_once,
     save_order,
 )
 
@@ -37,11 +37,21 @@ def orders():
 @app.post("/checkout/siglume/start")
 def start_checkout():
     order_id = str((request.get_json(silent=True) or {}).get("order_id") or "")
-    order = get_order(order_id)
+    order = begin_checkout_attempt(order_id)
     if order is None:
         return jsonify({"error": "order_not_found"}), 404
 
-    order["payment_attempt"] = int(order.get("payment_attempt") or 0) + 1
+    if order.get("siglume_checkout_url") and order.get("siglume_checkout_session_id"):
+        return jsonify(
+            {
+                "order_id": order["id"],
+                "amount_minor": order["amount_minor"],
+                "currency": order["currency"],
+                "checkout_url": order["siglume_checkout_url"],
+                "session_id": order["siglume_checkout_session_id"],
+            }
+        )
+
     session = siglume_merchant.create_checkout_session(
         merchant=merchant_key,
         amount_minor=int(order["amount_minor"]),
@@ -53,6 +63,7 @@ def start_checkout():
     )
 
     order["siglume_challenge_hash"] = session["challenge_hash"]
+    order["siglume_checkout_url"] = session["checkout_url"]
     order["siglume_checkout_session_id"] = session["session_id"]
     order["siglume_payment_status"] = "pending"
     save_order(order)
@@ -77,35 +88,39 @@ def siglume_webhook():
     )
     event = verified["event"]
 
-    if not mark_webhook_event_processed_once(str(event["id"])):
+    def handler() -> None:
+        if event["type"] == "direct_payment.confirmed":
+            confirmation = classify_direct_payment_confirmation(event)
+
+            if confirmation["kind"] == "standard_settled":
+                order = find_order_by_challenge_hash(confirmation["challenge_hash"])
+                if order is not None:
+                    order["siglume_payment_status"] = "paid"
+                    order["siglume_requirement_id"] = confirmation["requirement_id"]
+                    order["siglume_chain_receipt_id"] = confirmation["chain_receipt_id"]
+                    save_order(order)
+            elif confirmation["kind"] == "metered_usage_accepted":
+                app.logger.warning(
+                    "Micro/Nano settlement integration is required before automatic fulfillment",
+                    extra={
+                        "event_id": event["id"],
+                        "requirement_id": confirmation["requirement_id"],
+                        "pricing_band": confirmation["pricing_band"],
+                    },
+                )
+            else:
+                app.logger.warning(
+                    "manual payment review required",
+                    extra={
+                        "event_id": event["id"],
+                        "reason": confirmation.get("reason"),
+                        "requirement_id": confirmation.get("requirement_id"),
+                    },
+                )
+
+    if process_webhook_event_once(str(event["id"]), handler) == "duplicate":
         return "", 204
 
-    if event["type"] == "direct_payment.confirmed":
-        confirmation = classify_direct_payment_confirmation(event)
-
-        if confirmation["kind"] == "standard_settled":
-            order = find_order_by_challenge_hash(confirmation["challenge_hash"])
-            if order is not None:
-                order["siglume_payment_status"] = "paid"
-                order["siglume_requirement_id"] = confirmation["requirement_id"]
-                order["siglume_chain_receipt_id"] = confirmation["chain_receipt_id"]
-                save_order(order)
-        elif confirmation["kind"] == "metered_usage_accepted":
-            order = find_order_by_challenge_hash(confirmation["challenge_hash"])
-            if order is not None:
-                order["siglume_payment_status"] = "fulfilled_unsettled"
-                order["siglume_requirement_id"] = confirmation["requirement_id"]
-                save_order(order)
-        else:
-            app.logger.warning(
-                "manual payment review required",
-                extra={
-                    "event_id": event["id"],
-                    "reason": confirmation.get("reason"),
-                    "requirement_id": confirmation.get("requirement_id"),
-                },
-            )
-
     return "", 204
 
 

package/examples/hosted-checkout-python/order_store.py

@@ -20,6 +20,15 @@ def get_order(order_id: str) -> Order | None:
     return _orders.get(order_id)
 
 
+def begin_checkout_attempt(order_id: str) -> Order | None:
+    order = _orders.get(order_id)
+    if order is None:
+        return None
+    if not int(order.get("payment_attempt") or 0):
+        order["payment_attempt"] = 1
+    return order
+
+
 def all_orders() -> list[Order]:
     return list(_orders.values())
 
@@ -35,8 +44,9 @@ def find_order_by_challenge_hash(challenge_hash: str) -> Order | None:
     return None
 
 
-def mark_webhook_event_processed_once(event_id: str) -> bool:
+def process_webhook_event_once(event_id: str, handler) -> str:
     if event_id in _processed_webhook_events:
-        return False
+        return "duplicate"
+    handler()
     _processed_webhook_events.add(event_id)
-    return True
+    return "processed"

package/examples/hosted-checkout-python/pyproject.toml

@@ -5,5 +5,5 @@ requires-python = ">=3.11"
 dependencies = [
   "Flask>=3.0,<4",
   "python-dotenv>=1.0,<2",
-  "siglume-direct-request-payment>=0.4.19,<0.5",
+  "siglume-direct-request-payment>=0.4.20,<0.5",
 ]

package/examples/hosted-checkout-typescript/src/order-store.ts

@@ -6,6 +6,7 @@ export interface Order {
   currency: "JPY" | "USD";
   payment_attempt: number;
   siglume_challenge_hash?: string;
+  siglume_checkout_url?: string;
   siglume_checkout_session_id?: string;
   siglume_requirement_id?: string;
   siglume_chain_receipt_id?: string;
@@ -31,6 +32,15 @@ export function getOrder(orderId: string): Order | undefined {
   return orders.get(orderId);
 }
 
+export function beginCheckoutAttempt(orderId: string): Order | undefined {
+  const order = orders.get(orderId);
+  if (!order) return undefined;
+  if (!order.payment_attempt) {
+    order.payment_attempt = 1;
+  }
+  return order;
+}
+
 export function allOrders(): Order[] {
   return [...orders.values()];
 }
@@ -43,10 +53,11 @@ export function findOrderByChallengeHash(challengeHash: string): Order | undefin
   return [...orders.values()].find((order) => order.siglume_challenge_hash === challengeHash);
 }
 
-export function markWebhookEventProcessedOnce(eventId: string): boolean {
+export async function processWebhookEventOnce(eventId: string, handler: () => Promise<void>): Promise<"processed" | "duplicate"> {
   if (processedWebhookEvents.has(eventId)) {
-    return false;
+    return "duplicate";
   }
+  await handler();
   processedWebhookEvents.add(eventId);
-  return true;
+  return "processed";
 }

package/examples/hosted-checkout-typescript/src/server.ts

@@ -10,9 +10,9 @@ import {
 
 import {
   allOrders,
+  beginCheckoutAttempt,
   findOrderByChallengeHash,
-  getOrder,
-  markWebhookEventProcessedOnce,
+  processWebhookEventOnce,
   saveOrder,
 } from "./order-store.js";
 
@@ -40,13 +40,23 @@ app.post(
   express.json(),
   asyncRoute(async (req, res) => {
     const orderId = String(req.body?.order_id || "");
-    const order = getOrder(orderId);
+    const order = beginCheckoutAttempt(orderId);
     if (!order) {
       res.status(404).json({ error: "order_not_found" });
       return;
     }
 
-    order.payment_attempt += 1;
+    if (order.siglume_checkout_url && order.siglume_checkout_session_id) {
+      res.json({
+        order_id: order.id,
+        amount_minor: order.amount_minor,
+        currency: order.currency,
+        checkout_url: order.siglume_checkout_url,
+        session_id: order.siglume_checkout_session_id,
+      });
+      return;
+    }
+
     const session = await siglumeMerchant.createCheckoutSession({
       merchant: merchantKey,
       amount_minor: order.amount_minor,
@@ -58,6 +68,7 @@ app.post(
     });
 
     order.siglume_challenge_hash = session.challenge_hash;
+    order.siglume_checkout_url = session.checkout_url;
     order.siglume_checkout_session_id = session.session_id;
     order.siglume_payment_status = "pending";
     saveOrder(order);
@@ -82,41 +93,42 @@ app.post(
       req.header("siglume-signature") || "",
     );
 
-    if (!markWebhookEventProcessedOnce(event.id)) {
-      res.status(204).send();
-      return;
-    }
-
-    if (event.type === "direct_payment.confirmed") {
-      const confirmation = classifyDirectPaymentConfirmation(event);
-
-      if (confirmation.kind === "standard_settled") {
-        const order = findOrderByChallengeHash(confirmation.challenge_hash);
-        if (order) {
-          order.siglume_payment_status = "paid";
-          order.siglume_requirement_id = confirmation.requirement_id;
-          order.siglume_chain_receipt_id = confirmation.chain_receipt_id;
-          saveOrder(order);
-        }
-      } else if (confirmation.kind === "metered_usage_accepted") {
-        const order = findOrderByChallengeHash(confirmation.challenge_hash);
-        if (order) {
-          order.siglume_payment_status = "fulfilled_unsettled";
-          order.siglume_requirement_id = confirmation.requirement_id;
-          saveOrder(order);
+    const result = await processWebhookEventOnce(event.id, async () => {
+      if (event.type === "direct_payment.confirmed") {
+        const confirmation = classifyDirectPaymentConfirmation(event);
+
+        if (confirmation.kind === "standard_settled") {
+          const order = findOrderByChallengeHash(confirmation.challenge_hash);
+          if (order) {
+            order.siglume_payment_status = "paid";
+            order.siglume_requirement_id = confirmation.requirement_id;
+            order.siglume_chain_receipt_id = confirmation.chain_receipt_id;
+            saveOrder(order);
+          }
+        } else if (confirmation.kind === "metered_usage_accepted") {
+          console.warn("Micro/Nano settlement integration is required before automatic fulfillment", {
+            event_id: event.id,
+            requirement_id: confirmation.requirement_id,
+            pricing_band: confirmation.pricing_band,
+          });
+        } else if (confirmation.kind === "metered_batch_settled") {
+          console.info("metered batch settled", {
+            settlement_batch_id: confirmation.settlement_batch_id,
+            chain_receipt_id: confirmation.chain_receipt_id,
+          });
+        } else {
+          console.warn("manual payment review required", {
+            event_id: event.id,
+            reason: confirmation.reason,
+            requirement_id: confirmation.requirement_id,
+          });
         }
-      } else if (confirmation.kind === "metered_batch_settled") {
-        console.info("metered batch settled", {
-          settlement_batch_id: confirmation.settlement_batch_id,
-          chain_receipt_id: confirmation.chain_receipt_id,
-        });
-      } else {
-        console.warn("manual payment review required", {
-          event_id: event.id,
-          reason: confirmation.reason,
-          requirement_id: confirmation.requirement_id,
-        });
       }
+    });
+
+    if (result === "duplicate") {
+      res.status(204).send();
+      return;
     }
 
     res.status(204).send();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",

package/templates/express/README.md

@@ -1,21 +1,41 @@
 # Express Integration Files
 
-Mount the router in your existing app:
+Mount the webhook before any global JSON parser. Webhook signature verification
+needs the raw request body; `express.json()` cannot recreate it after parsing.
 
 ```ts
-import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import express from "express";
+import {
+  createSiglumeSdrpCheckoutRouter,
+  createSiglumeSdrpWebhookHandler,
+  type SiglumeSdrpRouterOptions,
+} from "./siglume/siglume-sdrp-routes.js";
 import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
 
-app.use("/payments", createSiglumeSdrpRouter({
+const siglumeOptions: SiglumeSdrpRouterOptions = {
   merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
   merchant_auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
   webhook_secret: process.env.SIGLUME_WEBHOOK_SECRET!,
   shop_public_origin: process.env.SHOP_PUBLIC_ORIGIN!,
   order_store: siglumeOrderStore,
-}));
+  allow_metered_payments: false,
+};
+
+app.post(
+  "/payments/webhooks/siglume",
+  express.raw({ type: "application/json" }),
+  createSiglumeSdrpWebhookHandler(siglumeOptions),
+);
+
+app.use(express.json());
+app.use("/payments", createSiglumeSdrpCheckoutRouter(siglumeOptions));
 ```
 
 Replace `siglume-order-store.example.ts` with your real order database adapter.
+Keep `processWebhookEventOnce()` 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/express/siglume-order-store.example.ts

@@ -1,10 +1,13 @@
 import type { Request } from "express";
 
-import type { SiglumeCheckoutOrder, SiglumeSdrpOrderStore } from "./siglume-sdrp-routes.js";
+import type { SiglumeCheckoutAttempt, SiglumeCheckoutOrder, SiglumeSdrpOrderStore } from "./siglume-sdrp-routes.js";
 
 type Order = SiglumeCheckoutOrder & {
   status: "created" | "pending" | "paid" | "fulfilled_unsettled" | "review_required";
+  attempt_id?: string;
+  stable_nonce?: string;
   challenge_hash?: string;
+  checkout_url?: string;
   checkout_session_id?: string;
   requirement_id?: string;
   chain_receipt_id?: string;
@@ -16,20 +19,33 @@ const orders = new Map<string, Order>([
 const processedEvents = new Set<string>();
 
 export const siglumeOrderStore: SiglumeSdrpOrderStore = {
-  async getOrderForCheckout(orderId: string, _req: Request) {
-    return orders.get(orderId) || null;
+  async beginCheckoutAttempt(orderId: string, _req: Request): Promise<SiglumeCheckoutAttempt | null> {
+    const order = orders.get(orderId);
+    if (!order) return null;
+    order.attempt_id ||= `${order.id}_attempt_1`;
+    order.stable_nonce ||= `${order.id}-attempt_1`;
+    return {
+      ...order,
+      order_id: order.id,
+      attempt_id: order.attempt_id,
+      stable_nonce: order.stable_nonce,
+    };
   },
   async markCheckoutPending(input) {
     const order = orders.get(input.order_id);
     if (!order) return;
     order.status = "pending";
+    order.attempt_id = input.attempt_id;
+    order.stable_nonce = input.stable_nonce;
     order.challenge_hash = input.challenge_hash;
     order.checkout_session_id = input.checkout_session_id;
+    order.checkout_url = input.checkout_url;
   },
-  async recordWebhookEventOnce(eventId) {
-    if (processedEvents.has(eventId)) return false;
+  async processWebhookEventOnce(eventId, handler) {
+    if (processedEvents.has(eventId)) return "duplicate";
+    await handler();
     processedEvents.add(eventId);
-    return true;
+    return "processed";
   },
   async findOrderByChallengeHash(challengeHash) {
     return [...orders.values()].find((order) => order.challenge_hash === challengeHash) || null;