@siglume/direct-request-payment 0.4.14 → 0.4.16

package/docs/api-reference.md

@@ -353,6 +353,11 @@ Returns:
 - `webhook_subscription`: webhook subscription response, when created
 - `env`: server environment values to store, including returned secrets
 
+`merchant.merchant_account.metadata_jsonb.metered_risk_acceptance` records the
+merchant's Micro / Nano delayed-settlement risk acceptance receipt with
+`terms_version`, `accepted_at`, `principal_user_id`, `receipt_id`, and fixed
+market thresholds `JPY: 10000` / `USD: 10000`.
+
 Secrets are returned only when created or rotated. Existing secrets are not
 replayed by `getMerchant` / `get_merchant`.
 
@@ -537,15 +542,20 @@ accepted by these user-authenticated routes.
 This client creates SDRP Standard Payment requirements for external merchant
 checkout flows. Micro Payment and Nano Payment are applied automatically by
 amount and settled on account-assigned weekly / monthly slots, or earlier when a
-buyer/payee/token batch reaches JPY 10,000 / USD 100.00; they are not created
-explicitly through this client. Use the statement APIs below to see open-period
-usage, the close time, the final-notice schedule, and settled / unsettled /
-past-due revenue.
+buyer / provider / token / pricing-band batch reaches JPY 10,000 / USD 100.00;
+they are not created explicitly through this client. Use the statement APIs
+below to see open-period usage, the close time, the final-notice schedule, and
+settled / unsettled / past-due revenue.
 
 Standard Payment requirements include `fee_bps` from the Siglume platform. The
 SDK does not calculate merchant plan fees locally. For Micro / Nano, use the
 statement API amount fields (`protocol_fee_minor`, `gross_buyer_debit_minor`,
-`buyer_debit_minor`, and `rounding_delta_minor`); see [Pricing](./pricing.md).
+`buyer_debit_minor`, `provider_gross_amount_minor`, and
+`rounding_delta_minor`); see [Pricing](./pricing.md).
+`provider_gross_amount_minor` is canonical; `provider_usage_amount_minor` and
+`gross_buyer_debit_minor` are compatibility aliases of the same provider gross
+amount. Micro / Nano protocol fees are seller-borne, so
+`buyer_debit_minor = provider_gross_amount_minor`.
 
 ```ts
 const siglume = new DirectRequestPaymentClient({
@@ -772,6 +782,7 @@ returns `{items, next_cursor}`. When `next_cursor` is non-null, pass it back as
 Buyer-facing amount names are centered on the debit:
 
 - `estimated_buyer_debit_minor`
+- `provider_gross_amount_minor`
 - `provider_usage_amount_minor`
 - `gross_buyer_debit_minor`
 - `buyer_debit_minor`
@@ -837,6 +848,7 @@ back as `cursor` to fetch the next page.
 
 Provider-facing amount names:
 
+- `provider_gross_amount_minor`
 - `provider_usage_amount_minor`
 - `provider_receivable_minor`
 - `gross_buyer_debit_minor`
@@ -845,6 +857,9 @@ Provider-facing amount names:
 - `settled_provider_receivable_minor`
 - `unsettled_provider_receivable_minor`
 - `past_due_provider_receivable_minor`
+- `terminal_provider_receivable_minor`
+- `uncollectible_provider_receivable_minor`
+- `written_off_provider_receivable_minor`
 
 Schedule and execution fields:
 
@@ -862,6 +877,9 @@ Schedule and execution fields:
 - `usage_event_digest`
 - `attempt_count`
 - `next_attempt_at`
+- `terminal_status`
+- `terminal_marked_at`
+- `terminal_reason_code`
 
 Failure fields are sanitized for public display:
 
@@ -875,6 +893,14 @@ address, relayer id, nonce, gas data, raw RPC errors, or raw
 `failure_message`. Use `buyer_period_ref` for provider-side reconciliation
 within a period.
 
+Terminal statuses `uncollectible` and `written_off` are operator resolutions
+after past-due manual review. Their receivable fields are reported separately
+from settled, unsettled, and past-due revenue.
+
+If a Micro / Nano execution idempotency key is reused with a different input
+payload, execution fails closed before provider execution with
+`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD` and HTTP status `409`.
+
 ### Provider CSV export
 
 ```text
