@siglume/direct-request-payment 0.4.16 → 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
@@ -24,9 +31,11 @@ This quickstart uses Standard-band example amounts. Micro Payment and Nano
 Payment are applied automatically by amount through the same Hosted Checkout or
 agent/API flow; you do not create a separate Micro/Nano object or manually
 select the amount band. Micro/Nano are settled on account-assigned weekly /
-monthly slots after the final notice and close-plus-3-day window (see
-[Pricing](./pricing.md#settlement-schedule)), and provider revenue remains
-unsettled until the later on-chain settlement succeeds. Completing merchant
+monthly slots, or earlier when the same buyer / provider / token / pricing band
+reaches the fixed market threshold, after the final notice and
+close-plus-3-day window (see [Pricing](./pricing.md#settlement-schedule)), and
+provider revenue remains unsettled until the later on-chain settlement succeeds.
+Completing merchant
 setup and the billing mandate means accepting this Micro/Nano delayed aggregated
 settlement model for low-price items. If your product requires immediate
 on-chain settlement, keep its price above the Micro/Nano thresholds instead of
@@ -42,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.
@@ -57,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
@@ -598,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
@@ -616,7 +636,8 @@ manual, including buyer past-due blocks and public failure fields.
   before new payments can be accepted.
 - `METERED_SETTLEMENT_PAST_DUE` (Micro / Nano only): a previous Micro / Nano
   metered settlement for this buyer is unresolved, so new Micro / Nano usage in
-  the same fee band is paused until it settles. Siglume retries settlement
+  the same buyer / provider / token / pricing band is paused until it settles.
+  Siglume retries settlement
   automatically every 6 hours, up to 28 attempts, before it requires manual
   resolution. The provider's Micro / Nano revenue stays unsettled until the
   settlement succeeds. This is a settlement-side state, not a per-request

package/docs/metered-statements.md

@@ -19,8 +19,8 @@ Siglume applies the settlement band from the amount.
 
 | Band | Cadence | Period close | First debit attempt | Revenue recognition |
 | --- | --- | --- | --- | --- |
-| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
-| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; can close early once the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; can close early once the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
 
 The schedule is platform-managed. Buyers and providers can see the resulting
 batch period and scheduled attempt times through the statement APIs, but cannot

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 2026-06-18. 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.
 
@@ -14,12 +14,13 @@ delayed aggregated settlement whenever they offer amounts in those bands.
 ## Settlement Currencies
 
 Siglume Direct Request Payment launches in the US and Japan, and both settlement
-currencies are first-class:
+currencies are first-class where enabled:
 
 - **JPY**, settled on-chain in **JPYC**
 - **USD**, settled on-chain in **USDC**
 
-A merchant settles in a single currency, chosen at onboarding. The settlement fee
+A merchant settles in a single currency, chosen at onboarding. Some accounts may
+require agreed USD/USDC terms before USD is enabled. The settlement fee
 percentage (the payment fee column below) is identical in both currencies. Only
 the flat amounts — the monthly base fee and the per-payment minimum fee — are
 quoted per currency.
@@ -34,8 +35,8 @@ charging.
 | Public one-time payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
 | JPY 501+ / USD 3.01+ | Standard Payment | Select one Standard plan: Launch, Starter, Growth, or Pro | Launch: JPY 0 / USD 0 monthly, 1.8%; Starter: JPY 980 / USD 6 monthly, 1.0%; Growth: JPY 2,980 / USD 18 monthly, 0.7%; Pro: JPY 9,800 / USD 60 monthly, 0.5%. Minimum JPY 30 / USD 0.20 per payment. | Settled on-chain immediately after the payment confirms |
-| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | JPY 2 / USD 0.01 per SDRP Tx | Aggregated and settled **weekly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
-| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | JPY 0.2 / USD 0.001 per SDRP Tx | Aggregated and settled **monthly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
+| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | JPY 2 / USD 0.01 per SDRP Tx | Aggregated and settled **weekly**, or earlier once the same buyer / provider / token / pricing band reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
+| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | JPY 0.2 / USD 0.001 per SDRP Tx | Aggregated and settled **monthly**, or earlier once the same buyer / provider / token / pricing band reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
 
 In this table, `Tx` means one accepted SDRP payment, not an on-chain settlement
 transaction. Micro / Nano settlement batches are aggregated on-chain after the
@@ -43,8 +44,8 @@ weekly or monthly close, or earlier when the fixed amount threshold is reached.
 
 Standard Payment settles per payment. Micro Payment and Nano Payment are
 aggregated and settled in account-assigned weekly / monthly slots, with early
-settlement when the same buyer/payee/token/period batch reaches JPY 10,000 or
-USD 100.00. See [Settlement schedule](#settlement-schedule) for how each band
+settlement when the same buyer / provider / token / pricing band reaches JPY
+10,000 or USD 100.00. See [Settlement schedule](#settlement-schedule) for how each band
 closes, when the pre-debit notice window elapses, when revenue becomes settled,
 and how rejected requests behave.
 
@@ -65,8 +66,9 @@ field-by-field meaning of `scheduled_debit_at`, `not_before_attempt_at`,
 `execution_status`, and `buyer_period_ref`, see
 [Micro / Nano Statements and Notices](./metered-statements.md).
 
-USD pricing is the JPY tier converted at roughly 160 JPY/USD and rounded to
-clean price points that keep the same 1:3:10 tier ratio.
+USD plan prices are set as separate public price points. The JPY 10,000 and USD
+100.00 Micro / Nano early-settlement thresholds are fixed market thresholds,
+not FX conversions of one another.
 
 If no paid plan is selected during merchant setup, the merchant account uses the
 Launch plan. A merchant billing mandate is still required before accepting
@@ -95,25 +97,25 @@ confirmed payment turns into money in your settlement wallet.
 | Band | Cadence | Period | You are paid |
 | --- | --- | --- | --- |
 | Standard Payment | Per payment | n/a | On-chain, immediately after each payment confirms |
-| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
-| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, provider, token, pricing band, and period |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, provider, token, pricing band, and period |
 
 ### Micro weekly settlement
 
 - **Closing period.** Micro-band payments accrue across one weekly period. The
   specific closing weekday and time are assigned as a fixed slot per account to
   spread settlement load.
-- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
-  10,000 or USD 100.00 before the weekly close, Siglume can close that batch
-  early and start the same final-notice and settlement flow. JPY 10,000 and USD
-  100.00 are market-specific fixed thresholds, not FX conversions of one
-  another.
+- **Early threshold settlement.** If the same buyer / provider / token /
+  pricing band reaches JPY 10,000 or USD 100.00 before the weekly close,
+  Siglume can close that batch early and start the same final-notice and
+  settlement flow. JPY 10,000 and USD 100.00 are market-specific fixed
+  thresholds, not FX conversions of one another.
 - **Timezone.** Period boundaries are evaluated in the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
 - **Settlement.** After the week closes or the early threshold is reached,
   Siglume aggregates the Micro
-  payments — grouped per buyer, payee, token, and period — into on-chain
+  payments — grouped per buyer, provider, token, pricing band, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
@@ -125,17 +127,17 @@ confirmed payment turns into money in your settlement wallet.
 - **Closing period.** Nano-band payments accrue across one monthly period. The
   specific closing day and time are assigned as a fixed slot per account to
   spread settlement load.
-- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
-  10,000 or USD 100.00 before the monthly close, Siglume can close that batch
-  early and start the same final-notice and settlement flow. JPY 10,000 and USD
-  100.00 are market-specific fixed thresholds, not FX conversions of one
-  another.
+- **Early threshold settlement.** If the same buyer / provider / token /
+  pricing band reaches JPY 10,000 or USD 100.00 before the monthly close,
+  Siglume can close that batch early and start the same final-notice and
+  settlement flow. JPY 10,000 and USD 100.00 are market-specific fixed
+  thresholds, not FX conversions of one another.
 - **Timezone.** As with Micro, period boundaries use the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
 - **Settlement.** After the month closes or the early threshold is reached,
   Siglume aggregates the Nano
-  payments — grouped per buyer, payee, token, and period — into on-chain
+  payments — grouped per buyer, provider, token, pricing band, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
@@ -190,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,
@@ -130,7 +144,9 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
 app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
   // Log the detail server-side; never return raw error messages to the client —
   // a payment error can otherwise leak internal API details or configuration.
-  console.error("checkout error:", error);
+  console.error("checkout error:", {
+    name: error instanceof Error ? error.name : "Error",
+  });
   res.status(500).json({ error: "internal_error" });
 });
 

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.