@siglume/direct-request-payment 0.4.5 → 0.4.7

package/docs/merchant-quickstart.md

@@ -16,11 +16,15 @@ order challenge; the buyer-facing Siglume payment flow pays it.
 
 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 pass a
-"force Standard" flag. Micro/Nano are settled on account-assigned weekly /
+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.
+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
+offering JPY 500-and-under or USD 3-and-under amounts.
 
 ## Two Buyer Systems
 
@@ -396,16 +400,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 +472,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

@@ -7,7 +7,9 @@ fee data returned at runtime.
 
 Pricing has one structure: a merchant selects the Standard Payment plan during
 setup, then Siglume applies the fee for each payment by amount. Micro Payment
-and Nano Payment are automatic amount bands, not separate choices.
+and Nano Payment are automatic amount bands, not separate choices. Merchant
+setup and the billing mandate terms assume the merchant accepts Micro / Nano
+delayed aggregated settlement whenever they offer amounts in those bands.
 
 ## Settlement Currencies
 
@@ -36,10 +38,17 @@ aggregated and settled in account-assigned weekly / monthly slots - see
 pre-debit notice window elapses, when revenue becomes settled, and how rejected
 requests behave.
 
-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.
+The current public API chooses the band from `amount_minor`; JPY 500-and-under /
+USD 3-and-under payments are routed to Micro / Nano delayed aggregated
+settlement. If a merchant needs immediate on-chain finality, the payment amount
+must be in the Standard band. In practice, do not offer JPY 500-and-under or
+USD 3-and-under items for a product that cannot accept Micro / Nano delayed
+aggregated settlement. 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 +192,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.7",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",