@@ -892,13 +918,14 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
 Columns:
 
 ```text
-metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
+metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_gross_amount_minor,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
 ```
 
 The CSV uses `buyer_period_ref`, not raw buyer account identifiers.
 The CSV keeps the `rounding_delta_minor` column for schema stability, but usage
-rows report `0`; the authoritative rounding adjustment is the settlement batch
-field `rounding_delta_minor`.
+rows report `0`. If a batch-level `rounding_delta_minor` appears in historical
+or internal records, do not add it to buyer debit and do not allocate it to
+provider revenue.
 
 Micro / Nano amount fields are decimal minor-unit strings. In JavaScript, do
 not aggregate them with `number`; parse them with a decimal library. In Python,
@@ -950,14 +977,17 @@ Returns the prepared-transaction payload object.
 Returns the bare HMAC-SHA256 hex digest over `"<timestamp>.<body>"`. This is the
 primitive `buildWebhookSignatureHeader` / `verifyWebhookSignature` use. In
 TypeScript `options` is `{ timestamp: number }`; in Python `timestamp` is a
-keyword-only `int`. `body` may be raw bytes, a string, or a JSON object.
+keyword-only `int`. `body` may be raw bytes, a string, or a JSON object when you
+are building a test signature. Production webhook verification must use the
+exact raw request body.
 
 ### `buildWebhookSignatureHeader(secret, body, options)` / `build_webhook_signature_header(secret, body, *, timestamp=None)`
 
 Returns a `t=<timestamp>,v1=<signature>` header string. Mainly for tests /
 mocking inbound webhooks. In TypeScript `options` is an optional
 `{ timestamp?: number }` (defaults to now); in Python `timestamp` is a
-keyword-only optional `int`.
+keyword-only optional `int`. This helper accepts JSON objects for tests; the
+verification helpers below do not.
 
 ### `verifyWebhookSignature(secret, body, signature_header, options)` / `verify_webhook_signature(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
 
@@ -966,7 +996,9 @@ Verifies the `Siglume-Signature` header against the raw `body`. Throws
 the timestamp is outside tolerance or the signature does not match. In TypeScript
 `options` is `{ tolerance_seconds?, now? }`; in Python those are keyword-only
 (`tolerance_seconds` defaults to `DEFAULT_WEBHOOK_TOLERANCE_SECONDS` = 300).
-Returns `{ timestamp, signature }`.
+Returns `{ timestamp, signature }`. Pass the exact raw request body bytes or raw
+body string captured by your web framework. Passing a parsed JSON object is
+rejected because re-stringifying changes the signed bytes.
 
 ### `parseDirectRequestPaymentWebhookEvent(payload)` / `parse_direct_request_payment_webhook_event(payload)`
 
@@ -1029,7 +1061,8 @@ return `kind: "unknown"` with a machine-readable `reason`.
 
 Verifies the signature and parses the event in one call. Returns
 `{ event, verification }` (TS) / `{"event": ..., "verification": ...}` (Py). Same
-options shape as `verifyWebhookSignature` (keyword-only in Python).
+options shape as `verifyWebhookSignature` (keyword-only in Python). The `body`
+argument is raw bytes or a raw body string only; do not pass parsed JSON.
 
 Webhook-verification trio (typical inbound webhook handler):
 
@@ -1058,6 +1091,45 @@ event = verified["event"]
 # or equivalent fail-closed field checks before marking an order paid or fulfilled.
 ```
 
+Express example:
+
+```ts
+app.post("/siglume/webhook", express.raw({ type: "application/json" }), async (req, res) => {
+  const { event } = await verifyDirectRequestPaymentWebhook(
+    process.env.SIGLUME_WEBHOOK_SECRET!,
+    req.body,
+    req.header("siglume-signature") ?? "",
+  );
+  res.json({ received: event.id });
+});
+```
+
+FastAPI example:
+
+```py
+@app.post("/siglume/webhook")
+async def siglume_webhook(request: Request):
+    raw_body = await request.body()
+    verified = verify_direct_request_payment_webhook(
+        os.environ["SIGLUME_WEBHOOK_SECRET"],
+        raw_body,
+        request.headers.get("siglume-signature", ""),
+    )
+    return {"received": verified["event"]["id"]}
+```
+
+Django example:
+
+```py
+def siglume_webhook(request):
+    verified = verify_direct_request_payment_webhook(
+        os.environ["SIGLUME_WEBHOOK_SECRET"],
+        request.body,
+        request.headers.get("Siglume-Signature", ""),
+    )
+    return JsonResponse({"received": verified["event"]["id"]})
+```
+
 ## Exported Constants
 
 Both packages export these importable constants:

package/docs/merchant-quickstart.md

@@ -31,6 +31,10 @@ 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.
+The setup response records this acceptance at
+`merchant.merchant_account.metadata_jsonb.metered_risk_acceptance` with a
+`terms_version`, `accepted_at`, `principal_user_id`, `receipt_id`, and fixed
+market thresholds `JPY: 10000` / `USD: 10000`.
 
 ## Two Buyer Systems
 

package/docs/metered-statements.md

@@ -91,38 +91,34 @@ open period. It can report `wallet_balance_checked: false` or
 `allowance_checked: false`; in that case it is guidance, not a final on-chain
 guarantee.
 
-## Amount Rounding
+## Seller-borne Micro / Nano Amounts
 
 Micro / Nano usage rows keep provider price and protocol fee values as decimal
 minor-unit amounts. This allows Nano fees such as JPY 0.2 per SDRP Tx to be
 accounted without rounding every accepted payment.
 
-Rounding happens once when a settlement batch is created:
+The buyer is charged only the provider-visible usage amount. Micro / Nano
+protocol fees are seller-borne and are deducted from provider receivable:
 
 ```text
-provider_usage_amount_minor = sum(provider price minor units for accepted metered rows)
+provider_gross_amount_minor = sum(provider price minor units for accepted metered rows)
+provider_usage_amount_minor = provider_gross_amount_minor   # legacy alias
+gross_buyer_debit_minor = provider_gross_amount_minor       # legacy alias
+buyer_debit_minor = provider_gross_amount_minor
 protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
-provider_receivable_minor = max(provider_usage_amount_minor - protocol_fee_minor, 0)
-gross_buyer_debit_minor = provider_usage_amount_minor
-buyer_debit_minor = ceil(gross_buyer_debit_minor)
-rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
+provider_receivable_minor = provider_gross_amount_minor - protocol_fee_minor
+rounding_delta_minor = 0 for buyer/provider accounting
 ```
 
-For low-count Nano batches, the ceiling can make the effective rounded debit per
-SDRP Tx higher than the decimal provider usage amount. Here, `Tx` means one
-accepted SDRP payment, not an on-chain settlement transaction. The protocol fee
-remains the decimal statement amount and is deducted from provider receivable;
-the extra integer-minor-unit 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.
-`protocol_fee_minor` is provider-borne and is not added to the buyer debit.
-Provider reports should use `provider_receivable_minor`,
-`settled_provider_receivable_minor`, `unsettled_provider_receivable_minor`, and
-`past_due_provider_receivable_minor`.
+Example: a JPY 100 Micro usage event has `buyer_debit_minor = 100`,
+`protocol_fee_minor = 2`, and `provider_receivable_minor = 98`.
+
+The `rounding_delta_minor` field remains in some statement schemas for
+compatibility. It is not added to `buyer_debit_minor`, not added to
+`provider_gross_amount_minor`, and not deducted again from
+`provider_receivable_minor`. If non-zero in a historical or internal record,
+treat it as a Siglume platform accounting adjustment, not buyer debit or
+provider revenue.
 
 Micro / Nano amount fields are decimal minor-unit strings. JavaScript
 integrations should aggregate them with a decimal library, not `number`. Python
@@ -149,7 +145,9 @@ Buyer usage event amount fields:
 
 - `provider_usage_amount_minor`: provider price for the usage event
 - `protocol_fee_minor`: provider-borne metered protocol fee
-- `gross_buyer_debit_minor`: provider usage amount before integer-token rounding
+- `provider_gross_amount_minor`: provider price before protocol fee
+- `gross_buyer_debit_minor`: legacy alias of `provider_gross_amount_minor`
+- `buyer_debit_minor`: buyer debit; equals `provider_gross_amount_minor`
 - `expected_scheduled_debit_at`: derived schedule for an open period before a
   settlement batch exists
 
@@ -175,8 +173,10 @@ Buyer batch amount fields:
 
 - `estimated_buyer_debit_minor`: total buyer debit for the batch
 - `provider_usage_amount_minor`: provider usage amount before protocol fee
-- `gross_buyer_debit_minor`: provider usage amount before integer-token rounding
+- `provider_gross_amount_minor`: provider gross before protocol fee
+- `gross_buyer_debit_minor`: legacy alias of `provider_gross_amount_minor`
 - `buyer_debit_minor`: amount scheduled for the debit transaction
+- `provider_receivable_minor`: provider gross minus provider-borne protocol fee
 
 Past-due batches include:
 
@@ -197,7 +197,7 @@ Threshold-control fields:
 - `threshold_reached_at`: set when the fixed amount threshold closed the batch
 - `total_unsettled_exposure_minor`: open plus `notice_pending`, `ready`,
   `submitted`, retrying, and `past_due` provider gross exposure for the same
-  buyer / provider / token
+  buyer / provider / token / pricing band
 
 JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
 conversions of one another.
@@ -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,13 +312,13 @@ 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 |
 | `settlement_threshold_minor` | Fixed market threshold for early settlement: JPY `10000` or USD `10000` minor units |
 | `threshold_reached_at` | Timestamp when the fixed threshold closed the batch, otherwise null |
-| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token |
+| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token / pricing band |
 | `expected_scheduled_debit_at` | Expected debit time for an open period before a batch exists |
 | `scheduled_debit_at` | Scheduled debit time after batch creation |
 | `not_before_attempt_at` | Earliest allowed debit attempt; this is the close-plus-3-day gate |
@@ -324,14 +326,19 @@ Important batch fields:
 | `latest_execution_attempt_status` | Latest non-sensitive execution attempt status |
 | `chain_receipt_id` | On-chain receipt id when available |
 | `usage_event_digest` | Digest of usage rows included in the batch |
+| `provider_gross_amount_minor` | Provider gross before provider-borne protocol fee |
 | `provider_usage_amount_minor` | Provider usage amount before protocol fee |
 | `provider_receivable_minor` | Provider amount for the batch after provider-borne protocol fee |
 | `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 |
