@siglume/direct-request-payment 0.4.19 → 0.4.22

package/docs/troubleshooting.md

@@ -11,19 +11,33 @@ Hosted Checkout is enabled account by account during beta. Check this before
 building a human web checkout:
 
 ```bash
+npx siglume-check readiness --sandbox
 npx siglume-check readiness
 ```
 
-The command validates local configuration, reads the merchant account, and
-creates one unpaid expiring checkout session to prove Hosted Checkout is
-available for this merchant account.
+Run `--sandbox` against the local SDK sandbox first. Then run the same command
+without `--sandbox` against live credentials. The command validates local
+configuration, reads the merchant account, checks the active billing mandate,
+confirms the webhook subscription, creates one unpaid expiring checkout session,
+and queues a signed webhook test delivery.
 
 - The merchant account exists.
 - The merchant billing mandate is active.
-- The webhook callback URL is HTTPS and reachable.
+- `SIGLUME_WEBHOOK_SECRET` is present and matches the subscription secret hint.
+- The webhook callback URL is HTTPS and matches an active subscription.
+- The subscription includes `direct_payment.confirmed`.
 - The checkout return URL origins are registered through
   `checkout_allowed_origins`.
 - The account has Hosted Checkout enabled.
+- The signed webhook test delivery reaches the endpoint and returns success.
+
+`--no-api` is only for local config smoke tests. `--no-probe` is a partial API
+check and does not report readiness as ready.
+
+If sandbox readiness fails, make sure `SIGLUME_ENV=sandbox`,
+`SIGLUME_API_BASE=http://127.0.0.1:8787/v1`, `SHOP_PUBLIC_ORIGIN`, and
+`SHOP_WEBHOOK_URL` all point to your local product, and that
+`siglume-sdrp sandbox --webhook-url ...` is still running.
 
 If `createCheckoutSession(...)` or `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError`, do not show the raw 404/409 to the buyer.
@@ -46,10 +60,11 @@ contact for Hosted Checkout enablement.
 
 - Verify the exact raw request body bytes or raw body string.
 - Do not verify a parsed JSON object or a re-stringified JSON body.
-- Return a 2xx only after you have durably recorded the event or safely decided
-  it is duplicate/ignored.
-- Store processed webhook event ids or settlement identifiers durably; an
-  in-memory set is not enough for production.
+- Return a 2xx only after the order update or durable manual-review write has
+  succeeded, or after you safely decided the event is duplicate/ignored.
+- Store processed webhook event ids or settlement identifiers durably, in the
+  same database transaction as the order update/review write. An in-memory set
+  is not enough for production.
 - Do not assume delivery order. A settlement batch event may be reconciled from
   statement APIs rather than from one order challenge.
 - On signature failure, return a non-2xx status and do not mutate order state.

package/examples/express-checkout.ts

@@ -36,11 +36,21 @@ app.use((req, res, next) => {
 });
 
 const orders = new Map<string, any>();
+const processedWebhookEvents = new Set<string>();
 
 async function flagForPaymentStateReview(payload: Record<string, any>): Promise<void> {
   console.warn("payment state review required", payload);
 }
 
+async function processWebhookEventOnce(eventId: string, handler: () => Promise<void>): Promise<"processed" | "duplicate"> {
+  if (processedWebhookEvents.has(eventId)) {
+    return "duplicate";
+  }
+  await handler();
+  processedWebhookEvents.add(eventId);
+  return "processed";
+}
+
 async function handleDirectPaymentConfirmed(event: any): Promise<void> {
   const classification = classifyDirectPaymentConfirmation(event);
 
@@ -67,16 +77,11 @@ async function handleDirectPaymentConfirmed(event: any): Promise<void> {
   }
 
   if (classification.kind === "metered_usage_accepted") {
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
-    if (order) {
-      order.siglume_payment_status = "fulfilled_unsettled";
-      order.siglume_requirement_id = classification.requirement_id;
-    } else {
-      await flagForPaymentStateReview({
-        reason: "unknown_metered_challenge_hash",
-        requirement_id: classification.requirement_id,
-      });
-    }
+    await flagForPaymentStateReview({
+      reason: "metered_integration_required",
+      requirement_id: classification.requirement_id,
+      pricing_band: classification.pricing_band,
+    });
     return;
   }
 
@@ -102,7 +107,19 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
     return;
   }
 
-  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
+  if (!Number(order.payment_attempt || 0)) {
+    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,
@@ -114,6 +131,7 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
   });
 
   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";
 
@@ -134,8 +152,14 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
     header,
   );
 
-  if (event.type === "direct_payment.confirmed") {
-    await handleDirectPaymentConfirmed(event);
+  const result = await processWebhookEventOnce(event.id, async () => {
+    if (event.type === "direct_payment.confirmed") {
+      await handleDirectPaymentConfirmed(event);
+    }
+  });
+  if (result === "duplicate") {
+    res.status(204).send();
+    return;
   }
 
   res.status(204).send();

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.22,<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.22",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
@@ -79,9 +79,17 @@
     "pack:check": "npm pack --json"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^20.16.5",
+    "@types/sql.js": "^1.4.11",
+    "esbuild": "^0.28.1",
+    "express": "^5.2.1",
+    "sql.js": "^1.14.1",
     "tsup": "^8.3.0",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.9"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

package/templates/express/README.md

@@ -1,21 +1,55 @@
 # 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 { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
+import express from "express";
+import {
+  createSiglumeSdrpCheckoutRouter,
+  createSiglumeSdrpWebhookHandler,
+  type SiglumeSdrpRouterOptions,
+} from "./siglume/siglume-sdrp-routes.js";
+import { createPrismaSiglumeOrderStore } from "./siglume/siglume-order-store.sql.js";
+import { prisma } from "../db/prisma.js";
 
-app.use("/payments", createSiglumeSdrpRouter({
+const siglumeOrderStore = createPrismaSiglumeOrderStore(prisma, {
+  dialect: "postgres",
+  orders_table: "orders",
+  order_id_column: "id",
+  amount_minor_column: "amount_minor",
+  currency_column: "currency",
+});
+
+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.
+Use `siglume-order-store.sql.ts` for a durable database-backed adapter. It
+supports Prisma, TypeORM, Sequelize, Drizzle, and any driver that can implement
+the small `SiglumeSqlExecutor` interface. Run
+`createSiglumeSdrpSqlSchema({ dialect: "postgres" })` once in a migration or
+translate the returned SQL into your migration tool.
+
+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;