@siglume/direct-request-payment 0.4.3 → 0.4.5

package/docs/api-reference.md

@@ -36,7 +36,7 @@ and no new webhook.
 | --- | --- | --- |
 | `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` | merchant server | HMAC secret for order challenges |
 | `SIGLUME_MERCHANT_AUTH_TOKEN` | merchant setup helper | merchant Siglume bearer token for self-service setup |
-| `SIGLUME_AUTH_TOKEN` | buyer payment helper | buyer Siglume bearer token for API calls |
+| `SIGLUME_AUTH_TOKEN` | user-authenticated helper | buyer Siglume bearer token for payment / buyer statements, or provider Siglume bearer token for provider statements |
 | `SIGLUME_API_BASE` | optional | API base URL override; defaults to `https://siglume.com/v1` |
 | `SIGLUME_WEBHOOK_SECRET` | merchant server | webhook signing secret returned as `whsec_...` |
 
@@ -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",
@@ -495,8 +505,10 @@ or rotation.
 ## `DirectRequestPaymentClient`
 
 Thin wrapper around the current Siglume Direct Request Payment HTTP contract.
-Use it with the authenticated buyer's Siglume bearer token. Developer Portal
-`cli_` API keys are not accepted by these buyer-authenticated routes.
+Use it with the authenticated Siglume user bearer token for the route you call:
+buyer tokens for buyer payment and buyer statement routes, provider / merchant
+tokens for provider statement routes. Developer Portal `cli_` API keys are not
+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
@@ -505,19 +517,21 @@ 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({
-  auth_token: buyerSiglumeBearerToken,
+  auth_token: buyerOrProviderSiglumeBearerToken,
   base_url: "https://siglume.com/v1",
 });
 ```
 
 ```py
 siglume = DirectRequestPaymentClient(
-    auth_token=buyer_siglume_bearer_token,
+    auth_token=buyer_or_provider_siglume_bearer_token,
     base_url="https://siglume.com/v1",
 )
 ```
@@ -544,6 +558,29 @@ Input:
 - `allowance_amount_minor`: optional positive integer
 - `metadata`: optional JSON object
 
+There is no public `idempotency_key` field on this requirement-create request.
+For one-time external checkout, idempotency is the merchant-signed challenge
+nonce: derive `nonce` from a durable order payment attempt, store the returned
+`challenge_hash`, and use `request_hash_v2` when you need a canonical machine
+hash for the same payment request. Do not retry the same order by minting a new
+nonce unless you intentionally want a new payment attempt.
+
+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 +677,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 +704,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 +727,15 @@ 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`, `limit`, and `cursor`, and
+returns `{items, next_cursor}`. When `next_cursor` is non-null, pass it back as
+`cursor` to fetch the next page.
+
 Buyer-facing amount names are centered on the debit:
 
 - `estimated_buyer_debit_minor`
@@ -711,16 +760,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 +785,19 @@ 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`, `limit`, and `cursor`. Detail accepts
+`settlement_batch_id`, plus optional `listing_id` and `capability_key`. List
+methods return `{items, next_cursor}`. When `next_cursor` is non-null, pass it
+back as `cursor` to fetch the next page.
+
 Provider-facing amount names:
 
 - `provider_receivable_minor`
@@ -792,6 +854,13 @@ metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end
 ```
 
 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`.
+
+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,
+use `Decimal` for accounting and reconciliation.
 
 ## Payload Builders
 
@@ -862,8 +931,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 +988,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,37 @@ 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
+```
+
+For low-count Nano batches, the ceiling can make the effective buyer burden per
+usage higher than the headline "USD 0.001 / usage" protocol fee. The protocol
+fee remains the decimal statement amount; the extra integer-minor-unit
+adjustment is recorded as `rounding_delta_minor` on the settlement batch.
+
+`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`.
+
+Micro / Nano amount fields are decimal minor-unit strings. JavaScript
+integrations should aggregate them with a decimal library, not `number`. Python
+integrations should use `Decimal` for accounting.
+
 ### Usage Events
 
 ```text
@@ -103,8 +132,12 @@ Query parameters:
 - `plan_type`: `micro` or `nano`
 - `token_symbol`: `JPYC` or `USDC`
 - `status`: for example `pending_settlement`, `settled`, `failed_chargeable`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `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
@@ -125,8 +158,12 @@ Query parameters:
 - `token_symbol`: `JPYC` or `USDC`
 - `status`: `notice_pending`, `ready`, `submitted`, `settled`, `failed`,
   `past_due`, or `notice_delivery_failed`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `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 +194,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",
+});
 ```
 
-Raw HTTP / Python:
+Python:
+
+```py
+provider_summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
+```
+
+Raw HTTP:
 
 ```bash
 curl https://siglume.com/v1/sdrp/metered/provider/summary?plan_type=micro\&token_symbol=JPYC \
@@ -208,8 +244,12 @@ Query parameters:
 - `status`
 - `listing_id`
 - `capability_key`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 500
 
+SDK methods: `listProviderUsageEvents(...)` /
+`list_provider_usage_events(...)`. They return `{items, next_cursor}`.
+
 Provider usage event fields include:
 
 - `provider_receivable_minor`
@@ -238,10 +278,15 @@ Query parameters for the list endpoint:
 - `status`
 - `listing_id`
 - `capability_key`
+- `cursor`: pass the previous response's `next_cursor` to fetch the next page
 - `limit`: 1 to 200
 
 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 |
@@ -285,6 +330,10 @@ metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end
 ```
 
 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.
 
 ## Notifications
 
@@ -326,6 +375,45 @@ 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. |
+
+Future platform versions may add explicit terminal states such as
+`closed_unpaid`, `uncollectible`, or `written_off`. Treat unknown terminal
+settlement states as not settled unless `status === "settled"` and
+`chain_receipt_id` is present.
+
 ## Operational Recipes
 
 ### "How much did we use this week or month?"