-| `gross_buyer_debit_minor` | Provider usage amount before integer-token rounding |
+| `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 |
+| `buyer_debit_minor` | Amount scheduled for the buyer debit; equals provider gross |
 | `attempt_count`, `next_attempt_at` | Retry state |
 | `failure_reason_code`, `failure_reason_label`, `failure_reason_help` | Sanitized public failure reason |
 | `support_reference` | Non-secret support reference |
@@ -350,14 +357,14 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
 The CSV contains exactly these columns:
 
 ```text
-metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
+metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_gross_amount_minor,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
 ```
 
 The CSV uses `buyer_period_ref`, not `buyer_user_id`.
 `rounding_delta_minor` is present for a stable usage-event schema, but per-row
-values are `0`. The authoritative rounding adjustment is the settlement batch
-`rounding_delta_minor`; do not allocate that adjustment to provider revenue
-from individual CSV rows.
+values are `0`. If a batch-level `rounding_delta_minor` appears in historical or
+internal records, do not add it to buyer debit and do not allocate it to provider
+revenue.
 
 ## Notifications
 
@@ -471,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
 
@@ -487,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

@@ -151,8 +151,8 @@ confirmed payment turns into money in your settlement wallet.
   the affected batch is treated as past due. Siglume currently retries every 6
   hours for up to 28 automatic attempts. After that, the batch remains past due
   and requires manual resolution before another attempt.
-- While the same buyer / provider / token has total unsettled exposure at or
-  above the fixed threshold, new Micro/Nano usage is paused with the
+- While the same buyer / provider / token / pricing band has total unsettled
+  exposure at or above the fixed threshold, new Micro/Nano usage is paused with the
   machine-readable error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not
   called. Exposure includes open usage plus `notice_pending`, `ready`,
   `submitted`, retrying, and `past_due` batches, and remains paused while
@@ -167,7 +167,7 @@ confirmed payment turns into money in your settlement wallet.
 
 Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 
-- A buyer's wallet budget reservation is consumed at the **gross buyer debit
+- A buyer's wallet budget reservation is consumed at the **provider gross
   amount** (your usage price, before any provider-borne protocol fee) from
   acceptance until settlement confirms. This
   is a reservation against Siglume spending limits; it does not lock, escrow,
@@ -185,51 +185,43 @@ Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 ### What is fixed vs platform-managed
 
 The cadence fields are fixed: **Micro is weekly, Nano is monthly**. In both
-bands, Siglume can close a buyer/payee/token batch early once it reaches JPY
-10,000 or USD 100.00. A payment is final only after its on-chain settlement
-confirms. Micro and Nano are automatic amount bands, not customer-selected
-options. The account-assigned period boundaries, roughly 3-day pre-debit notice
-window, early settlement threshold, and current retry policy above are the
-public behavior as of 2026-06-19. Treat the platform's statement status,
-`not_before_attempt_at`, Standard `fee_bps`, and Micro / Nano statement amount
-fields as authoritative rather than hard-coding local revenue recognition.
-
-## Micro / Nano Amount Rounding
+bands, Siglume can close a buyer / provider / token / pricing-band batch early
+once provider gross reaches JPY 10,000 or USD 100.00. These are fixed
+market-specific thresholds, not FX conversions of one another. A payment is
+final only after its on-chain settlement confirms. Micro and Nano are automatic
+amount bands, not customer-selected options. The account-assigned period
+boundaries, roughly 3-day pre-debit notice window, early settlement threshold,
+and current retry policy above are the public behavior as of 2026-06-19. Treat
+the platform's statement status, `not_before_attempt_at`, Standard `fee_bps`,
+and Micro / Nano statement amount fields as authoritative rather than
+hard-coding local revenue recognition.
+
+## Micro / Nano Seller-borne Amounts
 
 Micro / Nano fees are stored internally as decimal minor-unit values so
-sub-yen and sub-cent Nano fees are not silently rounded per accepted SDRP Tx. The
-current settlement rule is:
+sub-yen and sub-cent Nano fees are not silently rounded per accepted SDRP Tx.
+The buyer is charged only the provider-visible usage amount; the protocol fee is
+not added to the buyer debit:
 
 ```text
