@siglume/direct-request-payment 0.4.4 → 0.4.6

package/docs/api-reference.md

@@ -26,9 +26,11 @@ card — and the merchant SDK never authenticates the buyer.
   runs are bounded by Siglume's approval gates / spending budgets (per-run /
   daily / monthly auto-pay budgets, or Works approval).
 
-In both systems the merchant fulfills on the same signed
-`direct_payment.confirmed` webhook. Hosted Checkout adds no new money movement
-and no new webhook.
+In both systems the merchant handles the same signed `direct_payment.confirmed`
+webhook. Hosted Checkout adds no new money movement and no new webhook. Inspect
+`pricing_band`, `finality`, and `settlement_status`: Standard can be marked paid
+only after settled per-payment finality, while Micro / Nano usage is accepted
+before the later aggregated settlement.
 
 ## Environment Variables
 
@@ -36,7 +38,7 @@ and no new webhook.
 | --- | --- | --- |
 | `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` | merchant server | HMAC secret for order challenges |
 | `SIGLUME_MERCHANT_AUTH_TOKEN` | merchant setup helper | merchant Siglume bearer token for self-service setup |
-| `SIGLUME_AUTH_TOKEN` | buyer payment helper | buyer Siglume bearer token for API calls |
+| `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_WEBHOOK_SECRET` | merchant server | webhook signing secret returned as `whsec_...` |
 
@@ -364,8 +366,9 @@ webhook-origin auto-allow apply.
 Beta / server rollout: Hosted Checkout is rolling out account by account. If the
 server endpoint is not enabled for the merchant yet, the SDK raises
 `HostedCheckoutNotAvailableError` (TS + Py) rather than leaking a raw rollout
-404/409. Fulfillment must still key off the signed `direct_payment.confirmed`
-webhook.
+404/409. Payment handling must still key off the signed
+`direct_payment.confirmed` webhook and its settlement machine fields, not the
+event name alone.
 
 Creates a single-use, expiring Hosted Checkout session for a human web shopper
 and returns the URL to redirect them to. Requires the merchant's Siglume bearer
@@ -447,11 +450,24 @@ Returns a `HostedCheckoutSession` status object with:
   `failed`
 - `challenge_hash`
 - `requirement_id` (nullable until a requirement is created)
+- `pricing_band` (nullable until a requirement is created): `standard`,
+  `micro`, or `nano`
+- `settlement_cadence` (nullable until a requirement is created):
+  `per_payment`, `weekly`, or `monthly`
+- `finality` (nullable until a requirement is created), for example
+  `per_payment_onchain` or `aggregated_onchain_settlement`
+- `protocol_fee_minor` (nullable; decimal string for Micro / Nano)
+- `settlement_status` (nullable until a requirement is created), for example
+  `pending_payment`, `provisional`, `settled`, or `pending_settlement`
+- `chain_receipt_id` (nullable)
 - `success_url`
 - `cancel_url`
 - `expires_at` (nullable)
 - `authenticated_at` (nullable; set when the shopper signs into Siglume)
-- `paid_at` (nullable; set when the payment confirms)
+- `paid_at` (nullable; set when Hosted Checkout has accepted the wallet
+  payment flow. For Micro / Nano, this is not the same as final provider
+  settlement; use `pricing_band`, `finality`, `settlement_status`, and the
+  statement APIs.)
 - `cancelled_at` (nullable; set when the shopper cancels)
 - `created_at` (nullable)
 - `metadata_jsonb`
@@ -505,8 +521,10 @@ or rotation.
 ## `DirectRequestPaymentClient`
 
 Thin wrapper around the current Siglume Direct Request Payment HTTP contract.
-Use it with the authenticated buyer's Siglume bearer token. Developer Portal
-`cli_` API keys are not accepted by these buyer-authenticated routes.
+Use it with the authenticated Siglume user bearer token for the route you call:
+buyer tokens for buyer payment and buyer statement routes, provider / merchant
+tokens for provider statement routes. Developer Portal `cli_` API keys are not
+accepted by these user-authenticated routes.
 
 This client creates SDRP Standard Payment requirements for external merchant
 checkout flows. Micro Payment and Nano Payment are applied automatically by
@@ -522,14 +540,14 @@ statement API amount fields (`protocol_fee_minor`, `gross_buyer_debit_minor`,
 
 ```ts
 const siglume = new DirectRequestPaymentClient({
-  auth_token: buyerSiglumeBearerToken,
+  auth_token: buyerOrProviderSiglumeBearerToken,
   base_url: "https://siglume.com/v1",
 });
 ```
 
 ```py
 siglume = DirectRequestPaymentClient(
-    auth_token=buyer_siglume_bearer_token,
+    auth_token=buyer_or_provider_siglume_bearer_token,
     base_url="https://siglume.com/v1",
 )
 ```
@@ -556,6 +574,20 @@ Input:
 - `allowance_amount_minor`: optional positive integer
 - `metadata`: optional JSON object
 
+There is no public `idempotency_key` field on this requirement-create request.
+For one-time external checkout, idempotency is the merchant-signed challenge
+nonce: derive `nonce` from a durable order payment attempt, store the returned
+`challenge_hash`, and use `request_hash_v2` when you need a canonical machine
+hash for the same payment request. Do not retry the same order by minting a new
+nonce unless you intentionally want a new payment attempt.
+
+For Siglume Marketplace paid capability execution / MCP tools, `idempotency_key`
+is a separate top-level JSON field on the execution payload or tool arguments.
+Use one stable key per logical paid operation, up to 128 characters, and do not
+reuse it for a different payload. A retry with the same key returns or reconciles
+the first recorded outcome instead of creating another chargeable usage event.
+The HTTP `Idempotency-Key` header is not the public requirement-create contract.
+
 The returned requirement includes both compatibility and machine-readable
 settlement fields:
 
@@ -723,8 +755,9 @@ SDK methods:
 - TypeScript: `listBuyerUsageEvents(...)`, `listBuyerSettlementBatches(...)`
 - Python: `list_buyer_usage_events(...)`, `list_buyer_settlement_batches(...)`
 
-Each accepts `plan_type`, `token_symbol`, `status`, and `limit`, and returns
-`{items, next_cursor}`.
+Each accepts `plan_type`, `token_symbol`, `status`, `limit`, and `cursor`, and
+returns `{items, next_cursor}`. When `next_cursor` is non-null, pass it back as
+`cursor` to fetch the next page.
 
 Buyer-facing amount names are centered on the debit:
 
@@ -783,9 +816,10 @@ SDK methods:
   `list_provider_settlement_batches(...)`, `get_provider_settlement_batch(...)`
 
 Provider list methods accept `plan_type`, `token_symbol`, `status`,
-`listing_id`, `capability_key`, and `limit`. Detail accepts
+`listing_id`, `capability_key`, `limit`, and `cursor`. Detail accepts
 `settlement_batch_id`, plus optional `listing_id` and `capability_key`. List
-methods return `{items, next_cursor}`.
+methods return `{items, next_cursor}`. When `next_cursor` is non-null, pass it
+back as `cursor` to fetch the next page.
 
 Provider-facing amount names:
 
@@ -843,6 +877,13 @@ metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end
 ```
 
 The CSV uses `buyer_period_ref`, not raw buyer account identifiers.
+The CSV keeps the `rounding_delta_minor` column for schema stability, but usage
+rows report `0`; the authoritative rounding adjustment is the settlement batch
+field `rounding_delta_minor`.
+
+Micro / Nano amount fields are decimal minor-unit strings. In JavaScript, do
+not aggregate them with `number`; parse them with a decimal library. In Python,
+use `Decimal` for accounting and reconciliation.
 
 ## Payload Builders
 
@@ -919,11 +960,26 @@ argument is positional in both languages.
 
 For `direct_payment.confirmed`, inspect `event.data.pricing_band`,
 `event.data.settlement_cadence`, `event.data.finality`,
-`event.data.protocol_fee_minor`, and `event.data.settlement_status` instead of
-inferring whether the event means per-payment on-chain confirmation or an
-aggregated Micro / Nano settlement confirmation. `event.data.request_hash_v2`
-is present on new challenge-backed requirements; keep accepting
-`event.data.request_hash` for historical payloads.
+`event.data.protocol_fee_minor`, `event.data.settlement_status`,
+`event.data.settlement_batch_id`, `event.data.chain_receipt_id`,
+`event.data.usage_event_digest`, and `event.data.settled_at` instead of
+inferring whether the event means per-payment on-chain confirmation, Micro /
+Nano accepted-but-unsettled usage, or an aggregated Micro / Nano settlement
+confirmation. `event.data.request_hash_v2` is present on new challenge-backed
+requirements; keep accepting `event.data.request_hash` for historical payloads.
+
+Recommended branch:
+
+- `mode === "metered_settlement_batch"`: no order `challenge_hash` is expected.
+  Reconcile the batch only when `settlement_status === "settled"`.
+- `pricing_band === "standard"`, `finality === "per_payment_onchain"`, and
+  `settlement_status === "settled"`: mark the mapped order paid once.
+- `pricing_band === "micro" || pricing_band === "nano"`: treat the usage as
+  accepted but unsettled. Fulfill only if your business accepts delayed
+  settlement risk, and reconcile final revenue from statement APIs / settlement
+  batches.
+- Missing machine fields: do not mark paid from the event type alone; fetch the
+  requirement or route the event to manual review.
 
 ### `verifyDirectRequestPaymentWebhook(secret, body, signature_header, options)` / `verify_direct_request_payment_webhook(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
 
@@ -941,7 +997,8 @@ const { event, verification } = await verifyDirectRequestPaymentWebhook(
   rawRequestBody,                       // the RAW body bytes/string, not re-stringified JSON
   request.headers["siglume-signature"],
 );
-// event.type === "direct_payment.confirmed" -> fulfill once; verification.timestamp is the signed time
+// event.type === "direct_payment.confirmed"; inspect pricing_band/finality/
+// settlement_status before marking an order paid.
 ```
 
 ```py
@@ -953,7 +1010,8 @@ verified = verify_direct_request_payment_webhook(
     siglume_signature_header,
 )
 event = verified["event"]
-# event["type"] == "direct_payment.confirmed" -> fulfill once
+# event["type"] == "direct_payment.confirmed"; inspect pricing_band/finality/
+# settlement_status before marking an order paid.
 ```
 
 ## Exported Constants

package/docs/merchant-quickstart.md

@@ -396,16 +396,63 @@ const { event } = await verifyDirectRequestPaymentWebhook(
   siglumeSignatureHeader,
 );
 
-if (event.type === "direct_payment.confirmed") {
-  const data = event.data;
+if (event.type !== "direct_payment.confirmed") {
+  return new Response(null, { status: 204 });
+}
+
+const data = event.data;
+
+if (data.mode === "metered_settlement_batch") {
+  // Aggregated Micro/Nano settlement events do not carry an order challenge.
+  if (data.settlement_status === "settled") {
+    await orders.reconcileMeteredSettlementOnce({
+      settlement_batch_id: String(data.settlement_batch_id ?? ""),
+      chain_receipt_id: String(data.chain_receipt_id ?? ""),
+      usage_event_digest: String(data.usage_event_digest ?? ""),
+      settled_at: String(data.settled_at ?? ""),
+    });
+  }
+  return new Response(null, { status: 204 });
+}
+
+if (
+  data.pricing_band === "standard" &&
+  data.finality === "per_payment_onchain" &&
+  data.settlement_status === "settled"
+) {
   const order = await orders.findByChallengeHash(String(data.challenge_hash ?? ""));
   if (!order) {
-    throw new Error("Unknown Siglume challenge hash");
+    await orders.flagForPaymentStateReview({
+      reason: "unknown_challenge_hash",
+      requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+    });
+    return new Response(null, { status: 204 });
   }
   await orders.markPaidOnce(order.id, {
     siglume_requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+    chain_receipt_id: String(data.chain_receipt_id ?? ""),
   });
+  return new Response(null, { status: 204 });
+}
+
+if (data.pricing_band === "micro" || data.pricing_band === "nano") {
+  const order = await orders.findByChallengeHash(String(data.challenge_hash ?? ""));
+  if (order) {
+    await orders.markFulfilledButUnsettledOnce(order.id, {
+      siglume_requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+      pricing_band: String(data.pricing_band),
+    });
+  }
+  return new Response(null, { status: 204 });
 }
+
+// Missing or unknown machine fields: do not mark the order paid from the event
+// name alone. Fetch the requirement or route it to manual review.
+await orders.flagForPaymentStateReview({
+  reason: "missing_settlement_machine_fields",
+  requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+});
+return new Response(null, { status: 204 });
 ```
 
 Python:
@@ -421,23 +468,68 @@ verified = verify_direct_request_payment_webhook(
     siglume_signature_header,
 )
 
-if verified["event"]["type"] == "direct_payment.confirmed":
-    data = verified["event"]["data"]
+if verified["event"]["type"] != "direct_payment.confirmed":
+    return "", 204
+
+data = verified["event"]["data"]
+
+if data.get("mode") == "metered_settlement_batch":
+    # Aggregated Micro/Nano settlement events do not carry an order challenge.
+    if data.get("settlement_status") == "settled":
+        orders.reconcile_metered_settlement_once(
+            settlement_batch_id=str(data.get("settlement_batch_id") or ""),
+            chain_receipt_id=str(data.get("chain_receipt_id") or ""),
+            usage_event_digest=str(data.get("usage_event_digest") or ""),
+            settled_at=str(data.get("settled_at") or ""),
+        )
+    return "", 204
+
+if (
+    data.get("pricing_band") == "standard"
+    and data.get("finality") == "per_payment_onchain"
+    and data.get("settlement_status") == "settled"
+):
     order = orders.find_by_challenge_hash(str(data.get("challenge_hash") or ""))
     if not order:
-        raise RuntimeError("Unknown Siglume challenge hash")
+        orders.flag_for_payment_state_review(
+            reason="unknown_challenge_hash",
+            requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+        )
+        return "", 204
     orders.mark_paid_once(
         order["id"],
         siglume_requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+        chain_receipt_id=str(data.get("chain_receipt_id") or ""),
     )
+    return "", 204
+
+if data.get("pricing_band") in ("micro", "nano"):
+    order = orders.find_by_challenge_hash(str(data.get("challenge_hash") or ""))
+    if order:
+        orders.mark_fulfilled_but_unsettled_once(
+            order["id"],
+            siglume_requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+            pricing_band=str(data.get("pricing_band") or ""),
+        )
+    return "", 204
+
+# Missing or unknown machine fields: do not mark the order paid from the event
+# name alone. Fetch the requirement or route it to manual review.
+orders.flag_for_payment_state_review(
+    reason="missing_settlement_machine_fields",
+    requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+)
+return "", 204
 ```
 
 ## Reconcile Micro / Nano Statements
 
-Standard Payment can be fulfilled from the verified
-`direct_payment.confirmed` webhook. Micro Payment and Nano Payment are different:
-they are automatic amount bands and are settled later in aggregated on-chain
-batches. Use the statement APIs to answer:
+Standard Payment can be marked paid from the verified `direct_payment.confirmed`
+webhook only when `pricing_band === "standard"`,
+`finality === "per_payment_onchain"`, and `settlement_status === "settled"`.
+Micro Payment and Nano Payment are different: they are automatic amount bands
+and are settled later in aggregated on-chain batches. Use the statement APIs to
+answer:
 
 - how much Micro / Nano usage is open this week or month,
 - when the buyer's assigned period closes,

package/docs/metered-statements.md

@@ -106,12 +106,24 @@ buyer_debit_minor = ceil(gross_buyer_debit_minor)
 rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
 ```
 
+For low-count Nano batches, the ceiling can make the effective buyer burden per
+usage higher than the headline "USD 0.001 / usage" protocol fee. The protocol
+fee remains the decimal statement amount; the extra integer-minor-unit
+adjustment is recorded as `rounding_delta_minor` on the settlement batch. Each
+settlement batch can add a positive rounding adjustment of less than 1 token
+minor unit; if a buyer uses many providers / payees in one period, that
+adjustment can occur once per settlement batch.
+
 `rounding_delta_minor` belongs to the buyer debit and Siglume's rounding
 adjustment accounting for that batch. It is not provider revenue. Provider
 reports should use `provider_receivable_minor`,
 `settled_provider_receivable_minor`, `unsettled_provider_receivable_minor`, and
 `past_due_provider_receivable_minor`.
 
+Micro / Nano amount fields are decimal minor-unit strings. JavaScript
+integrations should aggregate them with a decimal library, not `number`. Python
+integrations should use `Decimal` for accounting.
+
 ### Usage Events
 
 ```text
@@ -123,6 +135,7 @@ Query parameters:
 - `plan_type`: `micro` or `nano`
 - `token_symbol`: `JPYC` or `USDC`
 - `status`: for example `pending_settlement`, `settled`, `failed_chargeable`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 500
 
 SDK methods: `listBuyerUsageEvents(...)` / `list_buyer_usage_events(...)`.
@@ -148,6 +161,7 @@ Query parameters:
 - `token_symbol`: `JPYC` or `USDC`
 - `status`: `notice_pending`, `ready`, `submitted`, `settled`, `failed`,
   `past_due`, or `notice_delivery_failed`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 200
 
 SDK methods: `listBuyerSettlementBatches(...)` /
@@ -233,6 +247,7 @@ Query parameters:
 - `status`
 - `listing_id`
 - `capability_key`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 500
 
 SDK methods: `listProviderUsageEvents(...)` /
@@ -266,6 +281,7 @@ Query parameters for the list endpoint:
 - `status`
 - `listing_id`
 - `capability_key`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 200
 
 The detail endpoint also accepts `listing_id` and `capability_key`.
@@ -317,6 +333,10 @@ metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end
 ```
 
 The CSV uses `buyer_period_ref`, not `buyer_user_id`.
+`rounding_delta_minor` is present for a stable usage-event schema, but per-row
+values are `0`. The authoritative rounding adjustment is the settlement batch
+`rounding_delta_minor`; do not allocate that adjustment to provider revenue
+from individual CSV rows.
 
 ## Notifications
 
@@ -360,9 +380,20 @@ or support staff. Do not depend on raw platform failure messages.
 
 ## Usage Accounting by Result
 
-Use idempotency keys for every paid operation. Siglume records one chargeable
-usage event per idempotency key within the same buyer / listing / operation
-scope.
+Use idempotency keys for every paid operation. For Siglume Marketplace paid
+capability execution and MCP tools, pass `idempotency_key` as a top-level JSON
+field on the execution payload / tool arguments. Do not rely on an HTTP
+`Idempotency-Key` header for this public paid-operation contract; Siglume may
+also use that header internally when it calls providers.
+
+The key should be a stable retry key for one logical paid operation, such as
+`order:<order_id>:attempt:<n>` or `<provider_event_id>`, and should not be reused
+for a different payload. The current public contract stores up to 128
+characters. Siglume records one chargeable usage event per idempotency key within
+the same buyer / listing / capability scope; a retry with the same key returns or
+reconciles the first recorded outcome rather than creating another chargeable
+event. If a provider times out after doing work, retry or reconcile with the
+same key before repeating side effects.
 
 | Case | Provider API executed? | Usage counted? | Integration rule |
 | --- | --- | --- | --- |
@@ -392,6 +423,11 @@ using stable idempotency keys and provider-side completion records.
 | `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`. |
 | `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.
+
 ## Operational Recipes
 
 ### "How much did we use this week or month?"
@@ -424,7 +460,9 @@ separate from settled revenue.
 ## Go-Live Checklist
 
 - Your order fulfillment is idempotent by order id and requirement id.
-- Standard Payment fulfillment still uses verified `direct_payment.confirmed`.
+- Standard Payment fulfillment still uses verified `direct_payment.confirmed`
+  only when `pricing_band`, `finality`, and `settlement_status` show settled
+  per-payment finality.
 - Micro / Nano accounting uses statement APIs or CSV, not only webhooks.
 - Your dashboard separates settled, unsettled, and past-due provider amounts.
 - Your support UI shows sanitized failure fields and `support_reference`.

package/docs/pricing.md

@@ -40,6 +40,11 @@ The current public API chooses the band from `amount_minor`; it does not expose
 `settlement_mode: "immediate"` or `require_immediate_finality: true`. If a
 merchant needs immediate on-chain finality, the payment amount must be in the
 Standard band or the merchant must have a separately agreed platform contract.
+For public one-time Direct Payment / Hosted Checkout, `amount_minor` is a
+positive integer in minor currency units. That means the smallest public
+one-time checkout amount is JPY 1 or USD 0.01. Nano Payment on this public path
+therefore means JPY 1-49 or USD 0.01-0.30. Sub-minor Nano protocol fees are
+settlement-accounting amounts, not externally submitted one-time item prices.
 
 For the operational statement APIs, CSV export, buyer past-due blocks, and the
 field-by-field meaning of `scheduled_debit_at`, `not_before_attempt_at`,
@@ -179,6 +184,16 @@ revenue. Providers should reconcile their revenue with
 `unsettled_provider_receivable_minor`, and
 `past_due_provider_receivable_minor`, not with `buyer_debit_minor`.
 
+For low-count Nano batches, the integer ceiling can make the effective buyer
+burden per usage higher than the headline USD 0.001 / usage protocol fee. The
+decimal protocol fee remains visible as `protocol_fee_minor`; the difference
+created by integer-token settlement is visible as `rounding_delta_minor` on the
+batch. Each settlement batch can add a positive rounding adjustment of less than
+1 token minor unit. If a buyer uses many providers / payees in one period, that
+adjustment can occur once per settlement batch. JavaScript integrations should
+not sum Micro / Nano minor amounts with `number`; use a decimal library. Python
+integrations should use `Decimal`.
+
 ## Statement APIs and Notices
 
 Micro and Nano require operational reconciliation after usage is accepted. The

package/docs/security.md

@@ -119,6 +119,19 @@ Fulfill exactly once per order. Store at least:
 Duplicate webhook deliveries and manual redelivery can occur. A duplicate
 webhook with the same requirement id must not ship the order twice.
 
+The public requirement-create API does not accept an `idempotency_key` field.
+For one-time external checkout, the durable idempotency material is the
+merchant-authored challenge nonce plus the returned `challenge_hash` /
+`request_hash_v2`. Reuse the same order-attempt nonce when reconciling a retry;
+mint a new nonce only for a new payment attempt.
+
+For Micro / Nano paid capability execution through Siglume Marketplace or MCP
+tools, use the top-level JSON field `idempotency_key` on the execution payload /
+tool arguments. Treat it as a stable retry key for one logical paid operation
+and do not reuse it for a different payload. The HTTP `Idempotency-Key` header is
+not the public contract for this requirement-create API; Siglume may use headers
+internally when calling providers.
+
 ## Micro / Nano Statement Privacy
 
 Micro Payment and Nano Payment introduce operational statement APIs and CSV
@@ -154,16 +167,15 @@ Direct Request Payment is not:
 - a platform balance
 - a card payment fallback
 
-Each payment is an individual wallet payment backed by an on-chain receipt. Small
-payments in the Micro and Nano amount bands are aggregated and settled on
-account-assigned weekly / monthly slots instead of one transaction at a time
-(see the [pricing guide](./pricing.md#settlement-schedule)), but they are still
-wallet payments, not a stored balance. Before a small payment is fulfilled,
-Siglume checks the buyer's wallet budget and fails closed when it is invalid, so
-a rejected request is never charged. Provider revenue for Micro and Nano remains
-unsettled until the aggregated on-chain settlement succeeds; Siglume does not
-advance or guarantee revenue when a buyer's balance, allowance, BudgetVault
-authorization, cap, or on-chain transaction fails.
+Standard Payment is settled individually with its own on-chain receipt. Micro
+and Nano usage events are included in an aggregated settlement batch, and the
+batch is backed by an on-chain receipt. They are still wallet payments, not a
+stored balance. Before a small payment is fulfilled, Siglume checks the buyer's
+wallet budget and fails closed when it is invalid, so a rejected request is
+never charged. Provider revenue for Micro and Nano remains unsettled until the
+aggregated on-chain settlement succeeds; Siglume does not advance or guarantee
+revenue when a buyer's balance, allowance, BudgetVault authorization, cap, or
+on-chain transaction fails.
 
 A Micro / Nano budget reservation is not a token lock, escrow, or payment
 guarantee. It reserves room against Siglume spending limits only. A later

package/examples/express-checkout.ts

@@ -22,6 +22,48 @@ app.use((req, res, next) => {
 
 const orders = new Map<string, any>();
 
+async function handleDirectPaymentConfirmed(data: Record<string, any>): Promise<void> {
+  if (data.mode === "metered_settlement_batch") {
+    // Aggregated Micro/Nano settlement events do not carry an order challenge.
+    // Reconcile them against statement / settlement batch data instead.
+    if (data.settlement_status === "settled") {
+      console.log("settled metered batch", data.settlement_batch_id || data.usage_event_digest);
+    }
+    return;
+  }
+
+  if (
+    data.pricing_band === "standard" &&
+    data.finality === "per_payment_onchain" &&
+    data.settlement_status === "settled"
+  ) {
+    const challengeHash = String(data.challenge_hash || "");
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+    if (order) {
+      order.siglume_payment_status = "paid";
+      order.siglume_requirement_id = data.requirement_id || data.direct_payment_requirement_id;
+      order.siglume_chain_receipt_id = data.chain_receipt_id || null;
+    }
+    return;
+  }
+
+  if (data.pricing_band === "micro" || data.pricing_band === "nano") {
+    const challengeHash = String(data.challenge_hash || "");
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+    if (order) {
+      order.siglume_payment_status = "fulfilled_unsettled";
+      order.siglume_requirement_id = data.requirement_id || data.direct_payment_requirement_id;
+    }
+    return;
+  }
+
+  // Unknown or older payload shape: do not mark paid from the event name alone.
+  console.warn("direct_payment.confirmed missing settlement machine fields", {
+    id: data.id,
+    requirement_id: data.requirement_id || data.direct_payment_requirement_id,
+  });
+}
+
 const asyncRoute =
   (handler: express.RequestHandler): express.RequestHandler =>
   (req, res, next) => {
@@ -69,12 +111,7 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
   );
 
   if (event.type === "direct_payment.confirmed") {
-    const challengeHash = String(event.data.challenge_hash || "");
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
-    if (order) {
-      order.siglume_payment_status = "paid";
-      order.siglume_requirement_id = event.data.requirement_id || event.data.direct_payment_requirement_id;
-    }
+    await handleDirectPaymentConfirmed(event.data);
   }
 
   res.status(204).send();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",