@siglume/direct-request-payment 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.7 - 2026-06-19
+
+Documentation-only patch release.
+
+- Clarified that SDRP merchant setup and billing mandate terms assume acceptance
+  of automatic Micro / Nano delayed aggregated settlement for low-price bands.
+- Replaced merchant-specific override wording with the operational rule that
+  products requiring immediate settlement should be priced in the Standard band.
+
+## 0.4.6 - 2026-06-19
+
+Patch release for the external webhook-state re-review.
+
+- Changed webhook examples to branch Standard settled payments, Micro / Nano
+  accepted-but-unsettled usage, and metered settlement batches separately.
+- Added Hosted Checkout settlement machine fields and metered settlement batch
+  webhook fields to TypeScript types and API docs.
+- Clarified public Nano one-time amount limits, Micro / Nano idempotency key
+  placement, and per-batch rounding adjustment behavior.
+- Added `pytest python_tests` to the PyPI Trusted Publishing release workflow.
+
 ## 0.4.5 - 2026-06-19
 
 Patch release for the public beta re-review.

package/README.md

@@ -67,12 +67,16 @@ card-style "instant" checkout for first-time buyers.
 Some merchant accounts may not have the server endpoint enabled yet. In that
 case `createCheckoutSession(...)` / `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError` instead of exposing the raw rollout 404/409.
-Keep fulfilling only from the signed `direct_payment.confirmed` webhook.
+Keep the signed `direct_payment.confirmed` webhook as the durable signal, and
+inspect its settlement machine fields before marking any order paid.
 
 Hosted Checkout is a Siglume-hosted page that turns a "Pay with Siglume" button
 into a completed wallet payment, then returns the shopper to your store. It
-orchestrates the same rails as the agent flow — there is no new money movement
-and the merchant fulfills on the same `direct_payment.confirmed` webhook.
+orchestrates the same rails as the agent flow — there is no new money movement.
+Fulfillment still starts from the signed `direct_payment.confirmed` webhook, but
+you must inspect the settlement machine fields before deciding whether the event
+means Standard settled payment, Micro / Nano accepted usage, or aggregated
+Micro / Nano settlement.
 
 ```ts
 import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
@@ -99,9 +103,12 @@ const session = await merchant.createCheckoutSession({
 });
 redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
-// 3. Fulfill when the signed direct_payment.confirmed webhook arrives (the
-//    source of truth). Poll merchant.getCheckoutSession(session.session_id) if
-//    you also want to show status in your own UI.
+// 3. Handle the signed direct_payment.confirmed webhook. Fulfill Standard only
+//    when pricing_band=standard, finality=per_payment_onchain, and
+//    settlement_status=settled. Treat Micro / Nano as accepted but unsettled
+//    until the later metered settlement batch is settled.
+//    Poll merchant.getCheckoutSession(session.session_id) if you also want to
+//    show status in your own UI.
 ```
 
 ```py
@@ -131,9 +138,12 @@ session = merchant.create_checkout_session(
 )
 redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
-# 3. Fulfill when the signed direct_payment.confirmed webhook arrives (the
-#    source of truth). Poll merchant.get_checkout_session(session["session_id"])
-#    if you also want to show status in your own UI.
+# 3. Handle the signed direct_payment.confirmed webhook. Fulfill Standard only
+#    when pricing_band=standard, finality=per_payment_onchain, and
+#    settlement_status=settled. Treat Micro / Nano as accepted but unsettled
+#    until the later metered settlement batch is settled.
+#    Poll merchant.get_checkout_session(session["session_id"]) if you also want
+#    to show status in your own UI.
 ```
 
 Siglume fixes the amount, currency, challenge, and return URLs **server-side** at
@@ -183,7 +193,12 @@ weekly / monthly settlement schedule are in [docs/pricing.md](./docs/pricing.md)
 Provider revenue in the Micro and Nano bands is not settled revenue until the
 weekly or monthly on-chain settlement succeeds. Siglume keeps outstanding failed
 settlements for retry under the published policy, but does not advance or
-guarantee provider revenue before settlement succeeds.
+guarantee provider revenue before settlement succeeds. Merchant setup and the
+billing mandate terms assume the merchant accepts this Micro / Nano delayed
+aggregated settlement model whenever they offer amounts in these bands. If a
+product cannot fulfill before provider revenue is settled, keep the price in the
+Standard band; in practice, do not offer JPY 500-and-under or USD 3-and-under
+items for that product.
 Micro / Nano budget checks reserve spending capacity only; they do not lock,
 escrow, or guarantee the buyer's wallet balance, allowance, or settlement funds.
 Sub-minor-unit Nano fees are accumulated with decimal precision and rounded only
@@ -208,7 +223,8 @@ and CSV exports, see
 - buyer-authenticated payment requirement creation
 - prepared wallet transaction execution payloads
 - payment requirement verification
-- authenticated TypeScript JSON requests to Micro / Nano statement APIs
+- authenticated TypeScript JSON requests and named Python helpers for Micro /
+  Nano statement APIs
 - signed webhook verification
 
 It does not custody funds or manage customer wallets. Merchant setup runs through
@@ -246,14 +262,19 @@ amounts differ.
 | Under JPY 50 / up to USD 0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / usage, about JPY 0.2 | Monthly settlement - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
 
 A merchant billing mandate is required before accepting payments, even on the
