@siglume/direct-request-payment 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.4.8 - 2026-06-19
+
+Webhook sample hardening release.
+
+- Added TypeScript and Python confirmation classifiers for Standard settled
+  payments, Micro / Nano accepted usage, and Micro / Nano settled batches.
+- Updated public webhook samples to require finality, settlement status, and
+  non-empty settlement identifiers before fulfilling or reconciling.
+- Routed unknown Micro / Nano challenge hashes and malformed settlement batch
+  confirmations to manual review in copy-paste samples.
+
+## 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.

package/README.md

@@ -103,10 +103,10 @@ const session = await merchant.createCheckoutSession({
 });
 redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
-// 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.
+// 3. Handle the signed direct_payment.confirmed webhook. Use
+//    classifyDirectPaymentConfirmation(event). Fulfill Standard only for
+//    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
+//    until the later metered_batch_settled event arrives.
 //    Poll merchant.getCheckoutSession(session.session_id) if you also want to
 //    show status in your own UI.
 ```
@@ -138,10 +138,10 @@ session = merchant.create_checkout_session(
 )
 redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
-# 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.
+# 3. Handle the signed direct_payment.confirmed webhook. Use
+#    classify_direct_payment_confirmation(event). Fulfill Standard only for
+#    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
+#    until the later metered_batch_settled event arrives.
 #    Poll merchant.get_checkout_session(session["session_id"]) if you also want
 #    to show status in your own UI.
 ```
@@ -193,10 +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.
-If your product cannot fulfill before provider revenue is settled, keep the
-price in the Standard band or agree a merchant-specific contract with Siglume
-before launch.
+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
@@ -260,16 +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. 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`.
+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
@@ -520,7 +525,10 @@ the payload. Create a marketplace webhook subscription with
 signing secret once.
 
 ```ts
