@siglume/direct-request-payment 0.4.17 → 0.4.19

package/docs/merchant-quickstart.md

@@ -3,6 +3,12 @@
 This guide shows the minimum safe Siglume Direct Request Payment flow for an
 external merchant.
 
+For the shortest existing-product integration path, use
+[10-Minute Product Integration](./quickstart-10-minutes.md). That guide copies
+checkout and webhook routes into an Express or FastAPI product and verifies
+Hosted Checkout readiness before coding. This merchant quickstart is broader
+and includes the agent/API path plus Micro / Nano reconciliation notes.
+
 ## Actors
 
 - Merchant server: owns the order, amount, currency, challenge secret, webhook
@@ -44,8 +50,8 @@ There are two ways a buyer reaches you, and you integrate each differently:
 
 - **Human web shopper → Hosted Checkout (Beta; server rollout in progress).** Create a checkout session and
   redirect the shopper to the Siglume-hosted page (the
-  [section below](#hosted-checkout-human-web-shoppers)). This is the path that
-  resembles a Stripe-style hosted checkout.
+  [section below](#hosted-checkout-human-web-shoppers)). This is the Siglume
+  wallet hosted checkout path for human web shoppers.
 - **AI agent / agent-to-agent (AtoA) → direct API / tools.** An autonomous
   buyer pays through `DirectRequestPaymentClient` or the marketplace tool
   `market_confirm_direct_payment_and_execute`, as in sections 2-4 below.
@@ -59,6 +65,10 @@ the merchant SDK never authenticates the buyer, and you fulfill on the same
 **Beta / server rollout:** Hosted Checkout is rolling out account by account.
 Some merchant accounts may not have the server endpoint enabled yet. The SDK
 raises `HostedCheckoutNotAvailableError` for rollout 404/409 responses.
+Confirm readiness before building the flow; see
+[Hosted Checkout readiness](./troubleshooting.md#hosted-checkout-readiness).
+If the account is not enabled, do not continue with a human web checkout until
+Siglume enables it for that merchant account.
 
 When a person clicks "Pay with Siglume" on your site, create a session and
 redirect them to the returned `checkout_url`. They sign into Siglume on the
@@ -600,9 +610,16 @@ Do not book Micro / Nano provider revenue as settled revenue until the batch is
 `settled` and `chain_receipt_id` is present. See
 [Micro / Nano Statements and Notices](./metered-statements.md) for the full
 manual, including buyer past-due blocks and public failure fields.
+For a compact state-machine view across Standard, Micro, and Nano, see
+[Payment lifecycle](./payment-lifecycle.md).
 
 ## Failure Handling
 
+For retry policy, buyer-safe copy, webhook signature failures, Hosted Checkout
+readiness, and support escalation, see
+[Troubleshooting](./troubleshooting.md). The short list below is only the common
+payment-domain errors.
+
 - `EXTERNAL_402_CHALLENGE_REQUIRED`: the merchant server did not provide a
   challenge.
 - `INVALID_EXTERNAL_402_CHALLENGE`: the amount, currency, merchant, nonce, or

package/docs/payment-lifecycle.md

@@ -0,0 +1,85 @@
+# Payment Lifecycle
+
+This page separates three ideas that are easy to mix up:
+
+- **checkout status**: the shopper's Hosted Checkout session state,
+- **merchant fulfillment state**: whether your system can deliver the order,
+- **provider revenue state**: whether the provider has settled revenue.
+
+## Standard Payment
+
+```text
+checkout open
+  -> buyer authenticates
+  -> buyer pays
+  -> direct_payment.confirmed webhook
+  -> classifier kind: standard_settled
+  -> merchant marks order paid once
+  -> provider revenue is settled
+```
+
+For Standard Payment, fulfill only after a signed
+`direct_payment.confirmed` webhook verifies and
+`classifyDirectPaymentConfirmation(event)` returns `standard_settled`. That
+classification requires Standard pricing, per-payment on-chain finality, settled
+status, non-empty `requirement_id`, non-empty `challenge_hash`, and non-empty
+`chain_receipt_id`.
+
+## Micro / Nano Payment
+
+```text
+checkout open or agent/API payment starts
+  -> usage accepted
+  -> direct_payment.confirmed webhook
+  -> classifier kind: metered_usage_accepted
+  -> merchant may fulfill as fulfilled_unsettled
+  -> open period closes by amount threshold or schedule
+  -> final notice window
+  -> submitted / retrying / past_due if needed
+  -> aggregated on-chain settlement
+  -> classifier kind: metered_batch_settled
+  -> provider revenue is settled
+```
+
+For Micro / Nano, `metered_usage_accepted` means the usage can be fulfilled
+under the SDRP delayed settlement model, but provider revenue is not settled
+yet. Provider revenue becomes settled only when the settlement batch is settled
+on-chain and has a `chain_receipt_id`.
+
+## Field meanings
+
+| Field or state | What it means | What it does not mean |
+| --- | --- | --- |
+| Hosted Checkout `status: "paid"` | The checkout session accepted the wallet payment flow. | For Micro / Nano, it does not mean provider revenue is settled. |
+| `standard_settled` | Standard payment is on-chain settled and can mark an order paid. | It is not used for Micro / Nano accepted usage. |
+| `metered_usage_accepted` | Micro / Nano usage is accepted and may be fulfilled as unsettled. | It is not settled provider revenue. |
+| `fulfilled_unsettled` | Your merchant system delivered the item before Micro / Nano settlement. | It is not a Siglume settlement status. |
+| `metered_batch_settled` | Aggregated Micro / Nano batch settled on-chain. | It does not identify one order by challenge hash. |
+| `pending_settlement` | Micro / Nano usage is waiting for aggregated settlement. | It is not a failure by itself. |
+| `past_due` | Settlement failed or remains unresolved after retry state. | It is not collected revenue. |
+| `uncollectible` / `written_off` | Operator terminal resolution after past-due review. | It is not settled, unsettled, or past-due revenue. |
+
+## Fulfillment rules
+
+- Use the webhook raw body and `Siglume-Signature`; do not verify a
+  re-stringified JSON object.
+- Store `challenge_hash` on the order before redirecting the buyer.
+- For Standard, mark paid only from `standard_settled`.
+- For Micro / Nano, use a separate local state such as
+  `fulfilled_unsettled`; reconcile final revenue from statement APIs and batch
+  settlement events.
+- Treat `unknown` classifications as manual review. Do not mark paid or
+  fulfilled from the event name alone.
+
+## Revenue rules
+
+- Standard revenue is settled when the payment confirms on-chain.
+- Micro / Nano buyer debit is seller-borne-fee safe:
+  `buyer_debit_minor = provider_gross_amount_minor`.
+- Micro / Nano provider receivable is
+  `provider_gross_amount_minor - protocol_fee_minor`.
+- Micro / Nano revenue is settled only after the aggregated batch is settled
+  on-chain.
+- If `total_unsettled_exposure_minor` for the same buyer / provider / token /
+  pricing band is at or above the fixed threshold, new Micro / Nano usage is
+  paused until settlement succeeds or an operator resolves the state.

package/docs/pricing.md

@@ -1,7 +1,7 @@
 # Pricing
 
 This page documents the trial-phase merchant pricing for Siglume Direct Request
-Payment as of SDK v0.4.17. Pricing can change by agreement or future product
+Payment as of SDK v0.4.19. Pricing can change by agreement or future product
 release; the Siglume platform response is the source of truth for per-payment
 fee data returned at runtime.
 
@@ -192,11 +192,11 @@ once provider gross reaches JPY 10,000 or USD 100.00. These are fixed
 market-specific thresholds, not FX conversions of one another. A payment is
 final only after its on-chain settlement confirms. Micro and Nano are automatic
 amount bands, not customer-selected options. The account-assigned period
-boundaries, roughly 3-day pre-debit notice window, early settlement threshold,
-and current retry policy above are the public behavior as of 2026-06-19. Treat
-the platform's statement status, `not_before_attempt_at`, Standard `fee_bps`,
-and Micro / Nano statement amount fields as authoritative rather than
-hard-coding local revenue recognition.
+boundaries, roughly 3-day pre-debit notice window, and current retry policy above
+are platform-managed public behavior as of 2026-06-19. Treat the platform's
+statement status, `not_before_attempt_at`, Standard `fee_bps`, and Micro / Nano
+statement amount fields as authoritative rather than hard-coding local revenue
+recognition.
 
 ## Micro / Nano Seller-borne Amounts
 

package/docs/quickstart-10-minutes.md

@@ -0,0 +1,145 @@
+# 10-Minute Product Integration
+
+This guide is the supported 10-minute path for adding SDRP Hosted Checkout to
+an existing product. The goal is to
+add two routes to your own server:
+
+- `POST /payments/checkout/siglume/start`
+- `POST /payments/webhooks/siglume`
+
+The SDK supplies the readiness check, route files, webhook verification, payment
+classification, and the order-store adapter contract. Your app supplies the
+real order lookup and fulfillment writes.
+
+## 0. Readiness first
+
+Install the SDK in your product.
+
+Node / Express:
+
+```bash
+npm install @siglume/direct-request-payment
+```
+
+Python / FastAPI:
+
+```bash
+pip install siglume-direct-request-payment
+```
+
+Set these environment variables in your app or `.env`:
+
+```bash
+SIGLUME_MERCHANT_AUTH_TOKEN=<merchant Siglume bearer token>
+SIGLUME_DIRECT_PAYMENT_MERCHANT=<merchant key>
+SHOP_PUBLIC_ORIGIN=https://www.your-product.example
+SHOP_WEBHOOK_URL=https://api.your-product.example/payments/webhooks/siglume
+```
+
+Then run:
+
+```bash
+npx siglume-check readiness
+```
+
+The readiness check fails before you write checkout code if any required item is
+missing. It checks local config, reads the merchant account, and creates one
+unpaid expiring Hosted Checkout probe session to prove the account is enabled
+and the return origin is accepted. No buyer is charged.
+
+For CI or a preflight script:
+
+```bash
+npx siglume-check readiness --json
+```
+
+If this command fails, fix the reported item first. Do not build a human web
+checkout path until readiness passes.
+
+## 1. Copy integration files into your product
+
+For Express:
+
+```bash
+npx siglume-sdrp init express --target src/siglume
+```
+
+For FastAPI:
+
+```bash
+siglume-sdrp init fastapi --target app/siglume
+```
+
+These commands copy framework-specific route files into your codebase. The
+generated files are intentionally small and are meant to be edited.
+
+## 2. Mount the routes
+
+Express:
+
+```ts
+import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
+
+app.use("/payments", createSiglumeSdrpRouter({
+  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,
+}));
+```
+
+FastAPI:
+
+```py
+from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
+from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
+
+app.include_router(
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    prefix="/payments",
+)
+```
+
+## 3. Replace the order-store example
+
+Replace the example store with your product's order database. The adapter must:
+
+- load the order by your `order_id`,
+- verify the current user is allowed to pay for that order,
+- return the server-authored `amount_minor` and `currency`,
+- persist `challenge_hash` and `checkout_session_id` before redirecting,
+- record webhook event ids durably,
+- mark Standard orders paid exactly once,
+- mark Micro / Nano orders as fulfilled but unsettled exactly once,
+- route unknown classifications to manual review.
+
+Do not calculate the amount from browser input.
+
+## 4. Start checkout from your frontend
+
+Call your own server route:
+
+```bash
+curl -X POST https://api.your-product.example/payments/checkout/siglume/start \
+  -H "content-type: application/json" \
+  -d "{\"order_id\":\"order_123\"}"
+```
+
+Redirect the shopper to the returned `checkout_url`.
+
+## 5. Done means
+
+Your product is integrated when:
+
+- `npx siglume-check readiness` passes,
+- your product has mounted checkout and webhook routes,
+- your order database stores `challenge_hash` for the order,
+- the signed webhook verifies against the raw body,
+- `standard_settled` marks the order paid once,
+- `metered_usage_accepted` uses a separate fulfilled-but-unsettled state.
+
+For Micro / Nano revenue reconciliation, read
+[Payment lifecycle](./payment-lifecycle.md) and
+[Micro / Nano Statements and Notices](./metered-statements.md).

package/docs/troubleshooting.md

@@ -0,0 +1,70 @@
+# Troubleshooting
+
+Use this page when an integration fails before, during, or after checkout.
+Where a Siglume API response includes `request_id`, `trace_id`, or
+`support_reference`, include that value when contacting Siglume support or your
+Siglume account contact.
+
+## Hosted Checkout readiness
+
+Hosted Checkout is enabled account by account during beta. Check this before
+building a human web checkout:
+
+```bash
+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.
+
+- The merchant account exists.
+- The merchant billing mandate is active.
+- The webhook callback URL is HTTPS and reachable.
+- The checkout return URL origins are registered through
+  `checkout_allowed_origins`.
+- The account has Hosted Checkout enabled.
+
+If `createCheckoutSession(...)` or `getCheckoutSession(...)` raises
+`HostedCheckoutNotAvailableError`, do not show the raw 404/409 to the buyer.
+Stop the human checkout flow and contact Siglume support or your Siglume account
+contact for Hosted Checkout enablement.
+
+## API errors
+
+| Status / code | Likely cause | Retry? | Same idempotency key? | Buyer copy | Operator action |
+| --- | --- | --- | --- | --- | --- |
+| `401` / `403` | Missing token, expired token, wrong account, or insufficient scope. | No, not until credentials are fixed. | n/a | "Payment setup needs attention. Please try later." | Check whether you used a merchant Siglume bearer token for merchant setup and a buyer/provider Siglume bearer token for buyer/provider APIs. Do not use `cli_` keys. |
+| `404` / `409` Hosted Checkout rollout | Hosted Checkout is not enabled for this merchant account. | No. | n/a | "This payment method is not available for this store yet." | Contact Siglume for enablement; use agent/API only if that is actually your buyer flow. |
+| `409` idempotency conflict | The same idempotency key was reused with different Micro / Nano input. | No. | Do not reuse with different payload. | "This payment attempt could not be completed. Please retry from the order page." | Create a new payment attempt nonce/key for the changed order. |
+| `422` validation error | Invalid amount, currency, nonce, URL, origin, or metadata shape. | No, fix input. | n/a | "Payment information is invalid. Please refresh and retry." | Validate server-side amount/currency and registered URL origins. |
+| `429` | Rate limit. | Yes, after `Retry-After` when present. | Reuse only for the same logical attempt and same payload. | "Payment is busy. Please retry shortly." | Back off; do not create many new payment attempts. |
+| `5xx` or timeout | Temporary Siglume or network failure. | Yes, with bounded exponential backoff. | Reuse for the same logical attempt and same payload. | "Payment is temporarily unavailable. Please retry shortly." | Log request identifiers; avoid fulfilling without a verified webhook. |
+| `METERED_SETTLEMENT_PAST_DUE` | Micro / Nano usage is paused because unsettled exposure or a past-due batch remains unresolved for the same buyer / provider / token / pricing band. | No, until settlement succeeds or is resolved. | n/a | "This low-value payment is paused until previous settlement completes." | Check statement APIs and `support_reference`; do not call the provider API. |
+
+## Webhook failures
+
+- 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.
+- 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.
+- On a valid but unknown payment classification, return 2xx only after routing
+  it to durable manual review.
+
+## Refunds and adjustments
+
+This SDK release does not expose a self-service refund API. For Standard
+Payment refunds or Micro / Nano adjustments, use the explicit Siglume support or
+platform process available to your account. Do not reverse settled revenue by
+editing local statements or CSV exports.
+
+## Safe buyer messages
+
+Keep buyer-facing messages short and non-diagnostic. Do not expose raw API
+errors, wallet internals, RPC URLs, stack traces, webhook secrets, or support
+references. Log detailed context server-side with request identifiers.

package/examples/express-checkout.ts

@@ -1,3 +1,17 @@
+/**
+ * DEMO ONLY.
+ *
+ * This file shows the minimum Hosted Checkout webhook shape, but it is not
+ * production-safe:
+ * - in-memory order storage
+ * - no buyer authentication or order ownership checks
+ * - no database transaction around fulfillment
+ * - no durable webhook event deduplication
+ * - no production refund or support workflow
+ *
+ * For production, persist orders and processed webhook ids in a database,
+ * authorize every checkout start request, and make fulfillment idempotent.
+ */
 import express from "express";
 import {
   classifyDirectPaymentConfirmation,

package/examples/hosted-checkout-python/.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-python/README.md

@@ -0,0 +1,21 @@
+# Hosted Checkout Python Starter
+
+Minimal Flask starter for one Standard Payment test order.
+
+```bash
+cp .env.example .env
+python -m pip install -e . siglume-direct-request-payment
+python app.py
+```
+
+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-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.19,<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"
+  }
+}