-Launch plan. The current public API does not expose a flag that forces a
-JPY 500-and-under / USD 3-and-under payment into Standard immediate settlement.
-If immediate on-chain settlement is a hard requirement, price the item in the
-Standard band or confirm a merchant-specific contract with Siglume before
-launch. For Standard Payment, `fee_bps` returned on a payment requirement is the
-authoritative fee rate for that payment in the merchant's settlement currency.
-For Micro / Nano, the statement APIs expose `protocol_fee_minor`,
-`gross_buyer_debit_minor`, `buyer_debit_minor`, and `rounding_delta_minor`.
+Launch plan. The current public API chooses the payment band from
+`amount_minor`; JPY 500-and-under / USD 3-and-under payments are routed to
+Micro / Nano delayed aggregated settlement. Accepting the SDRP merchant terms
+means accepting automatic Micro / Nano delayed aggregated settlement for those
+low-price bands. If immediate on-chain settlement is a hard requirement, price
+the item in the Standard band; in practice, do not offer JPY 500-and-under or
+USD 3-and-under items for that product. Public Direct Payment / Hosted Checkout
+`amount_minor` is a positive integer in minor currency units, so public one-time
+Nano amounts start at JPY 1 or USD 0.01. For Standard Payment, `fee_bps`
+returned on a payment requirement is the authoritative fee rate for that payment
+in the merchant's settlement currency. For Micro / Nano, the statement APIs
+expose `protocol_fee_minor`, `gross_buyer_debit_minor`, `buyer_debit_minor`, and
+`rounding_delta_minor`.
 The full fee table and the weekly / monthly settlement schedule live in
 [docs/pricing.md](./docs/pricing.md). Statement APIs for "how much was used,
 when will it close, when can it debit, and what is settled" are documented in
@@ -513,7 +534,19 @@ const { event } = await verifyDirectRequestPaymentWebhook(
 );
 
 if (event.type === "direct_payment.confirmed") {
-  // Mark the order paid if event.data.challenge_hash/order mapping matches.
+  if (event.data.mode === "metered_settlement_batch") {
+    // Reconcile settled Micro / Nano batches by settlement_batch_id /
+    // usage_event_digest; these events do not carry an order challenge hash.
+  } else if (
+    event.data.pricing_band === "standard" &&
+    event.data.finality === "per_payment_onchain" &&
+    event.data.settlement_status === "settled"
+  ) {
+    // Mark the order paid once if event.data.challenge_hash/order mapping matches.
+  } else if (event.data.pricing_band === "micro" || event.data.pricing_band === "nano") {
+    // Mark fulfilled-but-unsettled only if your business allows fulfillment
+    // before the aggregated Micro / Nano settlement succeeds.
+  }
 }
 ```
 
@@ -529,14 +562,30 @@ verified = verify_direct_request_payment_webhook(
 )
 
 if verified["event"]["type"] == "direct_payment.confirmed":
-    # Mark the order paid if event.data.challenge_hash/order mapping matches.
-    pass
+    data = verified["event"]["data"]
+    if data.get("mode") == "metered_settlement_batch":
+        # Reconcile settled Micro / Nano batches by settlement_batch_id /
+        # usage_event_digest; these events do not carry an order challenge hash.
+        pass
+    elif (
+        data.get("pricing_band") == "standard"
+        and data.get("finality") == "per_payment_onchain"
+        and data.get("settlement_status") == "settled"
+    ):
+        # Mark the order paid once if event.data.challenge_hash/order mapping matches.
+        pass
+    elif data.get("pricing_band") in ("micro", "nano"):
+        # Mark fulfilled-but-unsettled only if your business allows fulfillment
+        # before the aggregated Micro / Nano settlement succeeds.
+        pass
 ```
 
 New `direct_payment.confirmed` payloads include `pricing_band`,
-`settlement_cadence`, `finality`, `protocol_fee_minor`, `settlement_status`, and
-when available `request_hash_v2`. Use these machine fields instead of inferring
-settlement semantics from the event name alone.
+`settlement_cadence`, `finality`, `protocol_fee_minor`, `settlement_status`,
+`settlement_batch_id`, `chain_receipt_id`, `usage_event_digest`, `settled_at`,
+and when available `request_hash_v2`. Use these machine fields instead of
+inferring settlement semantics from the event name alone. Do not mark an order
+paid from the event type alone.
 
 ## Security Rules
 
@@ -559,7 +608,8 @@ Read [docs/security.md](./docs/security.md) before going live.
 - Store `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` only on the merchant server.
 - Store the returned `SIGLUME_WEBHOOK_SECRET` only on the merchant server.
 - Persist `challenge_hash`, `requirement_id`, and fulfillment state per order.
-- Fulfill orders only from verified webhook data, with idempotency.
+- Fulfill orders only from verified webhook data, with idempotency, after
+  checking `pricing_band`, `finality`, and `settlement_status`.
 - Treat `fee_bps` returned by Siglume as the Standard Payment runtime fee source
   of truth; use statement API amount fields for Micro / Nano.
 

package/dist/index.cjs

@@ -78,7 +78,7 @@ var DIRECT_REQUEST_PAYMENT_RECEIPT_KIND = "sdrp_direct_payment";
 var DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND = "sdrp_direct_payment_allowance";
 var DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE = "sdrp_direct_payment_requirement";
 var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
-var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.5";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.7";
 var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {