@siglume/direct-request-payment 0.4.18 → 0.4.20

package/docs/api-reference.md

@@ -356,7 +356,8 @@ Returns:
 `merchant.merchant_account.metadata_jsonb.metered_risk_acceptance` records the
 merchant's Micro / Nano delayed-settlement risk acceptance receipt with
 `terms_version`, `accepted_at`, `principal_user_id`, `receipt_id`, and fixed
-market thresholds `JPY: 10000` / `USD: 10000`.
+market thresholds JPY 10,000 / USD 100.00 (`settlement_threshold_minor` is
+`10000` for both JPY minor units and USD cents).
 
 Secrets are returned only when created or rotated. Existing secrets are not
 replayed by `getMerchant` / `get_merchant`.
@@ -372,7 +373,9 @@ POST /v1/sdrp/direct-payments/merchants
 Creates or updates the merchant account for the authenticated merchant user.
 Accepts the optional `checkout_allowed_origins: string[]` return-URL origin
 allowlist described under `setupCheckout` above; the same normalization and
-webhook-origin auto-allow apply.
+webhook-origin auto-allow apply. Python annotates this direct response as
+`DirectRequestPaymentMerchantResponse`; `setup_checkout(...)` returns
+`DirectRequestPaymentCheckoutSetupResult`.
 
 ### `createCheckoutSession(input)` / `create_checkout_session(...)`
 
@@ -535,6 +538,41 @@ Defaults event types to `direct_payment.confirmed` and
 `direct_payment.spent`. The returned `signing_secret` is shown only at creation
 or rotation.
 
+### `listWebhookSubscriptions()` / `list_webhook_subscriptions()`
+
+Calls:
+
+```text
+GET /v1/market/webhooks/subscriptions
+```
+
+Returns the current user's webhook subscriptions without the full signing
+secret. Use `signing_secret_hint` to confirm that the local
+`SIGLUME_WEBHOOK_SECRET` is the expected secret.
+
+### `queueWebhookTestDelivery(input)` / `queue_webhook_test_delivery(...)`
+
+Calls:
+
+```text
+POST /v1/market/webhooks/test-deliveries
+```
+
+Queues a signed test event to one or more subscription ids. `siglume-check
+readiness` uses this for a harmless `direct_payment.confirmed` readiness probe.
+
+### `listWebhookDeliveries(input)` / `list_webhook_deliveries(...)`
+
+Calls:
+
+```text
+GET /v1/market/webhooks/deliveries
+```
+
+Supports `subscription_id`, `event_type`, `status`, and `limit`. Readiness polls
+this list after queueing the test delivery and only passes when the matching
+delivery status becomes `delivered`.
+
 ## `DirectRequestPaymentClient`
 
 Thin wrapper around the current Siglume Direct Request Payment HTTP contract.
@@ -1012,10 +1050,10 @@ the `Siglume-Signature` header; use
 `verifyDirectRequestPaymentWebhook(...)` /
 `verify_direct_request_payment_webhook(...)` for signature verification and
 parsing together. Throws
-`SiglumeWebhookPayloadError` on a malformed event, or when a
-`direct_payment.confirmed` event does not carry a supported Direct Request
-Payment mode (`external_402` or `metered_settlement_batch`). The `payload`
-argument is positional in both languages.
+`SiglumeWebhookPayloadError` on a malformed event. It does not reject an
+unsupported `direct_payment.confirmed` mode by itself; the classifier returns
+`kind: "unknown"` with `reason: "unsupported_confirmation_mode"` for that case.
+The `payload` argument is positional in both languages.
 
 For `direct_payment.confirmed`, inspect `event.data.pricing_band`,
 `event.data.settlement_cadence`, `event.data.finality`,
@@ -1039,13 +1077,15 @@ Recommended branch: call `classifyDirectPaymentConfirmation(event)` /
   pricing, per-payment on-chain finality, settled status, non-empty
   `requirement_id`, non-empty `challenge_hash`, and non-empty
   `chain_receipt_id`.
