@siglume/direct-request-payment 0.4.19 → 0.4.22

package/docs/api-reference.md

@@ -48,6 +48,8 @@ Standard can be marked paid only after settled per-payment finality, while Micro
 | `SIGLUME_MERCHANT_AUTH_TOKEN` | merchant setup helper | merchant Siglume bearer token for self-service setup |
 | `SIGLUME_AUTH_TOKEN` | user-authenticated helper | buyer Siglume bearer token for payment / buyer statements, or provider Siglume bearer token for provider statements |
 | `SIGLUME_API_BASE` | optional | API base URL override; defaults to `https://siglume.com/v1` |
+| `SIGLUME_ENV` | optional | Set to `sandbox` to default clients and readiness to the local sandbox API |
+| `SIGLUME_SANDBOX_API_BASE` | optional | Sandbox API override; defaults to `http://127.0.0.1:8787/v1` when `SIGLUME_ENV=sandbox` |
 | `SIGLUME_WEBHOOK_SECRET` | merchant server | webhook signing secret returned as `whsec_...` |
 
 Do not use a Developer Portal `cli_` API key as either auth token. Merchant
@@ -356,7 +358,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 +375,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 +540,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 +1052,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 +1079,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 +1195,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`
 
@@ -1170,6 +1216,7 @@ Both packages export these importable constants:
 | Constant | Value |
 | --- | --- |
 | `DEFAULT_SIGLUME_API_BASE` | `https://siglume.com/v1` |
+| `DEFAULT_SIGLUME_SANDBOX_API_BASE` | `http://127.0.0.1:8787/v1` |
 | `DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME` | `siglume-external-402-v1` |
 | `DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME` | `siglume-external-402-recurring-v1` |
 | `DIRECT_REQUEST_PAYMENT_MODE` | `external_402` |

package/docs/merchant-quickstart.md

@@ -459,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 });
@@ -531,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.19. Pricing can change by agreement or future product
+Payment as of SDK v0.4.22. 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

@@ -11,7 +11,43 @@ 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
+## 0. Run the sandbox first
+
+Do this before touching live Siglume credentials. The local sandbox is a tiny
+Siglume-compatible API server bundled with the SDK. It creates fake checkout
+sessions, signs webhooks with your sandbox secret, records delivery status, and
+never charges a wallet.
+
+In one terminal, point it at your product's local webhook route:
+
+```bash
+npx siglume-sdrp sandbox \
+  --origin http://localhost:3000 \
+  --webhook-url http://localhost:3000/payments/webhooks/siglume
+```
+
+Use the values it prints in your product `.env`:
+
+```bash
+SIGLUME_ENV=sandbox
+SIGLUME_API_BASE=http://127.0.0.1:8787/v1
+SIGLUME_MERCHANT_AUTH_TOKEN=sandbox_merchant_token
+SIGLUME_DIRECT_PAYMENT_MERCHANT=sandbox_merchant
+SHOP_PUBLIC_ORIGIN=http://localhost:3000
+SHOP_WEBHOOK_URL=http://localhost:3000/payments/webhooks/siglume
+SIGLUME_WEBHOOK_SECRET=whsec_sandbox_local
+```
+
+Then run:
+
+```bash
+npx siglume-check readiness --sandbox
+```
+
+The sandbox readiness check proves your local server can receive a signed
+`direct_payment.confirmed` delivery before you use live credentials.
+
+## 1. Live readiness
 
 Install the SDK in your product.
 
@@ -34,29 +70,37 @@ 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>
 ```
 
-Then run:
+Then run the matching CLI:
 
 ```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, 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.
+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 CI or a preflight script:
+For a CI local-config smoke test:
 
 ```bash
-npx siglume-check readiness --json
+npx siglume-check readiness --no-api --json
 ```
 
-If this command fails, fix the reported item first. Do not build a human web
-checkout path until readiness passes.
+`--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
+## 2. Copy integration files into your product
 
 For Express:
 
@@ -73,21 +117,36 @@ 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
+## 3. Mount the routes
 
 Express:
 
 ```ts
-import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import express from "express";
+import {
+  createSiglumeSdrpCheckoutRouter,
+  createSiglumeSdrpWebhookHandler,
+  type SiglumeSdrpRouterOptions,
+} from "./siglume/siglume-sdrp-routes.js";
 import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
 
-app.use("/payments", createSiglumeSdrpRouter({
+const siglumeOptions: SiglumeSdrpRouterOptions = {
   merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
   merchant_auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
   webhook_secret: process.env.SIGLUME_WEBHOOK_SECRET!,
   shop_public_origin: process.env.SHOP_PUBLIC_ORIGIN!,
   order_store: siglumeOrderStore,
-}));
+  allow_metered_payments: false,
+};
+
+app.post(
+  "/payments/webhooks/siglume",
+  express.raw({ type: "application/json" }),
+  createSiglumeSdrpWebhookHandler(siglumeOptions),
+);
+
+app.use(express.json());
+app.use("/payments", createSiglumeSdrpCheckoutRouter(siglumeOptions));
 ```
 
 FastAPI:
@@ -97,27 +156,77 @@ 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()),
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore(), allow_metered_payments=False),
     prefix="/payments",
 )
 ```
 
-## 3. Replace the order-store example
+## 4. Adapter responsibilities
 
 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,
