@siglume/direct-request-payment 0.4.8 → 0.4.10

package/docs/announcement-ja.md

@@ -8,6 +8,8 @@ Siglume Direct Request Payment 向けの外部事業者用SDKを公開しまし
 
 > **Beta / サーバーロールアウト中**: Hosted Checkout はアカウントごとに段階提供中です。未提供アカウントでは `createCheckoutSession(...)` / `getCheckoutSession(...)` が `HostedCheckoutNotAvailableError` を返します。生の 404/409 をそのまま利用者へ見せず、提供開始まで既存の agent/API 経路を利用してください。
 
+> **対応チェーン**: 現在の公開ベータは **Polygon PoS 上の JPYC / USDC 精算のみ** に対応しています。マルチチェーン、チェーン選択、クロスチェーン精算、複数の merchant settlement wallet、決済ごとの settlement wallet override、分割・マルチウォレット課金には対応していません。
+
 このSDKは、外部EC、予約サービス、会員制サービス、有料API、scheduled autopay などで、SDRP の Standard Payment / 通常決済を自社プロダクトに組み込むためのSDKです。
 
 ## できること

package/docs/api-reference.md

@@ -4,6 +4,14 @@ The TypeScript package is `@siglume/direct-request-payment`. The Python package
 is `siglume-direct-request-payment` and imports as
 `siglume_direct_request_payment`.
 
+## Current Public Beta Scope
+
+SDRP currently settles JPYC / USDC on **Polygon PoS only**. The public SDK does
+not expose chain selection, cross-chain payment, multiple merchant settlement
+wallets, per-payment settlement-wallet overrides, or split / multi-wallet
+charging. Route each payment through the buyer's Siglume wallet and the merchant
+account's configured Siglume settlement wallet.
+
 ## Two Buyer Systems
 
 SDRP serves two kinds of buyer, and you integrate each differently. In both
@@ -28,9 +36,9 @@ card — and the merchant SDK never authenticates the buyer.
 
 In both systems the merchant handles the same signed `direct_payment.confirmed`
 webhook. Hosted Checkout adds no new money movement and no new webhook. Inspect
-`pricing_band`, `finality`, and `settlement_status`: Standard can be marked paid
-only after settled per-payment finality, while Micro / Nano usage is accepted
-before the later aggregated settlement.
+`pricing_band`, `settlement_cadence`, `finality`, and `settlement_status`:
+Standard can be marked paid only after settled per-payment finality, while Micro
+/ Nano usage is accepted before the later aggregated settlement.
 
 ## Environment Variables
 
@@ -466,8 +474,8 @@ Returns a `HostedCheckoutSession` status object with:
 - `authenticated_at` (nullable; set when the shopper signs into Siglume)
 - `paid_at` (nullable; set when Hosted Checkout has accepted the wallet
   payment flow. For Micro / Nano, this is not the same as final provider
-  settlement; use `pricing_band`, `finality`, `settlement_status`, and the
-  statement APIs.)
+  settlement; use `pricing_band`, `settlement_cadence`, `finality`,
+  `settlement_status`, and the statement APIs.)
 - `cancelled_at` (nullable; set when the shopper cancels)
 - `created_at` (nullable)
 - `metadata_jsonb`
@@ -971,15 +979,18 @@ requirements; keep accepting `event.data.request_hash` for historical payloads.
 Recommended branch: call `classifyDirectPaymentConfirmation(event)` /
 `classify_direct_payment_confirmation(event)` and switch on `kind`:
 
