@siglume/direct-request-payment 0.4.15 → 0.4.17

package/docs/metered-statements.md

@@ -19,8 +19,8 @@ Siglume applies the settlement band from the amount.
 
 | Band | Cadence | Period close | First debit attempt | Revenue recognition |
 | --- | --- | --- | --- | --- |
-| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
-| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; can close early once the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; can close early once the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
 
 The schedule is platform-managed. Buyers and providers can see the resulting
 batch period and scheduled attempt times through the statement APIs, but cannot
@@ -248,7 +248,9 @@ Use:
 - `totals.unsettled_provider_receivable_minor` for expected but not yet settled
   revenue,
 - `totals.past_due_provider_receivable_minor` for provider revenue blocked on a
-  past-due buyer settlement.
+  past-due buyer settlement,
+- `totals.terminal_provider_receivable_minor` for provider receivable that an
+  operator has marked `uncollectible` or `written_off` after past-due review.
 
 ### Usage Events
 
@@ -310,7 +312,7 @@ Important batch fields:
 
 | Field | Meaning |
 | --- | --- |
-| `status` | Batch lifecycle state such as `notice_pending`, `ready`, `submitted`, `settled`, `failed`, `past_due`, or `notice_delivery_failed` |
+| `status` | Batch lifecycle state such as `notice_pending`, `ready`, `submitted`, `settled`, `failed`, `past_due`, `uncollectible`, `written_off`, or `notice_delivery_failed` |
 | `notice_status` | Final debit notice delivery status |
 | `period_start`, `period_end`, `close_at` | Statement period boundaries |
 | `settlement_trigger` | `amount_threshold` for early threshold close, or `scheduled_close` for weekly/monthly close |
@@ -330,6 +332,10 @@ Important batch fields:
 | `settled_provider_receivable_minor` | Provider receivable that is settled on-chain |
 | `unsettled_provider_receivable_minor` | Provider receivable not yet settled |
 | `past_due_provider_receivable_minor` | Provider receivable blocked on past-due settlement |
+| `terminal_provider_receivable_minor` | Provider receivable marked terminal after operator review |
+| `uncollectible_provider_receivable_minor` | Terminal provider receivable classified as uncollectible |
+| `written_off_provider_receivable_minor` | Terminal provider receivable classified as written off |
+| `terminal_status`, `terminal_marked_at`, `terminal_reason_code` | Public terminal resolution fields, present only for terminal batches |
 | `gross_buyer_debit_minor` | Legacy alias of provider gross; protocol fee is not added |
 | `protocol_fee_minor` | Micro / Nano protocol fee deducted from provider receivable |
 | `buyer_debit_minor` | Amount scheduled for the buyer debit; equals provider gross |
@@ -472,13 +478,24 @@ settled only when `status === "settled"` and `chain_receipt_id` is present.
 
 Buyer summary `past_due_blocks` returns `METERED_SETTLEMENT_PAST_DUE` with a
 sanitized reason and support reference. The buyer must repair the listed balance
-or authorization issue. Requeue is operator-only in the MVP.
+or authorization issue. Requeue is operator-only in the MVP. If operator review
+marks a past-due batch `uncollectible` or `written_off`, new usage may resume,
+but the provider receivable moves to terminal accounting instead of settled,
+unsettled, or past-due revenue.
+
+If the same execution idempotency key is reused with a different Micro / Nano
+input payload, the platform fails closed before provider execution with
+`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD` and HTTP status `409`.
 
 ### "What should our accounting system book?"
 
 Book `settled_provider_receivable_minor` as settled revenue. Keep
 `unsettled_provider_receivable_minor` and `past_due_provider_receivable_minor`
-separate from settled revenue.
+separate from settled revenue. Keep
+`terminal_provider_receivable_minor`, `uncollectible_provider_receivable_minor`,
+and `written_off_provider_receivable_minor` outside settled, unsettled, and
+past-due revenue; they represent operator terminal resolution, not successful
+on-chain settlement.
 
 ## Go-Live Checklist
 
