@siglume/direct-request-payment 0.4.3 → 0.4.4

package/docs/api-reference.md

@@ -267,7 +267,15 @@ Returns the `sha256:`-prefixed hash for an existing challenge string.
 ## `directRequestPaymentRequestHash(input)` / `direct_request_payment_request_hash(...)`
 
 Returns the SDK-side request hash material for merchant, amount, currency, and
-challenge. This is mostly useful for tests and internal assertions.
+challenge. This is the legacy v1 hash retained for wire compatibility and
+existing idempotency assertions.
+
+## `directRequestPaymentRequestHashV2(input)` / `direct_request_payment_request_hash_v2(...)`
+
+Returns the v2 request hash for the same fields using canonical JSON before
+hashing. New tests and server-side assertions should prefer this value when the
+API response includes `request_hash_v2`; keep accepting `request_hash` for older
+requirements and historical webhook payloads.
 
 ## `DirectRequestPaymentMerchantClient`
 
@@ -308,8 +316,10 @@ Input:
   Hosted Checkout (open-redirect defense). A Hosted Checkout `success_url` /
   `cancel_url` must be on a registered origin; the origin of
   `webhook_callback_url` is auto-allowed in addition. Each entry must be an
-  absolute origin such as `https://shop.example.com`; entries are normalized to
-  bare, lowercased origins and deduped.
+  absolute origin such as `https://shop.example.com`; production origins must
+  use `https`. Development `http` origins are accepted only for `localhost`,
+  `127.0.0.1`, or `[::1]`. Userinfo is rejected. Entries are normalized to bare,
+  lowercased origins and deduped.
 
 In addition to the `setupMerchant` inputs above, `setupCheckout` accepts these
 orchestration toggles:
@@ -371,7 +381,7 @@ POST /v1/sdrp/direct-payments/checkout-sessions
 ```ts
 const session = await merchant.createCheckoutSession({
   merchant: "example_merchant",
-  amount_minor: 500,
+  amount_minor: 1200,
   currency: "JPY",
   nonce: order.id,
   success_url: "https://www.your-shop.com/thanks",
@@ -383,7 +393,7 @@ const session = await merchant.createCheckoutSession({
 ```py
 session = merchant.create_checkout_session(
     merchant="example_merchant",
-    amount_minor=500,
+    amount_minor=1200,
     currency="JPY",
     nonce=order["id"],
     success_url="https://www.your-shop.com/thanks",
@@ -505,8 +515,10 @@ 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.
 
-Payment requirements include `fee_bps` from the Siglume platform. The SDK does
-not calculate merchant plan fees locally; see [Pricing](./pricing.md).
+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).
 
 ```ts
 const siglume = new DirectRequestPaymentClient({
@@ -544,6 +556,22 @@ Input:
 - `allowance_amount_minor`: optional positive integer
 - `metadata`: optional JSON object
 
+The returned requirement includes both compatibility and machine-readable
+settlement fields:
+
+- `request_hash`: legacy v1 request hash, retained for existing requirements
+  and integrations.
+- `request_hash_v2`: canonical-JSON v2 request hash when the server can compute
+  one for the challenge-backed request.
+- `pricing_band`: `standard`, `micro`, or `nano`.
+- `settlement_cadence`: `per_payment`, `weekly`, or `monthly`.
+- `finality`: machine-readable finality class such as
+  `per_payment_onchain` or `aggregated_onchain_settlement`.
+- `protocol_fee_minor`: Micro / Nano protocol fee when applicable; `null` for
+  Standard Payment.
+- `settlement_status`: `pending_payment`, `provisional`, `settled`,
+  `pending_settlement`, or another explicit operational state.
+
 ### `getPaymentRequirement(requirement_id)` / `get_payment_requirement(requirement_id)`
 
 Calls:
@@ -640,9 +668,9 @@ base URL configured on `DirectRequestPaymentClient`.
 `/sdrp/metered/my-summary`. The helper expects a JSON response. Use raw
 `fetch`, `curl`, or your HTTP client for CSV exports.
 
-Python does not expose a public generic request helper in this release. Use
-ordinary HTTPS requests with the same Siglume bearer token for endpoints that do
-not yet have a named Python SDK method.
+Python does not expose a public generic request helper. Use the named Python
+methods documented below for Micro / Nano statements, and ordinary HTTPS
+requests for endpoints that do not yet have a named Python SDK method.
 
 ## Metered Statement APIs
 
@@ -667,13 +695,16 @@ Common query parameters:
 TypeScript:
 
 ```ts