-- `metered_batch_settled`: no order `challenge_hash` is expected. Reconcile the
-  batch with the returned non-empty `settlement_batch_id`, `chain_receipt_id`,
-  and `usage_event_digest`.
+- `metered_batch_settled`: no order `challenge_hash` is expected. This requires
+  Micro / Nano pricing, the matching settlement cadence (`micro` -> `weekly`,
+  `nano` -> `monthly`), `finality === "aggregated_onchain_settlement"`, settled
+  status, and non-empty `settlement_batch_id`, `chain_receipt_id`, and
+  `usage_event_digest`. Reconcile the batch with those returned identifiers.
 - `standard_settled`: mark the mapped order paid once. This requires Standard
   pricing, per-payment on-chain finality, settled status, non-empty
   `requirement_id`, non-empty `challenge_hash`, and non-empty
   `chain_receipt_id`.
 - `metered_usage_accepted`: treat the usage as accepted but unsettled. This
   requires Micro / Nano pricing, `finality === "aggregated_onchain_settlement"`,
+  the matching settlement cadence (`micro` -> `weekly`, `nano` -> `monthly`),
   `settlement_status === "pending_settlement"`, non-empty `requirement_id`, and
   non-empty `challenge_hash`. SDRP merchant setup and terms assume the merchant
   accepts this delayed aggregated settlement model for Micro / Nano amount
@@ -998,9 +1009,10 @@ Classifies a parsed `direct_payment.confirmed` event into:
 - `metered_batch_settled`
 - `unknown`
 
-The classifier is fail-closed: missing finality, missing settlement status,
-empty challenge hashes, empty requirement ids, and empty settlement batch
-receipt identifiers return `kind: "unknown"` with a machine-readable `reason`.
+The classifier is fail-closed: missing finality, missing pricing band, mismatched
+Micro / Nano settlement cadence, missing settlement status, empty challenge
+hashes, empty requirement ids, and empty settlement batch receipt identifiers
+return `kind: "unknown"` with a machine-readable `reason`.
 
 ### `verifyDirectRequestPaymentWebhook(secret, body, signature_header, options)` / `verify_direct_request_payment_webhook(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
 

package/docs/merchant-quickstart.md

@@ -14,6 +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.
 
+**Current public beta scope.** SDRP currently settles JPYC / USDC on **Polygon
+PoS only**. The public SDK does not expose chain selection, cross-chain payment,
+multiple merchant settlement wallets, per-payment settlement-wallet override, or
+split / multi-wallet charging. Route each payment through the buyer's Siglume
+wallet and the merchant account's configured Siglume settlement wallet.
+
 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 manually

package/docs/metered-statements.md

@@ -461,8 +461,8 @@ separate from settled revenue.
 
 - Your order fulfillment is idempotent by order id and requirement id.
 - Standard Payment fulfillment still uses verified `direct_payment.confirmed`
-  only when `pricing_band`, `finality`, and `settlement_status` show settled
-  per-payment finality.
+  only when `pricing_band`, `settlement_cadence`, `finality`, and
+  `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 support UI shows sanitized failure fields and `support_reference`.

package/docs/pricing.md

@@ -24,6 +24,11 @@ percentage (the payment fee column below) is identical in both currencies. Only
 the flat amounts — the monthly base fee and the per-payment minimum fee — are
 quoted per currency.
 
+Current public beta settlement is on **Polygon PoS only**. The public SDK does
+not expose chain selection, cross-chain payment, multiple merchant settlement
+wallets, per-payment settlement-wallet overrides, or split / multi-wallet
+charging.
+
 ## Pricing Table
 
 | Payment amount | Applied automatically | What you select | Fee | Settlement |
@@ -62,8 +67,10 @@ If no paid plan is selected during merchant setup, the merchant account uses the
 Launch plan. A merchant billing mandate is still required before accepting
 payments so Siglume can collect the monthly base fee automatically.
 
-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
+Standard Payment fees are deducted at settlement, so the merchant receives the
+net amount for each Standard payment. Micro / Nano protocol fees are different:
+they are added to the buyer debit, are reported as `protocol_fee_minor`, and are
+not provider revenue. Monthly base fees are collected separately through the
 merchant billing mandate.
 
 The same Standard Payment percentage schedule applies in JPY and USD. For

package/package.json

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