-provider_usage_amount_minor = sum(provider price minor units for accepted metered rows)
+provider_gross_amount_minor = sum(provider price minor units for accepted metered rows)
+provider_usage_amount_minor = provider_gross_amount_minor   # legacy alias
+gross_buyer_debit_minor = provider_gross_amount_minor       # legacy alias
+buyer_debit_minor = provider_gross_amount_minor
 protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
-provider_receivable_minor = max(provider_usage_amount_minor - protocol_fee_minor, 0)
-gross_buyer_debit_minor = provider_usage_amount_minor
-buyer_debit_minor = ceil(gross_buyer_debit_minor)
-rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
+provider_receivable_minor = provider_gross_amount_minor - protocol_fee_minor
+rounding_delta_minor = 0 for buyer/provider accounting
 ```
 
-Rounding happens once when the settlement batch is created, not per accepted
-SDRP Tx.
-The rounding mode is ceiling to the next integer token minor unit because
-on-chain settlement cannot debit fractional JPYC/USDC minor units. The positive
-`rounding_delta_minor` is part of the buyer debit for that batch and is retained
-as a rounding adjustment in Siglume's settlement accounting; it is not provider
-revenue. `protocol_fee_minor` is provider-borne and is deducted from provider
-receivable, not added to the buyer debit. Providers should reconcile their
-revenue with
-`provider_receivable_minor`, `settled_provider_receivable_minor`,
-`unsettled_provider_receivable_minor`, and
-`past_due_provider_receivable_minor`, not with `buyer_debit_minor`.
-
-For low-count Nano batches, the integer ceiling can make the effective buyer
-rounded debit per SDRP Tx higher than the decimal provider usage amount. The
-decimal protocol fee remains visible as `protocol_fee_minor` and is deducted
-from provider receivable; the difference created by integer-token settlement is
-visible as `rounding_delta_minor` on the 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
+Example: a JPY 100 Micro usage event has buyer debit JPY 100, protocol fee JPY
+2, and provider receivable JPY 98.
+
+The `rounding_delta_minor` field is retained in some schemas for compatibility.
+It is not added to `buyer_debit_minor`, not added to
+`provider_gross_amount_minor`, and not deducted again from
+`provider_receivable_minor`. If non-zero in a historical or internal record,
+treat it as a Siglume platform accounting adjustment, not buyer debit or
+provider revenue. JavaScript integrations should not sum Micro / Nano minor
 amounts with `number`; use a decimal library. Python integrations should use
 `Decimal`.
 
@@ -241,12 +233,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/package.json

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