@siglume/direct-request-payment 0.4.16 → 0.4.18

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

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+from flask import Flask, jsonify, request
+from siglume_direct_request_payment import (
+    DirectRequestPaymentMerchantClient,
+    HostedCheckoutNotAvailableError,
+    classify_direct_payment_confirmation,
+    verify_direct_request_payment_webhook,
+)
+
+from order_store import (
+    all_orders,
+    find_order_by_challenge_hash,
+    get_order,
+    mark_webhook_event_processed_once,
+    save_order,
+)
+
+load_dotenv()
+
+app = Flask(__name__)
+merchant_key = os.environ.get("SIGLUME_DIRECT_PAYMENT_MERCHANT", "example_merchant")
+shop_origin = os.environ.get("SHOP_PUBLIC_ORIGIN", "https://www.example.com")
+siglume_merchant = DirectRequestPaymentMerchantClient(
+    auth_token=os.environ.get("SIGLUME_MERCHANT_AUTH_TOKEN"),
+)
+
+
+@app.get("/orders")
+def orders():
+    return jsonify({"orders": all_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)
+    if order is None:
+        return jsonify({"error": "order_not_found"}), 404
+
+    order["payment_attempt"] = int(order.get("payment_attempt") or 0) + 1
+    session = siglume_merchant.create_checkout_session(
+        merchant=merchant_key,
+        amount_minor=int(order["amount_minor"]),
+        currency=str(order["currency"]),
+        nonce=f"{order['id']}-attempt_{order['payment_attempt']}",
+        success_url=f"{shop_origin}/thanks",
+        cancel_url=f"{shop_origin}/cart",
+        metadata={"order_id": order["id"]},
+    )
+
+    order["siglume_challenge_hash"] = session["challenge_hash"]
+    order["siglume_checkout_session_id"] = session["session_id"]
+    order["siglume_payment_status"] = "pending"
+    save_order(order)
+
+    return jsonify(
+        {
+            "order_id": order["id"],
+            "amount_minor": order["amount_minor"],
+            "currency": order["currency"],
+            "checkout_url": session["checkout_url"],
+            "session_id": session["session_id"],
+        }
+    )
+
+
+@app.post("/siglume/webhook")
+def siglume_webhook():
+    verified = verify_direct_request_payment_webhook(
+        os.environ.get("SIGLUME_WEBHOOK_SECRET", ""),
+        request.get_data(),
+        request.headers.get("Siglume-Signature", ""),
+    )
+    event = verified["event"]
+
+    if not mark_webhook_event_processed_once(str(event["id"])):
+        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
+
+
+@app.errorhandler(HostedCheckoutNotAvailableError)
+def hosted_checkout_not_available(_: HostedCheckoutNotAvailableError):
+    return jsonify({"error": "hosted_checkout_not_enabled"}), 409
+
+
+@app.errorhandler(Exception)
+def internal_error(error: Exception):
+    app.logger.error("checkout starter error", extra={"name": type(error).__name__})
+    return jsonify({"error": "internal_error"}), 500
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", "3000")))

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

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+Order = dict[str, Any]
+
+_orders: dict[str, Order] = {
+    "order_123": {
+        "id": "order_123",
+        "amount_minor": 1200,
+        "currency": "JPY",
+        "payment_attempt": 0,
+        "siglume_payment_status": "created",
+    }
+}
+_processed_webhook_events: set[str] = set()
+
+
+def get_order(order_id: str) -> Order | None:
+    return _orders.get(order_id)
+
+
+def all_orders() -> list[Order]:
+    return list(_orders.values())
+
+
+def save_order(order: Order) -> None:
+    _orders[str(order["id"])] = order
+
+
+def find_order_by_challenge_hash(challenge_hash: str) -> Order | None:
+    for order in _orders.values():
+        if order.get("siglume_challenge_hash") == challenge_hash:
+            return order
+    return None
+
+
+def mark_webhook_event_processed_once(event_id: str) -> bool:
+    if event_id in _processed_webhook_events:
+        return False
+    _processed_webhook_events.add(event_id)
+    return True

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

@@ -0,0 +1,9 @@
+[project]
+name = "siglume-hosted-checkout-python-starter"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+  "Flask>=3.0,<4",
+  "python-dotenv>=1.0,<2",
+  "siglume-direct-request-payment>=0.4.18,<0.5",
+]

package/examples/hosted-checkout-typescript/.env.example

@@ -0,0 +1,5 @@
+SIGLUME_MERCHANT_AUTH_TOKEN=
+SIGLUME_DIRECT_PAYMENT_MERCHANT=example_merchant
+SIGLUME_WEBHOOK_SECRET=
+SHOP_PUBLIC_ORIGIN=https://www.example.com
+PORT=3000

package/examples/hosted-checkout-typescript/README.md

