@siglume/direct-request-payment 0.3.5 → 0.4.0

package/docs/merchant-quickstart.md

@@ -7,7 +7,7 @@ external merchant.
 
 - Merchant server: owns the order, amount, currency, challenge secret, webhook
   endpoint, and order fulfillment.
-- Buyer: owns the Siglume wallet that pays the DirectPaymentHub transaction.
+- Buyer: owns the Siglume wallet that pays the on-chain payment transaction.
 - Siglume: creates the payment requirement, prepares the wallet transaction,
   verifies the receipt, and emits signed webhooks.
 
@@ -15,9 +15,128 @@ 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 use the SDRP metered-payment server flow instead.
-Micro/Nano run a server-side meter gate before provider execution and settle
-later; they are not browser checkout requirements created by this merchant SDK.
+Micro Payment and Nano Payment are applied automatically by amount and settled on
+a weekly / monthly cadence (see [Pricing](./pricing.md#settlement-schedule)); they
+are not browser checkout requirements you create with this SDK. Their provider
+revenue remains unsettled until the later on-chain settlement succeeds.
+
+## Two Buyer Systems
+
+There are two ways a buyer reaches you, and you integrate each differently:
+
+- **Human web shopper → Hosted Checkout.** Create a checkout session and
+  redirect the shopper to the Siglume-hosted page (the
+  [section below](#hosted-checkout-human-web-shoppers)). This is the path that
+  resembles a Stripe-style hosted checkout.
+- **AI agent / agent-to-agent (AtoA) → direct API / tools.** An autonomous
+  buyer pays through `DirectRequestPaymentClient` or the marketplace tool
+  `market_confirm_direct_payment_and_execute`, as in sections 2-4 below.
+
+In both cases the buyer pays from a Siglume wallet (JPYC / USDC, not a card),
+the merchant SDK never authenticates the buyer, and you fulfill on the same
+`direct_payment.confirmed` webhook.
+
+## Hosted Checkout (Human Web Shoppers)
+
+When a person clicks "Pay with Siglume" on your site, create a session and
+redirect them to the returned `checkout_url`. They sign into Siglume on the
+hosted page, approve, and pay from their own wallet, then return to your
+`success_url`. Siglume fixes the amount, currency, challenge, and return URLs
+server-side, so the browser cannot tamper with the price or the redirect target.
+
+Register your return-URL origins once (open-redirect defense). The origin of
+your `webhook_callback_url` is auto-allowed in addition to these.
+
+TypeScript:
+
+```ts
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+});
+
+// Once, at setup: register the return-URL origin allowlist.
+await merchant.setupCheckout({
+  merchant: "example_merchant",
+  display_name: "Example Merchant",
+  billing_plan: "launch",
+  billing_currency: "JPY",
+  webhook_callback_url: "https://merchant.example/siglume/webhook",
+  checkout_allowed_origins: ["https://www.example.com"],
+});
+
+// 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
+  currency: "JPY",
+  nonce: order.id,              // unique per order
+  success_url: "https://www.example.com/thanks",
+  cancel_url: "https://www.example.com/cart",
+  metadata: { order_id: order.id },
+});
+
+await orders.update(order.id, {
+  siglume_challenge_hash: session.challenge_hash,
+  siglume_payment_status: "pending",
+});
+
+redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
+```
+
+Python:
+
+```py
+import os
+
+from siglume_direct_request_payment import DirectRequestPaymentMerchantClient
+
+merchant = DirectRequestPaymentMerchantClient(
+    auth_token=os.environ["SIGLUME_MERCHANT_AUTH_TOKEN"],
+)
+
+# Once, at setup: register the return-URL origin allowlist.
+merchant.setup_checkout(
+    merchant="example_merchant",
+    display_name="Example Merchant",
+    billing_plan="launch",
+    billing_currency="JPY",
+    webhook_callback_url="https://merchant.example/siglume/webhook",
+    checkout_allowed_origins=["https://www.example.com"],
+)
+
+# 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
+    currency="JPY",
+    nonce=order["id"],           # unique per order
+    success_url="https://www.example.com/thanks",
+    cancel_url="https://www.example.com/cart",
+    metadata={"order_id": order["id"]},
+)
+
+orders.update(
+    order["id"],
+    {
+        "siglume_challenge_hash": session["challenge_hash"],
+        "siglume_payment_status": "pending",
+    },
+)
+
+# Redirect the shopper to session["checkout_url"]
+# -> https://siglume.com/pay/<session_id>
+```
+
+Fulfill exactly as in [section 4](#4-fulfill-from-webhook): on the signed
+`direct_payment.confirmed` webhook, look up the order by `challenge_hash` and
+mark it paid once. The session is single-use and expires (~30 minutes); you can
+poll `getCheckoutSession` / `get_checkout_session` if you also want to show
+status in your own UI, but the webhook is the source of truth. Honest framing:
+the merchant plumbing integrates quickly, but human web payment still requires
+the shopper to have — or create — a Siglume wallet and pay from it; it is not a
+card-style "instant" checkout for first-time buyers.
 
 ## 1. Run Merchant Setup
 
@@ -42,7 +161,9 @@ const setup = await merchantClient.setupCheckout({
   max_amount_minor: 100000,
 });
 
-console.log(setup.env);
+// setup.env holds the merchant key plus the challenge and webhook secrets.
+// Store them in your server-side secret manager; do not log the secret values.
+console.log(`Configured merchant: ${setup.env.SIGLUME_DIRECT_PAYMENT_MERCHANT}`);
 ```
 
 Python:
@@ -65,7 +186,9 @@ setup = merchant_client.setup_checkout(
     max_amount_minor=100000,
 )
 
-print(setup["env"])
+# setup["env"] holds the merchant key plus the challenge and webhook secrets.
+# Persist them to your server-side secret store; do not log the secret values.
+print("Configured merchant:", setup["env"]["SIGLUME_DIRECT_PAYMENT_MERCHANT"])
 ```
 
 `setupCheckout` / `setup_checkout` performs:
@@ -157,6 +280,18 @@ The nonce must be unique per order payment attempt and must not contain `:`.
 
 ## 3. Buyer Creates and Pays the Requirement
 
+This is the AI agent / AtoA path: the buyer pays directly through
+`DirectRequestPaymentClient` (or the marketplace tool
+`market_confirm_direct_payment_and_execute`), rather than through Hosted
+Checkout. It assumes the buyer agent is **already connected to Siglume before
+the payment**: an AI client (Claude / ChatGPT / Cursor) connects through the
+Siglume MCP server (OAuth authorization with a consent screen), or a custom app
+holds the buyer's Siglume bearer token (JWT). Either way a Siglume
+authentication context is established first — the merchant SDK does not log the
+buyer in. Unattended runs are bounded by Siglume's approval gates / spending
+budgets (per-run / daily / monthly auto-pay budgets, or Works approval), not by
+the merchant.
+
 After the buyer authenticates with Siglume, create the payment requirement with
 the buyer's Siglume bearer token. Do not use a Developer Portal `cli_` API key
 or merchant API key here.

package/docs/pricing.md

@@ -26,13 +26,14 @@ 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. | Immediate on-chain split through DirectPaymentHub after payment confirmation |
-| JPY 50-500 / about USD 0.30-3.00 | Micro Payment | No selection. Applied automatically by amount. | USD 0.01 / Tx, about JPY 2 | Meter gate before provider execution; weekly delayed settlement |
-| Under JPY 1 to JPY 49 / under USD 0.01 to about USD 0.30 | Nano Payment | No selection. Applied automatically by amount. | USD 0.001 / usage, about JPY 0.2 | Meter gate before provider execution; monthly delayed 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 |
+| JPY 50-500 / about USD 0.30-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 1 to JPY 49 / under USD 0.01 to about 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)) |
 
-For Micro Payment and Nano Payment, the SDRP meter gate runs before provider
-execution. Budget or scope failures are recorded as `rejected_no_charge`; the
-provider API is not called and no pending provider revenue is created.
+Standard Payment settles per payment. Micro Payment and Nano Payment are
+aggregated and settled on a fixed weekly / monthly cadence — see
+[Settlement schedule](#settlement-schedule) for exactly when each band closes,
+when revenue becomes settled, and how rejected requests behave.
 
 USD pricing is the JPY tier converted at roughly 160 JPY/USD and rounded to
 clean price points that keep the same 1:3:10 tier ratio.
@@ -41,21 +42,95 @@ 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.
 
-The current Siglume API and merchant registry may still expose the internal
-`billing_plan` value `free` for the Launch tier. Treat `free` as an internal
-compatibility key, not the 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.)
-
-Per-payment fees are collected during payment settlement through the
-DirectPaymentHub split. The merchant receives the net amount after that fee.
-Monthly base fees are collected separately through the merchant billing mandate.
+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.
 
+## Settlement schedule
+
+Standard Payment, Micro Payment, and Nano Payment differ mainly in *when* a
+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 | Buyer settlement timezone Monday 00:00 to the next Monday 00:00; default timezone is UTC | After the week closes, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Nano Payment | Monthly | Buyer settlement timezone 1st 00:00 to the 1st of the next month 00:00; default timezone is UTC | After the month closes, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+
+### Micro weekly settlement
+
+- **Closing period.** Micro-band payments accrue across one calendar week:
+  Monday 00:00 to the following Monday 00:00 in the buyer settlement timezone.
+- **Timezone.** Period boundaries are evaluated in the buyer's configured
+  settlement timezone, defaulting to UTC, so different buyers can close on
+  slightly different local boundaries.
+- **Settlement.** After the week closes, Siglume aggregates that week's Micro
+  payments — grouped per buyer, payee, token, and period — into on-chain
+  settlement(s). Aggregation and payment run automatically on the next settlement
+  pass after the period closes; there is a short, platform-managed lag between
+  the close and the on-chain transaction.
+- **Revenue recognition.** A Micro payment is final only once its weekly
+  settlement confirms on-chain. Until then it is accrued, not settled.
+
+### Nano monthly settlement
+
+- **Closing period.** Nano-band payments accrue across one calendar month:
+  the 1st at 00:00 to the 1st of the next month at 00:00 in the buyer
+  settlement timezone.
+- **Timezone.** As with Micro, period boundaries use the buyer's configured
+  settlement timezone, defaulting to UTC.
+- **Settlement.** After the month closes, Siglume aggregates that month's Nano
+  payments — grouped per buyer, payee, token, and period — into on-chain
+  settlement(s), on the next settlement pass after the period closes.
+- **Revenue recognition.** A Nano payment is final only once its monthly
+  settlement confirms on-chain.
+
+### Failures, retries, and carry-over
+
+- Settlement is on-chain, so there are no banking-holiday gaps — periods close on
+  the calendar boundary regardless of weekday.
+- If a settlement fails because of insufficient balance, insufficient allowance,
+  inactive BudgetVault authorization, a per-payout cap, or an on-chain failure,
+  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.
+- 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.
+
+### 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.
+- 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
+  ceiling can have a request rejected even though earlier requests in the same
+  period succeeded.
+- Treat Siglume's settled status and webhooks as the source of truth for what has
+  actually been paid.
+
+### What is fixed vs platform-managed
+
+The cadence is fixed: **Micro settles weekly, Nano settles monthly**, and a
+payment is final only after its on-chain settlement confirms. The buyer-timezone
+period boundaries and the current retry policy above are the public behavior as
+of 2026-06-18. The scheduler lag between a period close and the on-chain
+transaction is platform-managed; treat the platform's settlement status and
+`fee_bps` response as authoritative rather than hard-coding local revenue
+recognition.
+
 ## SDK Behavior
 
 The SDK does not calculate merchant invoices or enforce plan limits locally.
@@ -72,3 +147,11 @@ The trial pricing is intended for:
 - Membership services
 - Paid API access
 - Scheduled autopay for external merchant workflows
+
+## Compatibility note
+
+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.)

package/docs/security.md

@@ -49,6 +49,23 @@ autopay approval tag; it does not itself limit occurrences to once per day.
 Scheduled autopay execution is bounded by the buyer-approved per-run, daily, and
 monthly auto-pay budget.
 
+## Hosted Checkout Return URLs
+
+Hosted Checkout adds a return-URL origin allowlist as open-redirect defense.
+Register your allowed origins once via `checkout_allowed_origins` on
+`setupCheckout` / `setupMerchant`. A checkout session's `success_url` and
+`cancel_url` must be on a registered origin; the origin of your
+`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. A return URL that is not on an allowed
+origin is rejected, so an attacker cannot point a session at an arbitrary
+redirect target.
+
+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
+browser or returned by `getCheckoutSession`.
+
 ## Do Not Trust Browser Amounts
 
 The merchant server owns:
@@ -106,9 +123,14 @@ Direct Request Payment is not:
 - escrow
 - a platform balance
 - a card payment fallback
-- the Micro Payment or Nano Payment meter
 
-It is a Standard Payment wallet gate backed by an on-chain receipt. Micro
-Payment and Nano Payment are SDRP amount bands with internal-meter,
-delayed-settlement behavior; they must fail closed before provider API
-execution when the buyer's metered budget, scope, or amount band is invalid.
+Each payment is an individual wallet payment backed by an on-chain receipt. Small
+payments in the Micro and Nano amount bands are aggregated and settled on a
+weekly / monthly cadence instead of one transaction at a time (see the
+[pricing guide](./pricing.md#settlement-schedule)), but they are still wallet
+payments, not a stored balance. Before a small payment is fulfilled, Siglume
+checks the buyer's wallet budget and fails closed when it is invalid, so a
+rejected request is never charged. Provider revenue for Micro and Nano remains
+unsettled until the weekly or monthly 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.

package/examples/express-checkout.ts

@@ -99,8 +99,10 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
 }));
 
 app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
-  const message = error instanceof Error ? error.message : "internal_error";
-  res.status(500).json({ error: message });
+  // Log the detail server-side; never return raw error messages to the client —
+  // a payment error can otherwise leak internal API details or configuration.
+  console.error("checkout error:", error);
+  res.status(500).json({ error: "internal_error" });
 });
 
 app.listen(port);

package/examples/setup-merchant.ts

@@ -14,4 +14,12 @@ const setup = await merchant.setupCheckout({
   create_webhook_subscription: Boolean(process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL),
 });
 
-console.log(JSON.stringify(setup, null, 2));
+// setup.env contains the merchant key PLUS the challenge and webhook secrets.
+// Store these in your server-side secret manager. Never log the secret values —
+// log only non-secret confirmation.
+const env = setup.env ?? {};
+console.log("Merchant configured:", {
+  merchant: env.SIGLUME_DIRECT_PAYMENT_MERCHANT,
+  challenge_secret: env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET ? "****" : undefined,
+  webhook_secret: env.SIGLUME_WEBHOOK_SECRET ? "****" : undefined,
+});

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
+    "sdrp",
+    "direct-request-payment",
     "payment",
-    "checkout",
-    "external-402",
+    "micropayments",
+    "metered-billing",
     "wallet",
+    "jpyc",
+    "usdc",
+    "checkout",
     "sdk"
   ],
   "license": "MIT",