@@ -488,6 +505,8 @@ separate from settled revenue.
   `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 dashboard separates terminal `uncollectible` / `written_off` provider
+  amounts from settled, unsettled, and past-due revenue.
 - Your support UI shows sanitized failure fields and `support_reference`.
 - You do not store or display raw buyer IDs from provider APIs; use
   `buyer_period_ref`.

package/docs/pricing.md

@@ -1,7 +1,7 @@
 # Pricing
 
 This page documents the trial-phase merchant pricing for Siglume Direct Request
-Payment as of 2026-06-18. Pricing can change by agreement or future product
+Payment as of SDK v0.4.17. Pricing can change by agreement or future product
 release; the Siglume platform response is the source of truth for per-payment
 fee data returned at runtime.
 
@@ -14,12 +14,13 @@ delayed aggregated settlement whenever they offer amounts in those bands.
 ## Settlement Currencies
 
 Siglume Direct Request Payment launches in the US and Japan, and both settlement
-currencies are first-class:
+currencies are first-class where enabled:
 
 - **JPY**, settled on-chain in **JPYC**
 - **USD**, settled on-chain in **USDC**
 
-A merchant settles in a single currency, chosen at onboarding. The settlement fee
+A merchant settles in a single currency, chosen at onboarding. Some accounts may
+require agreed USD/USDC terms before USD is enabled. The settlement fee
 percentage (the payment fee column below) is identical in both currencies. Only
 the flat amounts — the monthly base fee and the per-payment minimum fee — are
 quoted per currency.
@@ -34,8 +35,8 @@ charging.
 | Public one-time payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
 | JPY 501+ / USD 3.01+ | Standard Payment | Select one Standard plan: Launch, Starter, Growth, or Pro | Launch: JPY 0 / USD 0 monthly, 1.8%; Starter: JPY 980 / USD 6 monthly, 1.0%; Growth: JPY 2,980 / USD 18 monthly, 0.7%; Pro: JPY 9,800 / USD 60 monthly, 0.5%. Minimum JPY 30 / USD 0.20 per payment. | Settled on-chain immediately after the payment confirms |
-| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | JPY 2 / USD 0.01 per SDRP Tx | Aggregated and settled **weekly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
-| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | JPY 0.2 / USD 0.001 per SDRP Tx | Aggregated and settled **monthly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
+| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | JPY 2 / USD 0.01 per SDRP Tx | Aggregated and settled **weekly**, or earlier once the same buyer / provider / token / pricing band reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
+| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | JPY 0.2 / USD 0.001 per SDRP Tx | Aggregated and settled **monthly**, or earlier once the same buyer / provider / token / pricing band reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
 
 In this table, `Tx` means one accepted SDRP payment, not an on-chain settlement
 transaction. Micro / Nano settlement batches are aggregated on-chain after the
@@ -43,8 +44,8 @@ weekly or monthly close, or earlier when the fixed amount threshold is reached.
 
 Standard Payment settles per payment. Micro Payment and Nano Payment are
 aggregated and settled in account-assigned weekly / monthly slots, with early
-settlement when the same buyer/payee/token/period batch reaches JPY 10,000 or
-USD 100.00. See [Settlement schedule](#settlement-schedule) for how each band
+settlement when the same buyer / provider / token / pricing band reaches JPY
+10,000 or USD 100.00. See [Settlement schedule](#settlement-schedule) for how each band
 closes, when the pre-debit notice window elapses, when revenue becomes settled,
 and how rejected requests behave.
 
@@ -65,8 +66,9 @@ field-by-field meaning of `scheduled_debit_at`, `not_before_attempt_at`,
 `execution_status`, and `buyer_period_ref`, see
 [Micro / Nano Statements and Notices](./metered-statements.md).
 
-USD pricing is the JPY tier converted at roughly 160 JPY/USD and rounded to
-clean price points that keep the same 1:3:10 tier ratio.
+USD plan prices are set as separate public price points. The JPY 10,000 and USD
+100.00 Micro / Nano early-settlement thresholds are fixed market thresholds,
+not FX conversions of one another.
 
 If no paid plan is selected during merchant setup, the merchant account uses the
 Launch plan. A merchant billing mandate is still required before accepting
@@ -95,25 +97,25 @@ confirmed payment turns into money in your settlement wallet.
 | Band | Cadence | Period | You are paid |
 | --- | --- | --- | --- |
 | Standard Payment | Per payment | n/a | On-chain, immediately after each payment confirms |
-| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
-| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, provider, token, pricing band, and period |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If the same buyer / provider / token / pricing band reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, provider, token, pricing band, and period |
 
 ### Micro weekly settlement
 
 - **Closing period.** Micro-band payments accrue across one weekly period. The
   specific closing weekday and time are assigned as a fixed slot per account to
   spread settlement load.
-- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
-  10,000 or USD 100.00 before the weekly close, Siglume can close that batch
-  early and start the same final-notice and settlement flow. JPY 10,000 and USD
-  100.00 are market-specific fixed thresholds, not FX conversions of one
-  another.
+- **Early threshold settlement.** If the same buyer / provider / token /
+  pricing band reaches JPY 10,000 or USD 100.00 before the weekly close,
+  Siglume can close that batch early and start the same final-notice and
+  settlement flow. JPY 10,000 and USD 100.00 are market-specific fixed
+  thresholds, not FX conversions of one another.
 - **Timezone.** Period boundaries are evaluated in the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
 - **Settlement.** After the week closes or the early threshold is reached,
   Siglume aggregates the Micro
-  payments — grouped per buyer, payee, token, and period — into on-chain
+  payments — grouped per buyer, provider, token, pricing band, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
@@ -125,17 +127,17 @@ confirmed payment turns into money in your settlement wallet.
 - **Closing period.** Nano-band payments accrue across one monthly period. The
   specific closing day and time are assigned as a fixed slot per account to
   spread settlement load.
-- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
-  10,000 or USD 100.00 before the monthly close, Siglume can close that batch
-  early and start the same final-notice and settlement flow. JPY 10,000 and USD
-  100.00 are market-specific fixed thresholds, not FX conversions of one
-  another.
+- **Early threshold settlement.** If the same buyer / provider / token /
+  pricing band reaches JPY 10,000 or USD 100.00 before the monthly close,
+  Siglume can close that batch early and start the same final-notice and
+  settlement flow. JPY 10,000 and USD 100.00 are market-specific fixed
+  thresholds, not FX conversions of one another.
 - **Timezone.** As with Micro, period boundaries use the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
 - **Settlement.** After the month closes or the early threshold is reached,
   Siglume aggregates the Nano
-  payments — grouped per buyer, payee, token, and period — into on-chain
+  payments — grouped per buyer, provider, token, pricing band, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
@@ -233,12 +235,17 @@ but it does not replace the Micro / Nano statement APIs.
 
 Use [Micro / Nano Statements and Notices](./metered-statements.md) to integrate:
 
-- provider summary of open, settled, unsettled, and past-due revenue,
+- provider summary of open, settled, unsettled, past-due, and terminal
+  `uncollectible` / `written_off` revenue buckets,
 - provider usage-event CSV export,
 - buyer summaries for open-period estimated debit and past-due blocks,
 - sanitized public failure reasons and support references,
 - the fixed final notice plus close-plus-3-day debit window.
 
+Reusing the same Micro / Nano execution idempotency key with a different input
+payload fails closed before provider execution with
+`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD` and HTTP status `409`.
+
 ## SDK Behavior
 
 The SDK does not calculate merchant invoices or enforce plan limits locally.

package/examples/express-checkout.ts

@@ -130,7 +130,9 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
 app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
   // Log the detail server-side; never return raw error messages to the client —
   // a payment error can otherwise leak internal API details or configuration.
-  console.error("checkout error:", error);
+  console.error("checkout error:", {
+    name: error instanceof Error ? error.name : "Error",
+  });
   res.status(500).json({ error: "internal_error" });
 });
 

package/package.json

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