-- `metered_usage_accepted`: treat the usage as accepted but unsettled. This
-  requires Micro / Nano pricing, `finality === "aggregated_onchain_settlement"`,
-  the matching settlement cadence (`micro` -> `weekly`, `nano` -> `monthly`),
+- `metered_usage_accepted`: treat the usage as accepted but unsettled only if
+  your integration has explicitly enabled Micro / Nano delayed-settlement
+  handling. This requires Micro / Nano pricing,
+  `finality === "aggregated_onchain_settlement"`, the matching settlement
+  cadence (`micro` -> `weekly`, `nano` -> `monthly`),
   `settlement_status === "pending_settlement"`, non-empty `requirement_id`, and
-  non-empty `challenge_hash`. SDRP merchant setup and terms assume the merchant
-  accepts this delayed aggregated settlement model for Micro / Nano amount
-  bands; reconcile final revenue from statement APIs / settlement batches.
+  non-empty `challenge_hash`. Standard-only integrations should route this to
+  review or return `METERED_INTEGRATION_REQUIRED`; Micro / Nano integrations
+  must reconcile final revenue from statement APIs / settlement batches.
 - `unknown`: do not mark paid or fulfilled from the event type alone; fetch the
   requirement or route the event to manual review.
 
@@ -1153,7 +1193,11 @@ package exports `TypedDict` names for the high-risk response shapes:
 - `DirectRequestPaymentPastDueBlock`
 - `DirectRequestPaymentProviderMeteredTotals`
 - `DirectRequestPaymentListResponse`
-- `DirectRequestPaymentMerchantSetupResponse`
+- `DirectRequestPaymentMerchantResponse`
+- `DirectRequestPaymentCheckoutSetupResult`
+- `DirectRequestPaymentMerchantSetupResponse` (compatibility alias for checkout setup result)
+- `DirectRequestPaymentWebhookSubscription`
+- `DirectRequestPaymentWebhookDelivery`
 - `DirectRequestPaymentWebhookVerification`
 - `DirectRequestPaymentConfirmationClassification`
 

package/docs/merchant-quickstart.md

@@ -3,12 +3,11 @@
 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.
+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
 
