@siglume/direct-request-payment 0.4.6 → 0.4.8

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
 
@@ -388,7 +392,10 @@ signer and verifier only.
 Use the webhook as the durable signal, not just the browser return path.
 
 ```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!,
@@ -400,57 +407,57 @@ if (event.type !== "direct_payment.confirmed") {
   return new Response(null, { status: 204 });
 }
 
-const data = event.data;
+const confirmation = classifyDirectPaymentConfirmation(event);
 
-if (data.mode === "metered_settlement_batch") {
+if (confirmation.kind === "metered_batch_settled") {
   // 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 ?? ""),
-    });
-  }
+  await orders.reconcileMeteredSettlementOnce({
+    settlement_batch_id: confirmation.settlement_batch_id,
+    chain_receipt_id: confirmation.chain_receipt_id,
+    usage_event_digest: confirmation.usage_event_digest,
+    settled_at: confirmation.settled_at ?? null,
+  });
   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 (confirmation.kind === "standard_settled") {
+  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
   if (!order) {
     await orders.flagForPaymentStateReview({
       reason: "unknown_challenge_hash",
-      requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+      requirement_id: confirmation.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 ?? ""),
+    siglume_requirement_id: confirmation.requirement_id,
+    chain_receipt_id: confirmation.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),
+if (confirmation.kind === "metered_usage_accepted") {
+  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
+  if (!order) {
+    await orders.flagForPaymentStateReview({
+      reason: "unknown_metered_challenge_hash",
+      requirement_id: confirmation.requirement_id,
     });
+    return new Response(null, { status: 204 });
   }
+  await orders.markFulfilledButUnsettledOnce(order.id, {
+    siglume_requirement_id: confirmation.requirement_id,
+    pricing_band: confirmation.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 ?? ""),
+  reason: confirmation.reason,
+  requirement_id: confirmation.requirement_id ?? "",
+  settlement_batch_id: confirmation.settlement_batch_id ?? null,
 });
 return new Response(null, { status: 204 });
 ```
@@ -460,7 +467,10 @@ Python:
 ```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"],
@@ -471,53 +481,54 @@ verified = verify_direct_request_payment_webhook(
 if verified["event"]["type"] != "direct_payment.confirmed":
     return "", 204
 
-data = verified["event"]["data"]
+confirmation = classify_direct_payment_confirmation(verified["event"])
 
-if data.get("mode") == "metered_settlement_batch":
+if confirmation["kind"] == "metered_batch_settled":
     # 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 ""),
-        )
+    orders.reconcile_metered_settlement_once(
+        settlement_batch_id=confirmation["settlement_batch_id"],
+        chain_receipt_id=confirmation["chain_receipt_id"],
+        usage_event_digest=confirmation["usage_event_digest"],
+        settled_at=confirmation.get("settled_at"),
+    )
     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 confirmation["kind"] == "standard_settled":
+    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
     if not order:
         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 ""),
+            requirement_id=confirmation["requirement_id"],
         )
         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 ""),
+        siglume_requirement_id=confirmation["requirement_id"],
+        chain_receipt_id=confirmation["chain_receipt_id"],
     )
     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 ""),
+if confirmation["kind"] == "metered_usage_accepted":
+    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
+    if not order:
+        orders.flag_for_payment_state_review(
+            reason="unknown_metered_challenge_hash",
+            requirement_id=confirmation["requirement_id"],
         )
+        return "", 204
+    orders.mark_fulfilled_but_unsettled_once(
+        order["id"],
+        siglume_requirement_id=confirmation["requirement_id"],
+        pricing_band=confirmation["pricing_band"],
+    )
     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 ""),
+    reason=confirmation["reason"],
+    requirement_id=confirmation.get("requirement_id") or "",
+    settlement_batch_id=confirmation.get("settlement_batch_id"),
 )
 return "", 204
 ```
@@ -525,11 +536,12 @@ return "", 204
 ## Reconcile Micro / Nano Statements
 
 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:
+webhook only when `classifyDirectPaymentConfirmation(event)` returns
+`standard_settled`, which requires Standard pricing, per-payment on-chain
+finality, settled status, a challenge hash, a requirement id, and a chain
+receipt id. 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/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,15 +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.
-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.
+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`,

package/examples/express-checkout.ts

@@ -1,5 +1,6 @@
 import express from "express";
 import {
+  classifyDirectPaymentConfirmation,
   DirectRequestPaymentMerchantClient,
   verifyDirectRequestPaymentWebhook,
 } from "@siglume/direct-request-payment";
@@ -22,45 +23,54 @@ 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") {
+async function flagForPaymentStateReview(payload: Record<string, any>): Promise<void> {
+  console.warn("payment state review required", payload);
+}
+
+async function handleDirectPaymentConfirmed(event: any): Promise<void> {
+  const classification = classifyDirectPaymentConfirmation(event);
+
+  if (classification.kind === "metered_batch_settled") {
     // 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);
-    }
+    console.log("settled metered batch", classification.settlement_batch_id, classification.chain_receipt_id);
     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 (classification.kind === "standard_settled") {
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
     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;
+      order.siglume_requirement_id = classification.requirement_id;
+      order.siglume_chain_receipt_id = classification.chain_receipt_id;
+    } else {
+      await flagForPaymentStateReview({
+        reason: "unknown_challenge_hash",
+        requirement_id: classification.requirement_id,
+      });
     }
     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 (classification.kind === "metered_usage_accepted") {
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
     if (order) {
       order.siglume_payment_status = "fulfilled_unsettled";
-      order.siglume_requirement_id = data.requirement_id || data.direct_payment_requirement_id;
+      order.siglume_requirement_id = classification.requirement_id;
+    } else {
+      await flagForPaymentStateReview({
+        reason: "unknown_metered_challenge_hash",
+        requirement_id: classification.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,
+  await flagForPaymentStateReview({
+    reason: classification.reason,
+    requirement_id: classification.requirement_id,
+    settlement_batch_id: classification.settlement_batch_id,
   });
 }
 
@@ -111,7 +121,7 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
   );
 
   if (event.type === "direct_payment.confirmed") {
-    await handleDirectPaymentConfirmed(event.data);
+    await handleDirectPaymentConfirmed(event);
   }
 
   res.status(204).send();

package/package.json

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