-const summary = await siglume.request<{
-  role: "buyer";
-  open_periods: Array<Record<string, unknown>>;
-  settlement_batches: Array<Record<string, unknown>>;
-  past_due_blocks: Array<Record<string, unknown>>;
-  balance_sufficiency: Record<string, unknown>;
-}>("GET", "/sdrp/metered/my-summary?plan_type=micro&token_symbol=JPYC");
+const summary = await siglume.getBuyerMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+summary = siglume.get_buyer_metered_summary(plan_type="micro", token_symbol="JPYC")
 ```
 
 Use `open_periods` for current-period estimated debit,
@@ -687,6 +718,14 @@ GET /v1/sdrp/metered/my-usage-events
 GET /v1/sdrp/metered/my-settlement-batches
 ```
 
+SDK methods:
+
+- TypeScript: `listBuyerUsageEvents(...)`, `listBuyerSettlementBatches(...)`
+- Python: `list_buyer_usage_events(...)`, `list_buyer_settlement_batches(...)`
+
+Each accepts `plan_type`, `token_symbol`, `status`, and `limit`, and returns
+`{items, next_cursor}`.
+
 Buyer-facing amount names are centered on the debit:
 
 - `estimated_buyer_debit_minor`
@@ -711,16 +750,16 @@ Common query parameters:
 TypeScript:
 
 ```ts
-const providerSummary = await siglume.request<{
-  role: "provider";
-  timezone: string;
-  open_periods: Array<Record<string, unknown>>;
-  periods: Array<Record<string, unknown>>;
-  totals: Record<string, string>;
-}>(
-  "GET",
-  "/sdrp/metered/provider/summary?plan_type=micro&token_symbol=JPYC",
-);
+const providerSummary = await siglume.getProviderMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+provider_summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
 ```
 
 Use `open_periods` for current-period expected revenue, `periods` for closed