-import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
+import {
+  classifyDirectPaymentConfirmation,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
 
 const { event } = await verifyDirectRequestPaymentWebhook(
   process.env.SIGLUME_WEBHOOK_SECRET!,
@@ -529,18 +537,16 @@ const { event } = await verifyDirectRequestPaymentWebhook(
 );
 
 if (event.type === "direct_payment.confirmed") {
-  if (event.data.mode === "metered_settlement_batch") {
+  const confirmation = classifyDirectPaymentConfirmation(event);
+  if (confirmation.kind === "metered_batch_settled") {
     // 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"
-  ) {
+  } else if (confirmation.kind === "standard_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.
+  } else if (confirmation.kind === "metered_usage_accepted") {
+    // Mark fulfilled-but-unsettled after matching confirmation.challenge_hash.
+  } else {
+    // Route confirmation.reason to manual review. Do not mark paid or fulfilled.
   }
 }
 ```
@@ -548,7 +554,10 @@ if (event.type === "direct_payment.confirmed") {
 ```py
 import os
 
-from siglume_direct_request_payment import verify_direct_request_payment_webhook
+from siglume_direct_request_payment import (
+    classify_direct_payment_confirmation,
+    verify_direct_request_payment_webhook,
+)
 
 verified = verify_direct_request_payment_webhook(
     os.environ["SIGLUME_WEBHOOK_SECRET"],
@@ -557,30 +566,30 @@ verified = verify_direct_request_payment_webhook(
 )
 
 if verified["event"]["type"] == "direct_payment.confirmed":
-    data = verified["event"]["data"]
-    if data.get("mode") == "metered_settlement_batch":
+    confirmation = classify_direct_payment_confirmation(verified["event"])
+    if confirmation["kind"] == "metered_batch_settled":
         # 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"
-    ):
+    elif confirmation["kind"] == "standard_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.
+    elif confirmation["kind"] == "metered_usage_accepted":
+        # Mark fulfilled-but-unsettled after matching confirmation["challenge_hash"].
+        pass
+    else:
+        # Route confirmation["reason"] to manual review. Do not mark paid or fulfilled.
         pass
 ```
 
 New `direct_payment.confirmed` payloads include `pricing_band`,
 `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.
+and when available `request_hash_v2`. Use
+`classifyDirectPaymentConfirmation(event)` /
+`classify_direct_payment_confirmation(event)` or the same machine-field checks
+instead of inferring settlement semantics from the event name alone. Do not mark
+an order paid from the event type alone.
 
 ## Security Rules
 

package/dist/index.cjs

@@ -34,11 +34,15 @@ __export(src_exports, {
   DEFAULT_WEBHOOK_TOLERANCE_SECONDS: () => DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
   DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND: () => DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME: () => DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME,
+  DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS: () => DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS,
+  DIRECT_REQUEST_PAYMENT_METERED_FINALITY: () => DIRECT_REQUEST_PAYMENT_METERED_FINALITY,
   DIRECT_REQUEST_PAYMENT_MODE: () => DIRECT_REQUEST_PAYMENT_MODE,
   DIRECT_REQUEST_PAYMENT_RECEIPT_KIND: () => DIRECT_REQUEST_PAYMENT_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME: () => DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME,
   DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE: () => DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE,
   DIRECT_REQUEST_PAYMENT_SDK_VERSION: () => DIRECT_REQUEST_PAYMENT_SDK_VERSION,
+  DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY: () => DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY,
+  DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS: () => DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS,
   DirectRequestPaymentClient: () => DirectRequestPaymentClient,
   DirectRequestPaymentMerchantClient: () => DirectRequestPaymentMerchantClient,
   HostedCheckoutNotAvailableError: () => HostedCheckoutNotAvailableError,
@@ -50,6 +54,7 @@ __export(src_exports, {
   buildPaymentExecutionPayload: () => buildPaymentExecutionPayload,
   buildPreparedTransactionExecutionPayload: () => buildPreparedTransactionExecutionPayload,
   buildWebhookSignatureHeader: () => buildWebhookSignatureHeader,
+  classifyDirectPaymentConfirmation: () => classifyDirectPaymentConfirmation,
   computeWebhookSignature: () => computeWebhookSignature,
   createDirectRequestPaymentChallenge: () => createDirectRequestPaymentChallenge,
   createDirectRequestPaymentChallengeSignature: () => createDirectRequestPaymentChallengeSignature,
@@ -78,7 +83,11 @@ 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.6";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.8";
+var DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS = "settled";
+var DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS = "pending_settlement";
+var DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY = "per_payment_onchain";
+var DIRECT_REQUEST_PAYMENT_METERED_FINALITY = "aggregated_onchain_settlement";
 var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {
@@ -671,6 +680,112 @@ function parseDirectRequestPaymentWebhookEvent(payload) {
   }
   return parsed;
 }
+function classifyDirectPaymentConfirmation(event) {
+  const data = event.data;
+  const requirementId = stringOrNull(data.requirement_id) ?? stringOrNull(data.direct_payment_requirement_id);
+  const challengeHash = stringOrNull(data.challenge_hash);
+  const pricingBand = stringOrNull(data.pricing_band);
+  const finality = stringOrNull(data.finality);
+  const settlementStatus = stringOrNull(data.settlement_status);
+  if (event.type !== "direct_payment.confirmed") {
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "not_direct_payment_confirmed",
+      requirement_id: requirementId,
+      settlement_batch_id: stringOrNull(data.settlement_batch_id),
+      pricing_band: pricingBand,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (data.mode === "metered_settlement_batch") {
+    const settlementBatchId = stringOrNull(data.settlement_batch_id);
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    const usageEventDigest = stringOrNull(data.usage_event_digest);
+    if (settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && settlementBatchId && chainReceiptId && usageEventDigest) {
+      return {
+        kind: "metered_batch_settled",
+        event,
+        data,
+        settlement_batch_id: settlementBatchId,
+        chain_receipt_id: chainReceiptId,
+        usage_event_digest: usageEventDigest,
+        settled_at: stringOrNull(data.settled_at)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "invalid_metered_settlement_confirmation",
+      requirement_id: requirementId,
+      settlement_batch_id: settlementBatchId,
+      pricing_band: pricingBand,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "standard") {
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    if (finality === DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && requirementId && challengeHash && chainReceiptId) {
+      return {
+        kind: "standard_settled",
+        event,
+        data,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        chain_receipt_id: chainReceiptId,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_standard_settlement_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "micro" || pricingBand === "nano") {
+    if (finality === DIRECT_REQUEST_PAYMENT_METERED_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS && requirementId && challengeHash) {
+      return {
+        kind: "metered_usage_accepted",
+        event,
+        data,
+        pricing_band: pricingBand,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_metered_usage_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  return {
+    kind: "unknown",
+    event,
+    data,
+    reason: "unknown_confirmation_shape",
+    requirement_id: requirementId,
+    settlement_batch_id: stringOrNull(data.settlement_batch_id),
+    pricing_band: pricingBand,
+    settlement_status: settlementStatus,
+    finality
+  };
+}
 async function verifyDirectRequestPaymentWebhook(signing_secret, body, signature_header, options = {}) {
   const verification = await verifyWebhookSignature(signing_secret, body, signature_header, options);
   const text = new TextDecoder().decode(bodyBytes(body));