@siglume/direct-request-payment 0.4.5 → 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
 
@@ -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`
@@ -565,6 +581,13 @@ nonce: derive `nonce` from a durable order payment attempt, store the returned
 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:
 
@@ -937,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)`
 
@@ -959,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
@@ -971,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

@@ -109,7 +109,10 @@ 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.
+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
@@ -377,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 |
 | --- | --- | --- | --- |
@@ -446,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`,
@@ -183,8 +188,11 @@ 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. JavaScript integrations should not sum Micro / Nano minor amounts with
-`number`; use a decimal library. Python integrations should use `Decimal`.
+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
 

package/docs/security.md

@@ -125,6 +125,13 @@ 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

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.5",
+  "version": "0.4.6",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",