@siglume/direct-request-payment 0.4.17 → 0.4.18

package/docs/merchant-quickstart.md

@@ -3,6 +3,13 @@
 This guide shows the minimum safe Siglume Direct Request Payment flow for an
 external merchant.
 
+For the shortest first-test path, use
+[10-Minute First Test Payment](./quickstart-10-minutes.md). That guide covers
+only one Standard Payment test after account, Hosted Checkout, billing mandate,
+HTTPS webhook, and buyer wallet prerequisites are ready. 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 +51,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 +66,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 +611,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.18. 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,176 @@
+# 10-Minute First Test Payment
+
+This guide is the shortest supported path to one **Standard Payment** test
+through Siglume wallet Hosted Checkout. It is not a full production launch.
+
+## What the 10 minutes cover
+
+You can count the 10 minutes only after the prerequisites below are already
+ready. The target outcome is:
+
+- one Standard-band order,
+- one Hosted Checkout session,
+- one signed `direct_payment.confirmed` webhook,
+- one idempotent local fulfillment decision.
+
+This guide does **not** cover production monitoring, refunds, subscriptions,
+scheduled autopay, game entitlement recovery, or Micro / Nano accounting.
+
+## Prerequisites
+
+Before starting, confirm:
+
+- You have a Siglume merchant account and merchant Siglume bearer token.
+- Hosted Checkout is enabled for that merchant account.
+- The merchant billing mandate is active, including any required wallet
+  approval.
+- You have a public HTTPS webhook URL that can receive the raw request body.
+- Your checkout return URL origin is known and can be registered.
+- The buyer has a Siglume wallet funded in the settlement token for the test
+  market: JPYC for JPY, USDC for USD.
+- Your order amount is in the Standard band: JPY 501+ or USD 3.01+.
+
+If Hosted Checkout is not enabled, stop here. The SDK raises
+`HostedCheckoutNotAvailableError` for rollout 404/409 responses; contact
+Siglume support or your Siglume account contact to enable the account before
+continuing with a human web checkout.
+
+## 1. Install
+
+Runnable starter directories are available if you want a small server to edit:
+
+- [TypeScript Express starter](../examples/hosted-checkout-typescript)
+- [Python Flask starter](../examples/hosted-checkout-python)
+
+For an existing app, install the SDK directly:
+
+```bash
+npm install @siglume/direct-request-payment
+```
+
+or:
+
+```bash
+pip install siglume-direct-request-payment
+```
+
+## 2. Set environment variables
+
+```bash
+SIGLUME_MERCHANT_AUTH_TOKEN=<merchant Siglume bearer token>
+SIGLUME_DIRECT_PAYMENT_MERCHANT=example_merchant
+SHOP_PUBLIC_ORIGIN=https://www.example.com
+SHOP_WEBHOOK_URL=https://api.example.com/siglume/webhook
+```
+
+Do not use a Developer Portal `cli_` API key. Merchant setup requires the
+merchant's Siglume bearer token.
+
+## 3. Register merchant settings
+
+Run setup once from your server, CI, or integration machine:
+
+```ts
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+});
+
+const setup = await merchant.setupCheckout({
+  merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
+  display_name: "Example Merchant",
+  billing_plan: "launch",
+  billing_currency: "JPY",
+  webhook_callback_url: process.env.SHOP_WEBHOOK_URL!,
+  checkout_allowed_origins: [process.env.SHOP_PUBLIC_ORIGIN!],
+});
+
+console.log(setup.env.SIGLUME_DIRECT_PAYMENT_MERCHANT);
+```
+
+Store the returned `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` and
+`SIGLUME_WEBHOOK_SECRET` in a server-side secret store. Secret values are
+returned only when created or rotated.
+
+## 4. Create a Standard checkout session
+
+For each order, create the order on your server first. Then create a Hosted
+Checkout session:
+
+```ts
+const session = await merchant.createCheckoutSession({
+  merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
+  amount_minor: 1200,
+  currency: "JPY",
+  nonce: "order_123-attempt_1",
+  success_url: `${process.env.SHOP_PUBLIC_ORIGIN}/thanks`,
+  cancel_url: `${process.env.SHOP_PUBLIC_ORIGIN}/cart`,
+  metadata: { order_id: "order_123" },
+});
+
+await orders.update("order_123", {
+  siglume_challenge_hash: session.challenge_hash,
+  siglume_checkout_session_id: session.session_id,
+  siglume_payment_status: "pending",
+});
+
+redirect(session.checkout_url);
+```
+
+The browser must never choose the amount, currency, nonce, or return URL. The
+session is single-use and expires.
+
+## 5. Fulfill from the signed webhook
+
+The browser return path is not the source of truth. Use the signed webhook and
+classify the confirmation:
+
+```ts
+import {
+  classifyDirectPaymentConfirmation,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+const { event } = await verifyDirectRequestPaymentWebhook(
+  process.env.SIGLUME_WEBHOOK_SECRET!,
+  rawRequestBody,
+  siglumeSignatureHeader,
+);
+
+if (event.type === "direct_payment.confirmed") {
+  const confirmation = classifyDirectPaymentConfirmation(event);
+
+  if (confirmation.kind === "standard_settled") {
+    await orders.markPaidOnceByChallengeHash(confirmation.challenge_hash, {
+      requirement_id: confirmation.requirement_id,
+      chain_receipt_id: confirmation.chain_receipt_id,
+    });
+  } else if (confirmation.kind === "metered_usage_accepted") {
+    await orders.markFulfilledButUnsettledOnceByChallengeHash(
+      confirmation.challenge_hash,
+      { requirement_id: confirmation.requirement_id },
+    );
+  } else {
+    await orders.flagForPaymentStateReview(confirmation);
+  }
+}
+```
+
+For this 10-minute guide, keep the test order in the Standard band so the
+expected successful branch is `standard_settled`.
+
+## Done means
+
+You are done with the quickstart when:
+
+- the checkout session is created,
+- the buyer reaches the Siglume wallet hosted checkout page,
+- the signed webhook verifies against the raw body,
+- `classifyDirectPaymentConfirmation(event)` returns `standard_settled`,
+- your order is marked paid once, keyed by the stored `challenge_hash`.
+
+Before production, complete the full checklist in
+[Merchant Quickstart](./merchant-quickstart.md#go-live-checklist), read
+[Payment lifecycle](./payment-lifecycle.md), and prepare the failure handling in
+[Troubleshooting](./troubleshooting.md).

package/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+# 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:
+
+- 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.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"
+  }
+}