+- 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,
-- 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
+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.
+
+## 5. Use a real database adapter
+
+The copied files include durable database adapters. Use these before opening
+checkout to users; the `*.example.*` stores are only for reading the interface.
+
+Express:
+
+```ts
+import {
+  createPrismaSiglumeOrderStore,
+  createTypeOrmSiglumeOrderStore,
+  createSequelizeSiglumeOrderStore,
+  createDrizzleSiglumeOrderStore,
+} from "./siglume/siglume-order-store.sql.js";
+
+const order_store = createPrismaSiglumeOrderStore(prisma, {
+  dialect: "postgres",
+  orders_table: "orders",
+  order_id_column: "id",
+  amount_minor_column: "amount_minor",
+  currency_column: "currency",
+});
+```
+
+FastAPI:
+
+```py
+from sqlalchemy.orm import sessionmaker
+from .siglume.siglume_order_store_sqlalchemy import (
+    SQLAlchemySiglumeOrderStore,
+    create_sqlalchemy_engine,
+    create_sqlalchemy_siglume_schema,
+)
+
+engine = create_sqlalchemy_engine(os.environ["DATABASE_URL"])
+create_sqlalchemy_siglume_schema(engine)
+SessionLocal = sessionmaker(engine, future=True)
+order_store = SQLAlchemySiglumeOrderStore(SessionLocal)
+```
+
+The adapters persist one checkout attempt per order, reuse the checkout URL on
+retries, record webhook event ids only after the order update/review write
+succeeds, and keep duplicate deliveries from double-fulfilling an order.
+
+## 6. Start checkout from your frontend
 
 Call your own server route:
 
@@ -129,16 +238,17 @@ curl -X POST https://api.your-product.example/payments/checkout/siglume/start \
 
 Redirect the shopper to the returned `checkout_url`.
 
-## 5. Done means
+## 7. Done means
 
 Your product is integrated when:
 
-- `npx siglume-check readiness` passes,
+- `npx siglume-check readiness --sandbox` passes against your local product,
+- `npx siglume-check readiness` passes against live Siglume credentials,
 - your product has mounted checkout and webhook routes,
-- your order database stores `challenge_hash` for the order,
+- your order database uses the SQL/ORM adapter or an equivalent transactional store,
 - 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.
+- a failed webhook handler is retried and duplicate webhook deliveries do not double-fulfill the order.
 
 For Micro / Nano revenue reconciliation, read
 [Payment lifecycle](./payment-lifecycle.md) and

package/docs/sandbox.md

@@ -0,0 +1,60 @@
+# SDRP Sandbox
+
+Use the SDK sandbox before live Siglume credentials. It is a local
+Siglume-compatible API server for product integration testing. It creates fake
+checkout sessions, signs `direct_payment.confirmed` webhooks, records delivery
+status, and never charges a wallet.
+
+Start your product locally first, then run:
+
+```bash
+npx siglume-sdrp sandbox \
+  --origin http://localhost:3000 \
+  --webhook-url http://localhost:3000/payments/webhooks/siglume
+```
+
+Set the printed environment variables in your product:
+
+```bash
+SIGLUME_ENV=sandbox
+SIGLUME_API_BASE=http://127.0.0.1:8787/v1
+SIGLUME_MERCHANT_AUTH_TOKEN=sandbox_merchant_token
+SIGLUME_DIRECT_PAYMENT_MERCHANT=sandbox_merchant
+SHOP_PUBLIC_ORIGIN=http://localhost:3000
+SHOP_WEBHOOK_URL=http://localhost:3000/payments/webhooks/siglume
+SIGLUME_WEBHOOK_SECRET=whsec_sandbox_local
+```
+
+Then verify the integration:
+
+```bash
+npx siglume-check readiness --sandbox
+```
+
+Create a checkout through your own product route:
+
+```bash
+curl -X POST http://localhost:3000/payments/checkout/siglume/start \
+  -H "content-type: application/json" \
+  -d "{\"order_id\":\"order_123\"}"
+```
+
+Open the returned `checkout_url` and click the sandbox confirm button. Your
+product should receive a signed webhook and mark the Standard order paid once.
+
+Sandbox Micro / Nano behavior follows the same public classifications:
+
+- JPY 501+ / USD 3.01+ returns `standard_settled`.
+- JPY 50-500 / USD 0.31-3.00 returns `metered_usage_accepted` with weekly Micro settlement fields.
+- JPY 1-49 / USD 0.01-0.30 returns `metered_usage_accepted` with monthly Nano settlement fields.
+
+The generated route defaults to Standard-only, so Micro / Nano checkout returns
+`METERED_INTEGRATION_REQUIRED` until you explicitly enable metered handling.
+
+Before live launch:
+
+- run `npx siglume-check readiness --sandbox` against the local product,
+- run the same checkout path and confirm a sandbox webhook,
+- switch to live `SIGLUME_MERCHANT_AUTH_TOKEN`, `SIGLUME_DIRECT_PAYMENT_MERCHANT`, `SHOP_PUBLIC_ORIGIN`, `SHOP_WEBHOOK_URL`, and `SIGLUME_WEBHOOK_SECRET`,
+- run `npx siglume-check readiness` without `--sandbox`,
+- confirm the live webhook subscription and signing secret are for the live product URL.