@siglume/direct-request-payment 0.4.13 → 0.4.15

package/docs/api-reference.md

@@ -537,15 +537,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,10 +777,15 @@ 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`
 - `protocol_fee_minor`
+- `settlement_trigger`
+- `settlement_threshold_minor`
+- `threshold_reached_at`
+- `total_unsettled_exposure_minor`
 
 ### Provider summary
 
@@ -833,6 +843,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 +856,10 @@ Provider-facing amount names:
 Schedule and execution fields:
 
 - `period_start`, `period_end`, `close_at`
+- `settlement_trigger`
+- `settlement_threshold_minor`
+- `threshold_reached_at`
+- `total_unsettled_exposure_minor`
 - `expected_scheduled_debit_at`
 - `scheduled_debit_at`
 - `not_before_attempt_at`
@@ -884,13 +899,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,
@@ -942,14 +958,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)`
 
@@ -958,7 +977,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)`
 
@@ -1021,7 +1042,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):
 
@@ -1050,6 +1072,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/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 about JPY 0.2 per SDRP Tx to
-be accounted without rounding every accepted payment.
+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:
 
@@ -190,6 +190,18 @@ Buyer-triggered requeue is not part of the MVP. The buyer-facing UI should show
 the block reason, tell the buyer to repair balance / allowance / BudgetVault /
 caps, and point them to support with `support_reference`.
 
+Threshold-control fields:
+
+- `settlement_trigger`: `amount_threshold` or `scheduled_close`
+- `settlement_threshold_minor`: JPY `10000` or USD `10000` minor units
+- `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 / pricing band
+
+JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
+conversions of one another.
+
 ## Provider Statement APIs
 
 ### Summary
@@ -301,6 +313,10 @@ Important batch fields:
 | `status` | Batch lifecycle state such as `notice_pending`, `ready`, `submitted`, `settled`, `failed`, `past_due`, 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 / 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 |
@@ -308,14 +324,15 @@ 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 |
+| `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 |
@@ -334,14 +351,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
 
@@ -375,9 +392,10 @@ Siglume retries failed Micro / Nano settlement every 6 hours for up to 28
 automatic attempts. After that the batch remains `past_due` until operator
 requeue.
 
-New Micro / Nano usage for the same buyer, plan type, and token is paused while
-the past-due block remains. The provider API is not called for the rejected
-request, and the request is not charged.
+New Micro / Nano usage for the same buyer / provider / token is paused while
+the total unsettled exposure is at or above the fixed threshold, and while a
+failed or past-due block remains. The provider API is not called for the
+rejected request, and the request is not charged.
 
 Public failure fields are sanitized. Show `failure_reason_code`,
 `failure_reason_label`, `failure_reason_help`, and `support_reference` to users

package/docs/pricing.md

@@ -34,8 +34,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 | USD 0.01 / SDRP Tx, about JPY 2 | 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 | USD 0.001 / SDRP Tx, about JPY 0.2 | 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 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)) |
 
 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
@@ -105,7 +105,9 @@ confirmed payment turns into money in your settlement wallet.
   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.
+  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.
@@ -125,7 +127,9 @@ confirmed payment turns into money in your settlement wallet.
   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.
+  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.
@@ -147,9 +151,12 @@ 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 a buyer has an unresolved failed Micro/Nano settlement for the same
-  payment band and token, new Micro/Nano usage is paused with the machine-readable
-  error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not called.
+- 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
+  settlement failure or `past_due` is unresolved.
 - Outstanding amounts remain attached to the failed settlement and are retried
   under this policy. They are not settled revenue, and Siglume does not advance,
   guarantee, or insure provider revenue before on-chain settlement succeeds.
@@ -160,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,
@@ -178,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`.
 

package/package.json

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