@@ -736,6 +775,18 @@ GET /v1/sdrp/metered/provider/settlement-batches
 GET /v1/sdrp/metered/provider/settlement-batches/{settlement_batch_id}
 ```
 
+SDK methods:
+
+- TypeScript: `listProviderUsageEvents(...)`,
+  `listProviderSettlementBatches(...)`, `getProviderSettlementBatch(...)`
+- Python: `list_provider_usage_events(...)`,
+  `list_provider_settlement_batches(...)`, `get_provider_settlement_batch(...)`
+
+Provider list methods accept `plan_type`, `token_symbol`, `status`,
+`listing_id`, `capability_key`, and `limit`. Detail accepts
+`settlement_batch_id`, plus optional `listing_id` and `capability_key`. List
+methods return `{items, next_cursor}`.
+
 Provider-facing amount names:
 
 - `provider_receivable_minor`
@@ -862,8 +913,17 @@ Returns `{ timestamp, signature }`.
 Validates and normalizes a parsed webhook event object (requires `id`, `type`,
 `api_version`, `occurred_at`, and an object `data`). Throws
 `SiglumeWebhookPayloadError` on a malformed event, or when a
-`direct_payment.confirmed` event does not carry `data.mode = "external_402"`. The
-`payload` argument is positional in both languages.
+`direct_payment.confirmed` event does not carry a supported Direct Request
+Payment mode (`external_402` or `metered_settlement_batch`). The `payload`
+argument is positional in both languages.
+
+For `direct_payment.confirmed`, inspect `event.data.pricing_band`,
+`event.data.settlement_cadence`, `event.data.finality`,
+`event.data.protocol_fee_minor`, and `event.data.settlement_status` instead of
+inferring whether the event means per-payment on-chain confirmation or an
+aggregated Micro / Nano settlement confirmation. `event.data.request_hash_v2`
+is present on new challenge-backed requirements; keep accepting
+`event.data.request_hash` for historical payloads.
 
 ### `verifyDirectRequestPaymentWebhook(secret, body, signature_header, options)` / `verify_direct_request_payment_webhook(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
 
@@ -910,6 +970,7 @@ Both packages export these importable constants:
 | `DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND` | `sdrp_direct_payment_allowance` |
 | `DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE` | `sdrp_direct_payment_requirement` |
 | `DEFAULT_WEBHOOK_TOLERANCE_SECONDS` | `300` |
+| `DIRECT_REQUEST_PAYMENT_SDK_VERSION` | package version string |
 
 The `external_402` / `siglume-external-402-*` values are legacy wire-compat
 identifiers, not public product names (see the README "Compatibility Notes").

package/docs/merchant-quickstart.md

@@ -14,11 +14,12 @@ external merchant.
 The merchant server must not create charges with a customer wallet. It signs the
 order challenge; the buyer-facing Siglume payment flow pays it.
 
-This quickstart is for SDRP Standard Payment in an external merchant product.
-Micro Payment and Nano Payment are applied automatically by amount and settled on
-account-assigned weekly / monthly slots after the final notice and close-plus-3-day
-site (see [Pricing](./pricing.md#settlement-schedule)); they are not browser
-checkout requirements you create with this SDK. Their provider revenue remains
+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 /
+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.
 
 ## Two Buyer Systems
@@ -74,7 +75,7 @@ await merchant.setupCheckout({
 // Per order: create a session and redirect the shopper to checkout_url.
 const session = await merchant.createCheckoutSession({
   merchant: "example_merchant",
-  amount_minor: 500,            // server-fixed; the browser cannot change it
+  amount_minor: 1200,           // server-fixed; the browser cannot change it
   currency: "JPY",
   nonce: order.id,              // unique per order
   success_url: "https://www.example.com/thanks",
@@ -114,7 +115,7 @@ merchant.setup_checkout(
 # Per order: create a session and redirect the shopper to checkout_url.
 session = merchant.create_checkout_session(
     merchant="example_merchant",
-    amount_minor=500,            # server-fixed; the browser cannot change it
+    amount_minor=1200,           # server-fixed; the browser cannot change it
     currency="JPY",
     nonce=order["id"],           # unique per order
     success_url="https://www.example.com/thanks",
@@ -452,14 +453,10 @@ const siglume = new DirectRequestPaymentClient({
   auth_token: providerSiglumeBearerToken,
 });
 
-const summary = await siglume.request<{
-  open_periods: Array<Record<string, unknown>>;
-  periods: Array<Record<string, unknown>>;
-  totals: Record<string, string>;
-}>(
-  "GET",
-  "/sdrp/metered/provider/summary?plan_type=micro&token_symbol=JPYC",
-);
+const summary = await siglume.getProviderMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
 
 console.log(summary.totals.settled_provider_receivable_minor);
 console.log(summary.totals.unsettled_provider_receivable_minor);
@@ -474,9 +471,14 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
   -o sdrp-metered.csv
 ```
 
-Python does not expose a public generic request helper in this release. Use
-ordinary HTTPS requests with the provider's Siglume bearer token for these
-statement endpoints.
+Python exposes the same named helper:
+
+```py
+from siglume_direct_request_payment import DirectRequestPaymentClient
+
+siglume = DirectRequestPaymentClient(auth_token=provider_siglume_bearer_token)
+summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
+```
 
 Do not book Micro / Nano provider revenue as settled revenue until the batch is
 `settled` and `chain_receipt_id` is present. See

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 | Account-assigned fixed weekly slot in the buyer settlement timezone | After final debit notice delivery and the fixed close-plus-3-day site | Only after the aggregated settlement confirms on-chain |
-| Nano Payment | Monthly | Account-assigned fixed monthly slot in the buyer settlement timezone | After final debit notice delivery and the fixed close-plus-3-day site | Only after the aggregated settlement confirms on-chain |
+| Micro Payment | Weekly | Account-assigned fixed weekly slot in the buyer settlement timezone | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Nano Payment | Monthly | Account-assigned fixed monthly slot in the buyer settlement timezone | 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 assigned
 period and scheduled attempt times through the statement APIs, but cannot choose
@@ -45,10 +45,8 @@ token. Provider responses never include raw `buyer_user_id`, buyer email, or raw
 wallet identifiers. Use `buyer_period_ref` to reconcile repeated usage by the
 same buyer within the provider's statement period without receiving buyer PII.
 
-TypeScript can call JSON statement endpoints with
-`DirectRequestPaymentClient.request<T>()`. Python does not expose a public
-generic request helper in this release; use ordinary HTTPS requests with the
-same bearer token.
+TypeScript and Python expose named helpers for the JSON statement endpoints.
+Use raw HTTPS only for the CSV export.
 
 ## Buyer Statement APIs
 
@@ -63,19 +61,19 @@ const siglume = new DirectRequestPaymentClient({
   auth_token: buyerSiglumeBearerToken,
 });
 
-const summary = await siglume.request<{
-  role: "buyer";
-  open_periods: Array<Record<string, unknown>>;
-  settlement_batches: Array<Record<string, unknown>>;
-  past_due_blocks: Array<Record<string, unknown>>;
-  balance_sufficiency: Record<string, unknown>;
-}>(
-  "GET",
-  "/sdrp/metered/my-summary?plan_type=micro&token_symbol=JPYC",
-);
+const summary = await siglume.getBuyerMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+summary = siglume.get_buyer_metered_summary(plan_type="micro", token_symbol="JPYC")
 ```
 
-Raw HTTP / Python:
+Raw HTTP:
 
 ```bash
 curl https://siglume.com/v1/sdrp/metered/my-summary?plan_type=micro\&token_symbol=JPYC \
@@ -92,6 +90,28 @@ 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
+
+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 usage to be
+accounted without rounding every event.
+
+Rounding happens once when a settlement batch is created:
+
+```text
+provider_usage_amount_minor = sum(provider price minor units for accepted usage)
+protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted usage)
+gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+buyer_debit_minor = ceil(gross_buyer_debit_minor)
+rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
+```
+
+`rounding_delta_minor` belongs to the buyer debit and Siglume's rounding
+adjustment accounting for that batch. It is not provider revenue. Provider
+reports should use `provider_receivable_minor`,
+`settled_provider_receivable_minor`, `unsettled_provider_receivable_minor`, and
+`past_due_provider_receivable_minor`.
+
 ### Usage Events
 
 ```text
@@ -105,6 +125,9 @@ Query parameters:
 - `status`: for example `pending_settlement`, `settled`, `failed_chargeable`
 - `limit`: 1 to 500
 
+SDK methods: `listBuyerUsageEvents(...)` / `list_buyer_usage_events(...)`.
+They return `{items, next_cursor}`.
+
 Buyer usage event amount fields:
 
 - `provider_usage_amount_minor`: provider price for the usage event
@@ -127,6 +150,9 @@ Query parameters:
   `past_due`, or `notice_delivery_failed`
 - `limit`: 1 to 200
 
+SDK methods: `listBuyerSettlementBatches(...)` /
+`list_buyer_settlement_batches(...)`. They return `{items, next_cursor}`.
+
 Buyer batch amount fields:
 
 - `estimated_buyer_debit_minor`: total buyer debit for the batch
@@ -157,20 +183,19 @@ const siglume = new DirectRequestPaymentClient({
   auth_token: providerSiglumeBearerToken,
 });
 
-const providerSummary = await siglume.request<{
-  role: "provider";
-  timezone: string;
-  filters: Record<string, unknown>;
-  open_periods: Array<Record<string, unknown>>;
-  periods: Array<Record<string, unknown>>;
-  totals: Record<string, string>;
-}>(
-  "GET",
-  "/sdrp/metered/provider/summary?plan_type=micro&token_symbol=JPYC",
-);
+const providerSummary = await siglume.getProviderMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+provider_summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
 ```
 
-Raw HTTP / Python:
+Raw HTTP:
 
 ```bash
 curl https://siglume.com/v1/sdrp/metered/provider/summary?plan_type=micro\&token_symbol=JPYC \
@@ -210,6 +235,9 @@ Query parameters:
 - `capability_key`
 - `limit`: 1 to 500
 
+SDK methods: `listProviderUsageEvents(...)` /
+`list_provider_usage_events(...)`. They return `{items, next_cursor}`.
+
 Provider usage event fields include:
 
 - `provider_receivable_minor`
@@ -242,6 +270,10 @@ Query parameters for the list endpoint:
 
 The detail endpoint also accepts `listing_id` and `capability_key`.
 
+SDK methods: `listProviderSettlementBatches(...)` /
+`list_provider_settlement_batches(...)` and `getProviderSettlementBatch(...)` /
+`get_provider_settlement_batch(...)`. List methods return `{items, next_cursor}`.
+
 Important batch fields:
 
 | Field | Meaning |
@@ -326,6 +358,40 @@ Public failure fields are sanitized. Show `failure_reason_code`,
 `failure_reason_label`, `failure_reason_help`, and `support_reference` to users
 or support staff. Do not depend on raw platform failure messages.
 
+## Usage Accounting by Result
+
+Use idempotency keys for every paid operation. Siglume records one chargeable
+usage event per idempotency key within the same buyer / listing / operation
+scope.
+
+| Case | Provider API executed? | Usage counted? | Integration rule |
+| --- | --- | --- | --- |
+| Budget gate rejected | No | No | Treat the request as rejected with no charge. The provider must not fulfill work. |
+| Provider returns 2xx | Yes | Yes | Chargeable usage is recorded once. Fulfill idempotently by order id / requirement id / idempotency key. |
+| Provider returns 4xx | Yes | Usually no, unless your integration deliberately marks the work as accepted before returning the 4xx | Prefer returning 2xx for completed work and 4xx only for unfulfilled client errors. Document any deliberate `failed_chargeable` mapping in your provider. |
+| Provider returns 5xx | Yes | No by default | Treat as unfulfilled; retry from the caller with the same idempotency key if safe. |
+| Provider timeout | Unknown | No by default unless the provider later confirms successful work under the same idempotency key | Reconcile by idempotency key before retrying side effects. |
+| Client disconnects after provider success | Yes | Yes if the provider completed work and Siglume observed/records that success | The client may see failure while the provider completed work; use idempotency to avoid duplicate fulfillment. |
+| Duplicate idempotency key | Maybe | One usage event | Return/reconcile the first outcome; do not create another chargeable event. |
+| Usage cancellation/refund before settlement | Depends on platform support and status | Not self-service in this SDK release | Contact support or use the platform path Siglume provides for the account; do not mutate CSV/statement totals locally. |
+| Refund/adjustment after settlement | Settled on-chain | Not self-service in this SDK release | Handle through an explicit adjustment/refund process; do not reverse settled revenue by editing statements. |
+
+`failed_chargeable` means the provider-side work is treated as completed or
+economically accepted even though the caller may have observed a failure state.
+It is for cases such as "provider completed the operation, but the client
+connection failed before receiving the response." It is not a catch-all for
+provider 5xx errors. Integrations should make this state rare and defensible by
+using stable idempotency keys and provider-side completion records.
+
+## Operational Status Handling
+
+| Status | Buyer / provider view | Automatic processing | Operator action | Integration guidance |
+| --- | --- | --- | --- | --- |
+| `notice_delivery_failed` | Buyer debit is not yet allowed; provider revenue remains unsettled | Notice delivery can be retried or reviewed | Required if delivery keeps failing | Do not attempt your own debit notice or mark revenue settled. Show support context only. |
+| `submitted_reconcile_required` | A settlement submission exists but final on-chain outcome is not yet reconciled | Reconciliation may complete if a receipt is found | Required if reconciliation stalls | Do not retry payment yourself. Wait for `settled`, `failed_retryable`, or `past_due`. |
+| `past_due` | Buyer has an unresolved settlement block; provider sees past-due revenue | New Micro / Nano usage for the same buyer / plan / token is paused | Operator requeue or manual resolution only | Do not promise collection or provider payment. Ask the buyer to repair balance / allowance / BudgetVault / caps and reference `support_reference`. |
+| `failed_chargeable` | Usage is still chargeable because provider work was accepted or completed | Included in later settlement attempts | Review if the provider disputes completion | Keep fulfillment idempotent and preserve evidence keyed by idempotency key. |
+
 ## Operational Recipes
 
 ### "How much did we use this week or month?"

package/docs/pricing.md

@@ -26,16 +26,21 @@ quoted per currency.
 
 | Payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
-| Over JPY 500 / over USD 3.00, or whenever immediate finality is required | 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 |
+| Over JPY 500 / over USD 3.00 | 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 / over USD 0.30 and up to USD 3.00 | Micro Payment | Applied automatically by amount | USD 0.01 / Tx, about JPY 2 | Aggregated and settled **weekly** (see [Settlement schedule](#settlement-schedule)) |
 | Under JPY 50 / up to USD 0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / usage, about JPY 0.2 | Aggregated and settled **monthly** (see [Settlement schedule](#settlement-schedule)) |
 
 Standard Payment settles per payment. Micro Payment and Nano Payment are
 aggregated and settled in account-assigned weekly / monthly slots - see
 [Settlement schedule](#settlement-schedule) for how each band closes, when the
-pre-debit notice site elapses, when revenue becomes settled, and how rejected
+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 the operational statement APIs, CSV export, buyer past-due blocks, and the
 field-by-field meaning of `scheduled_debit_at`, `not_before_attempt_at`,
 `execution_status`, and `buyer_period_ref`, see
@@ -52,10 +57,13 @@ Per-payment fees are deducted at settlement, so the merchant receives the net
 amount for each payment. Monthly base fees are collected separately through the
 merchant billing mandate.
 
-The same fee schedule applies in JPY and USD. The Siglume platform returns
-`fee_bps` in the merchant's settlement currency on every payment requirement, so
-the SDK never has to know which currency table to read — it just trusts the
-value Siglume returns.
+The same Standard Payment percentage schedule applies in JPY and USD. For
+Standard Payment, the Siglume platform returns `fee_bps` in the merchant's
+settlement currency on the payment requirement, so the SDK never has to know
+which currency table to read — it just trusts the value Siglume returns. For
+Micro / Nano, the authoritative fee fields are the statement API amounts:
+`protocol_fee_minor`, `gross_buyer_debit_minor`, `buyer_debit_minor`, and
+`rounding_delta_minor`.
 
 ## Settlement schedule
 
@@ -65,8 +73,8 @@ 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 | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes and the roughly 3-day pre-debit notice site has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
-| Nano Payment | Monthly | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes and the roughly 3-day pre-debit notice site has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Micro Payment | Weekly | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes 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 | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes 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 weekly settlement
 
@@ -80,7 +88,7 @@ confirmed payment turns into money in your settlement wallet.
   payments — grouped per buyer, payee, token, 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 site (`not_before_attempt_at`).
+  3-day pre-debit notice window (`not_before_attempt_at`).
 - **Revenue recognition.** A Micro payment is final only once its weekly
   settlement confirms on-chain. Until then it is accrued, not settled.
 
@@ -96,7 +104,7 @@ confirmed payment turns into money in your settlement wallet.
   payments — grouped per buyer, payee, token, 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 site (`not_before_attempt_at`).
+  3-day pre-debit notice window (`not_before_attempt_at`).
 - **Revenue recognition.** A Nano payment is final only once its monthly
   settlement confirms on-chain.
 
@@ -115,14 +123,18 @@ confirmed payment turns into money in your settlement wallet.
 - 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.
+- A `past_due` batch remains recorded until operator resolution or requeue, but
+  this does not guarantee collection from the buyer or payment to the provider.
 
 ### Rejected / no-charge behavior
 
 Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 
-- A buyer's wallet budget is consumed at the **gross amount** (your price plus
-  the protocol fee), held from the moment a request is accepted until its
-  settlement confirms.
+- A buyer's wallet budget reservation is consumed at the **gross amount** (your
+  price plus the protocol fee) from acceptance until settlement confirms. This
+  is a reservation against Siglume spending limits; it does not lock, escrow,
+  preserve, or guarantee the buyer's token balance, allowance, BudgetVault
+  authorization, or payment source.
 - If the buyer's budget, scope, or amount band does not allow a request, it is
   **rejected with no charge**: the request is not fulfilled, no amount is
   accrued, and nothing is added to a settlement. A buyer near their budget
@@ -137,10 +149,35 @@ Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 The cadence is fixed: **Micro settles weekly, Nano settles monthly**, and 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 site, and current retry policy
+period boundaries, roughly 3-day pre-debit notice window, and current retry policy
 above are the public behavior as of 2026-06-18. Treat the platform's statement
-status, `not_before_attempt_at`, and `fee_bps` response as authoritative rather
-than hard-coding local revenue recognition.
+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
+
+Micro / Nano fees are stored internally as decimal minor-unit values so
+sub-yen and sub-cent Nano fees are not silently rounded per usage event. The
+current settlement rule is:
+
+```text
+provider_usage_amount_minor = sum(provider price minor units for accepted usage)
+protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted usage)
+gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+buyer_debit_minor = ceil(gross_buyer_debit_minor)
+rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
+```
+
+Rounding happens once when the settlement batch is created, not per usage event.
+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. 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`.
 
 ## Statement APIs and Notices
 
@@ -154,14 +191,15 @@ Use [Micro / Nano Statements and Notices](./metered-statements.md) to integrate:
 - 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 site.
+- the fixed final notice plus close-plus-3-day debit window.
 
 ## SDK Behavior
 
 The SDK does not calculate merchant invoices or enforce plan limits locally.
 Instead, it exposes billing-related values returned by Siglume, including
-`fee_bps` on a payment requirement. This keeps merchant billing centralized in
-the Siglume platform and avoids stale client-side pricing logic.
+Standard Payment `fee_bps` on a payment requirement and Micro / Nano statement
+amount fields. This keeps merchant billing centralized in the Siglume platform
+and avoids stale client-side pricing logic.
 
 ## Supported Use Cases
 
@@ -179,4 +217,5 @@ The Siglume API and merchant registry may still expose the legacy `billing_plan`
 value `free` for the Launch tier. Treat `free` as a wire-compatibility key, not a
 public plan name. (Until 2026-06-12 the Launch plan included a free monthly
 allowance of 100 payments; that allowance has been retired — the platform
-`fee_bps` response is always the source of truth.)
+Standard `fee_bps` response and Micro / Nano statement amount fields are always
+the source of truth.)

package/docs/security.md

@@ -61,6 +61,11 @@ bare, lowercased origins and deduped. A return URL that is not on an allowed
 origin is rejected, so an attacker cannot point a session at an arbitrary
 redirect target.
 
+Production allowlist entries must use `https`. Development `http` entries are
+accepted only for `http://localhost`, `http://127.0.0.1`, or `http://[::1]`
+(with optional ports). Userinfo such as `https://user@shop.example.com` is
+rejected so an attacker cannot rely on origin-spoofing URL forms.
+
 For a Hosted Checkout session, Siglume authors the amount, currency, challenge,
 and return URLs server-side at session creation. The browser cannot tamper with
 the price or the redirect target, and the raw challenge is never exposed to the
@@ -159,3 +164,9 @@ a rejected request is never charged. Provider revenue for Micro and Nano remains
 unsettled until the aggregated on-chain settlement succeeds; Siglume does not
 advance or guarantee revenue when a buyer's balance, allowance, BudgetVault
 authorization, cap, or on-chain transaction fails.
+
+A Micro / Nano budget reservation is not a token lock, escrow, or payment
+guarantee. It reserves room against Siglume spending limits only. A later
+settlement can still fail if the buyer no longer has sufficient balance,
+allowance, BudgetVault authorization, or cap room; `past_due` records the issue
+but does not guarantee eventual collection or provider payment.