@@ -460,16 +459,9 @@ if (confirmation.kind === "standard_settled") {
 }
 
 if (confirmation.kind === "metered_usage_accepted") {
-  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
-  if (!order) {
-    await orders.flagForPaymentStateReview({
-      reason: "unknown_metered_challenge_hash",
-      requirement_id: confirmation.requirement_id,
-    });
-    return new Response(null, { status: 204 });
-  }
-  await orders.markFulfilledButUnsettledOnce(order.id, {
-    siglume_requirement_id: confirmation.requirement_id,
+  await orders.flagForPaymentStateReview({
+    reason: "metered_integration_required",
+    requirement_id: confirmation.requirement_id,
     pricing_band: confirmation.pricing_band,
   });
   return new Response(null, { status: 204 });
@@ -532,16 +524,9 @@ if confirmation["kind"] == "standard_settled":
     return "", 204
 
 if confirmation["kind"] == "metered_usage_accepted":
-    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
-    if not order:
-        orders.flag_for_payment_state_review(
-            reason="unknown_metered_challenge_hash",
-            requirement_id=confirmation["requirement_id"],
-        )
-        return "", 204
-    orders.mark_fulfilled_but_unsettled_once(
-        order["id"],
-        siglume_requirement_id=confirmation["requirement_id"],
+    orders.flag_for_payment_state_review(
+        reason="metered_integration_required",
+        requirement_id=confirmation["requirement_id"],
         pricing_band=confirmation["pricing_band"],
     )
     return "", 204

package/docs/metered-statements.md

@@ -195,9 +195,12 @@ Threshold-control fields:
 - `settlement_trigger`: `amount_threshold` or `scheduled_close`
 - `settlement_threshold_minor`: JPY `10000` or USD `10000` minor units
 - `threshold_reached_at`: set when the fixed amount threshold closed the batch
-- `total_unsettled_exposure_minor`: open plus `notice_pending`, `ready`,
-  `submitted`, retrying, and `past_due` provider gross exposure for the same
-  buyer / provider / token / pricing band
+- `total_unsettled_exposure_minor`: chargeable provider gross exposure for the
+  same buyer / provider / token / pricing band where the batch is not
+  `settled`, `uncollectible`, or `written_off`. This includes open usage,
+  `notice_pending`, `notice_delivery_failed`, `ready`, `submitted`,
+  `submitted_reconcile_required`, `failed_retryable`, `retrying`, and
+  `past_due`.
 
 JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
 conversions of one another.
@@ -318,7 +321,7 @@ Important batch fields:
 | `settlement_trigger` | `amount_threshold` for early threshold close, or `scheduled_close` for weekly/monthly close |
 | `settlement_threshold_minor` | Fixed market threshold for early settlement: JPY `10000` or USD `10000` minor units |
 | `threshold_reached_at` | Timestamp when the fixed threshold closed the batch, otherwise null |
-| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token / pricing band |
+| `total_unsettled_exposure_minor` | Chargeable provider gross exposure for the same buyer / provider / token / pricing band where status is not `settled`, `uncollectible`, or `written_off`; includes open, notice, ready, submitted, reconcile-required, retryable, retrying, and past-due states |
 | `expected_scheduled_debit_at` | Expected debit time for an open period before a batch exists |
 | `scheduled_debit_at` | Scheduled debit time after batch creation |
 | `not_before_attempt_at` | Earliest allowed debit attempt; this is the close-plus-3-day gate |
@@ -398,10 +401,10 @@ Siglume retries failed Micro / Nano settlement every 6 hours for up to 28
 automatic attempts. After that the batch remains `past_due` until operator
 requeue.
 
-New Micro / Nano usage for the same buyer / provider / token is paused while
-the total unsettled exposure is at or above the fixed threshold, and while a
-failed or past-due block remains. The provider API is not called for the
-rejected request, and the request is not charged.
+New Micro / Nano usage for the same buyer / provider / token / pricing band is
+paused while the total unsettled exposure is at or above the fixed threshold,
+and while a failed or past-due block remains. The provider API is not called for
+the rejected request, and the request is not charged.
 
 Public failure fields are sanitized. Show `failure_reason_code`,
 `failure_reason_label`, `failure_reason_help`, and `support_reference` to users
@@ -449,13 +452,12 @@ using stable idempotency keys and provider-side completion records.
 | --- | --- | --- | --- | --- |
 | `notice_delivery_failed` | Buyer debit is not yet allowed; provider revenue remains unsettled | Notice delivery can be retried or reviewed | Required if delivery keeps failing | Do not attempt your own debit notice or mark revenue settled. Show support context only. |
 | `submitted_reconcile_required` | A settlement submission exists but final on-chain outcome is not yet reconciled | Reconciliation may complete if a receipt is found | Required if reconciliation stalls | Do not retry payment yourself. Wait for `settled`, `failed_retryable`, or `past_due`. |
-| `past_due` | Buyer has an unresolved settlement block; provider sees past-due revenue | New Micro / Nano usage for the same buyer / plan / token is paused | Operator requeue or manual resolution only | Do not promise collection or provider payment. Ask the buyer to repair balance / allowance / BudgetVault / caps and reference `support_reference`. |
+| `past_due` | Buyer has an unresolved settlement block; provider sees past-due revenue | New Micro / Nano usage for the same buyer / provider / token / pricing band is paused | Operator requeue or manual resolution only | Do not promise collection or provider payment. Ask the buyer to repair balance / allowance / BudgetVault / caps and reference `support_reference`. |
 | `failed_chargeable` | Usage is still chargeable because provider work was accepted or completed | Included in later settlement attempts | Review if the provider disputes completion | Keep fulfillment idempotent and preserve evidence keyed by idempotency key. |
 
-Future platform versions may add explicit terminal states such as
-`closed_unpaid`, `uncollectible`, or `written_off`. Treat unknown terminal
-settlement states as not settled unless `status === "settled"` and
-`chain_receipt_id` is present.
+Terminal public states include `uncollectible` and `written_off` after operator
+review. Treat unknown terminal settlement states as not settled unless
+`status === "settled"` and `chain_receipt_id` is present.
 
 ## Operational Recipes
 

package/docs/payment-lifecycle.md

@@ -32,7 +32,7 @@ checkout open or agent/API payment starts
   -> usage accepted
   -> direct_payment.confirmed webhook
   -> classifier kind: metered_usage_accepted
-  -> merchant may fulfill as fulfilled_unsettled
+  -> merchant may fulfill as fulfilled_unsettled only after enabling Micro/Nano handling
   -> open period closes by amount threshold or schedule
   -> final notice window
   -> submitted / retrying / past_due if needed
@@ -41,10 +41,12 @@ checkout open or agent/API payment starts
   -> 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`.
+For Micro / Nano, `metered_usage_accepted` means the usage can be fulfilled only
+by an integration that has explicitly accepted SDRP delayed settlement and
+implemented fulfilled-but-unsettled state, settlement reconciliation, past-due
+handling, and terminal accounting. 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
 
@@ -52,7 +54,7 @@ on-chain and has a `chain_receipt_id`.
 | --- | --- | --- |
 | 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. |
+| `metered_usage_accepted` | Micro / Nano usage is accepted for integrations that have enabled delayed settlement handling. | It is not settled provider revenue, and Standard-only integrations should not fulfill it. |
 | `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. |
@@ -65,9 +67,10 @@ on-chain and has a `chain_receipt_id`.
   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.
+- For Micro / Nano, fulfill only after you have explicitly enabled delayed
+  settlement handling. Use a separate local state such as
+  `fulfilled_unsettled`, then 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.
 

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.18. Pricing can change by agreement or future product
+Payment as of SDK v0.4.20. 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.
 
@@ -156,9 +156,12 @@ confirmed payment turns into money in your settlement wallet.
 - While the same buyer / provider / token / pricing band has total unsettled
   exposure at or above the fixed threshold, new Micro/Nano usage is paused with the
   machine-readable error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not
-  called. Exposure includes open usage plus `notice_pending`, `ready`,
-  `submitted`, retrying, and `past_due` batches, and remains paused while
-  settlement failure or `past_due` is unresolved.
+  called. Exposure is chargeable provider gross where status is not `settled`,
+  `uncollectible`, or `written_off`; it includes open usage,
+  `notice_pending`, `notice_delivery_failed`, `ready`, `submitted`,
+  `submitted_reconcile_required`, `failed_retryable`, `retrying`, and
+  `past_due`. Usage remains paused while settlement failure or `past_due` is
+  unresolved.
 - Outstanding amounts remain attached to the failed settlement and are retried
   under this policy. They are not settled revenue, and Siglume does not advance,
   guarantee, or insure provider revenue before on-chain settlement succeeds.

package/docs/quickstart-10-minutes.md

@@ -1,176 +1,174 @@
-# 10-Minute First Test Payment
+# 10-Minute Product Integration
 
-This guide is the shortest supported path to one **Standard Payment** test
-through Siglume wallet Hosted Checkout. It is not a full production launch.
+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:
 
-## What the 10 minutes cover
+- `POST /payments/checkout/siglume/start`
+- `POST /payments/webhooks/siglume`
 
-You can count the 10 minutes only after the prerequisites below are already
-ready. The target outcome is:
+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.
 
-- one Standard-band order,
-- one Hosted Checkout session,
-- one signed `direct_payment.confirmed` webhook,
-- one idempotent local fulfillment decision.
+## 0. Readiness first
 
-This guide does **not** cover production monitoring, refunds, subscriptions,
-scheduled autopay, game entitlement recovery, or Micro / Nano accounting.
+Install the SDK in your product.
 
-## Prerequisites
+Node / Express:
 
-Before starting, confirm:
+```bash
+npm install @siglume/direct-request-payment
+```
 
-- 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+.
+Python / FastAPI:
 
-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.
+```bash
+pip install siglume-direct-request-payment
+```
 
-## 1. Install
+Set these environment variables in your app or `.env`:
 
-Runnable starter directories are available if you want a small server to edit:
+```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
+SIGLUME_WEBHOOK_SECRET=<webhook signing secret from setupCheckout/setup_checkout>
+```
 
-- [TypeScript Express starter](../examples/hosted-checkout-typescript)
-- [Python Flask starter](../examples/hosted-checkout-python)
+Then run the matching CLI:
 
-For an existing app, install the SDK directly:
+```bash
+# Node / Express
+npx siglume-check readiness
+
+# Python / FastAPI
+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, requires active
+billing, confirms the webhook subscription points to `SHOP_WEBHOOK_URL`, checks
+that `direct_payment.confirmed` is subscribed, verifies the local webhook secret
+against the subscription hint, creates one unpaid expiring Hosted Checkout probe
+session, and queues a signed webhook test delivery. No buyer is charged.
+
+For a CI local-config smoke test:
 
 ```bash
-npm install @siglume/direct-request-payment
+npx siglume-check readiness --no-api --json
 ```
 
-or:
+`--no-api` does not prove Hosted Checkout or webhook delivery. Before opening a
+human web checkout path, run readiness without `--no-api` and fix every FAIL
+item.
+
+## 1. Copy integration files into your product
+
+For Express:
 
 ```bash
-pip install siglume-direct-request-payment
+npx siglume-sdrp init express --target src/siglume
 ```
 
-## 2. Set environment variables
+For FastAPI:
 
 ```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
+siglume-sdrp init fastapi --target app/siglume
 ```
 
-Do not use a Developer Portal `cli_` API key. Merchant setup requires the
-merchant's Siglume bearer token.
+These commands copy framework-specific route files into your codebase. The
+generated files are intentionally small and are meant to be edited.
 
-## 3. Register merchant settings
+## 2. Mount the routes
 
-Run setup once from your server, CI, or integration machine:
+Express:
 
 ```ts
-import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
-
-const merchant = new DirectRequestPaymentMerchantClient({
-  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
-});
+import express from "express";
+import {
+  createSiglumeSdrpCheckoutRouter,
+  createSiglumeSdrpWebhookHandler,
+  type SiglumeSdrpRouterOptions,
+} from "./siglume/siglume-sdrp-routes.js";
+import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
 
-const setup = await merchant.setupCheckout({
+const siglumeOptions: SiglumeSdrpRouterOptions = {
   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);
-```
+  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),
+);
 
-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.
+app.use(express.json());
+app.use("/payments", createSiglumeSdrpCheckoutRouter(siglumeOptions));
+```
 
-## 4. Create a Standard checkout session
+FastAPI:
 
-For each order, create the order on your server first. Then create a Hosted
-Checkout session:
+```py
+from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
+from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
 
-```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);
+app.include_router(
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore(), allow_metered_payments=False),
+    prefix="/payments",
+)
 ```
 
-The browser must never choose the amount, currency, nonce, or return URL. The
-session is single-use and expires.
+## 3. Replace the order-store example
 
-## 5. Fulfill from the signed webhook
+Replace the example store with your product's order database. The adapter must:
 
-The browser return path is not the source of truth. Use the signed webhook and
-classify the confirmation:
+- 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`,
+- create or reuse one active checkout attempt with a stable nonce,
+- persist `challenge_hash`, `checkout_session_id`, and `checkout_url` before redirecting,
+- process webhook event ids durably in the same transaction as the order update,
+- mark Standard orders paid exactly once,
+- route unknown classifications to manual review.
 
-```ts
-import {
-  classifyDirectPaymentConfirmation,
-  verifyDirectRequestPaymentWebhook,
-} from "@siglume/direct-request-payment";
-
-const { event } = await verifyDirectRequestPaymentWebhook(
-  process.env.SIGLUME_WEBHOOK_SECRET!,
-  rawRequestBody,
-  siglumeSignatureHeader,
-);
+Do not calculate the amount from browser input.
 
-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);
-  }
-}
+The generated route defaults to Standard-only. If an order amount falls into
+Micro / Nano, checkout returns `METERED_INTEGRATION_REQUIRED` until you set
+`allow_metered_payments: true` / `allow_metered_payments=True` and implement
+fulfilled-but-unsettled state, settlement reconciliation, past-due handling, and
+terminal write-off handling.
+
+## 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\"}"
 ```
 
-For this 10-minute guide, keep the test order in the Standard band so the
-expected successful branch is `standard_settled`.
+Redirect the shopper to the returned `checkout_url`.
 
-## Done means
+## 5. Done means
 
-You are done with the quickstart when:
+Your product is integrated when:
 
-- the checkout session is created,
-- the buyer reaches the Siglume wallet hosted checkout page,
+- `npx siglume-check readiness` passes,
+- your product has mounted checkout and webhook routes,
+- your order database stores one active checkout attempt and `challenge_hash` for the order,
 - 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`.
+- `standard_settled` marks the order paid once,
+- duplicate webhook deliveries do not double-fulfill the order.
 
-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).
+For Micro / Nano revenue reconciliation, read
+[Payment lifecycle](./payment-lifecycle.md) and
+[Micro / Nano Statements and Notices](./metered-statements.md).