@@ -0,0 +1,21 @@
+# Hosted Checkout TypeScript Starter
+
+Minimal Express starter for one Standard Payment test order.
+
+```bash
+cp .env.example .env
+npm install
+npm run dev
+```
+
+Then call:
+
+```bash
+curl -X POST http://localhost:3000/checkout/siglume/start \
+  -H "content-type: application/json" \
+  -d "{\"order_id\":\"order_123\"}"
+```
+
+This starter uses in-memory storage so it is easy to inspect. Replace it with a
+database before production. Production systems must persist orders, processed
+webhook event ids, and fulfillment state in one durable transaction.

package/examples/hosted-checkout-typescript/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "siglume-hosted-checkout-typescript-starter",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@siglume/direct-request-payment": "file:../..",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.16.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

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

@@ -0,0 +1,52 @@
+export type OrderStatus = "created" | "pending" | "paid" | "fulfilled_unsettled" | "review_required";
+
+export interface Order {
+  id: string;
+  amount_minor: number;
+  currency: "JPY" | "USD";
+  payment_attempt: number;
+  siglume_challenge_hash?: string;
+  siglume_checkout_session_id?: string;
+  siglume_requirement_id?: string;
+  siglume_chain_receipt_id?: string;
+  siglume_payment_status: OrderStatus;
+}
+
+const orders = new Map<string, Order>([
+  [
+    "order_123",
+    {
+      id: "order_123",
+      amount_minor: 1200,
+      currency: "JPY",
+      payment_attempt: 0,
+      siglume_payment_status: "created",
+    },
+  ],
+]);
+
+const processedWebhookEvents = new Set<string>();
+
+export function getOrder(orderId: string): Order | undefined {
+  return orders.get(orderId);
+}
+
+export function allOrders(): Order[] {
+  return [...orders.values()];
+}
+
+export function saveOrder(order: Order): void {
+  orders.set(order.id, order);
+}
+
+export function findOrderByChallengeHash(challengeHash: string): Order | undefined {
+  return [...orders.values()].find((order) => order.siglume_challenge_hash === challengeHash);
+}
+
+export function markWebhookEventProcessedOnce(eventId: string): boolean {
+  if (processedWebhookEvents.has(eventId)) {
+    return false;
+  }
+  processedWebhookEvents.add(eventId);
+  return true;
+}

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

@@ -0,0 +1,139 @@
+import "dotenv/config";
+
+import express from "express";
+import {
+  classifyDirectPaymentConfirmation,
+  DirectRequestPaymentMerchantClient,
+  HostedCheckoutNotAvailableError,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+import {
+  allOrders,
+  findOrderByChallengeHash,
+  getOrder,
+  markWebhookEventProcessedOnce,
+  saveOrder,
+} from "./order-store.js";
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+const merchantKey = process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant";
+const shopOrigin = process.env.SHOP_PUBLIC_ORIGIN || "https://www.example.com";
+
+const siglumeMerchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN,
+});
+
+const asyncRoute =
+  (handler: express.RequestHandler): express.RequestHandler =>
+  (req, res, next) => {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+
+app.get("/orders", (_req, res) => {
+  res.json({ orders: allOrders() });
+});
+
+app.post(
+  "/checkout/siglume/start",
+  express.json(),
+  asyncRoute(async (req, res) => {
+    const orderId = String(req.body?.order_id || "");
+    const order = getOrder(orderId);
+    if (!order) {
+      res.status(404).json({ error: "order_not_found" });
+      return;
+    }
+
+    order.payment_attempt += 1;
+    const session = await siglumeMerchant.createCheckoutSession({
+      merchant: merchantKey,
+      amount_minor: order.amount_minor,
+      currency: order.currency,
+      nonce: `${order.id}-attempt_${order.payment_attempt}`,
+      success_url: `${shopOrigin}/thanks`,
+      cancel_url: `${shopOrigin}/cart`,
+      metadata: { order_id: order.id },
+    });
+
+    order.siglume_challenge_hash = session.challenge_hash;
+    order.siglume_checkout_session_id = session.session_id;
+    order.siglume_payment_status = "pending";
+    saveOrder(order);
+
+    res.json({
+      order_id: order.id,
+      amount_minor: order.amount_minor,
+      currency: order.currency,
+      checkout_url: session.checkout_url,
+      session_id: session.session_id,
+    });
+  }),
+);
+
+app.post(
+  "/siglume/webhook",
+  express.raw({ type: "application/json" }),
+  asyncRoute(async (req, res) => {
+    const { event } = await verifyDirectRequestPaymentWebhook(
+      process.env.SIGLUME_WEBHOOK_SECRET || "",
+      req.body,
+      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);
+        }
+      } 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,
+        });
+      }
+    }
+
+    res.status(204).send();
+  }),
+);
+
+app.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;
+  }
+  console.error("checkout starter error:", {
+    name: error instanceof Error ? error.name : "Error",
+  });
+  res.status(500).json({ error: "internal_error" });
+});
+
+app.listen(port, () => {
+  console.log(`Siglume Hosted Checkout starter listening on http://localhost:${port}`);
+});

package/examples/hosted-checkout-typescript/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
@@ -54,6 +54,9 @@
     "dist",
     "docs",
     "examples",
+    "!examples/**/node_modules",
+    "!examples/**/__pycache__",
+    "!examples/**/*.pyc",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"