@siglume/direct-request-payment 0.3.6 → 0.4.1

package/docs/merchant-quickstart.md

@@ -20,6 +20,128 @@ a weekly / monthly cadence (see [Pricing](./pricing.md#settlement-schedule)); th
 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 (Beta; server rollout in progress).** 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)
+
+**Beta / server rollout:** Hosted Checkout is rolling out account by account.
+Some merchant accounts may not have the server endpoint enabled yet. The SDK
+raises `HostedCheckoutNotAvailableError` for rollout 404/409 responses.
+
+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
 
 Run setup from the merchant server, CI, or an integration agent with the
@@ -162,6 +284,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

@@ -59,34 +59,38 @@ 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 Payment | Weekly | Fixed weekly slot assigned per account | After the period closes, after the final notice and an approximately 3-day pre-debit notice site, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Nano Payment | Monthly | Fixed monthly slot assigned per account | After the period closes, after the final notice and an approximately 3-day pre-debit notice site, 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.
+- **Closing period.** Micro-band payments accrue across one weekly period. The
+  specific closing weekday and time are assigned as a fixed slot per account to
+  spread settlement load.
 - **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 timezone, defaulting to UTC. Assigned slots are persisted and are
+  not recalculated on the fly.
 - **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.
+  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`).
 - **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.
+- **Closing period.** Nano-band payments accrue across one monthly period. The
+  specific closing day and time are assigned as a fixed slot per account to
+  spread settlement load.
 - **Timezone.** As with Micro, period boundaries use the buyer's configured
-  settlement timezone, defaulting to UTC.
+  settlement timezone, defaulting to UTC. Assigned slots are persisted and are
+  not recalculated on the fly.
 - **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.
+  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`).
 - **Revenue recognition.** A Nano payment is final only once its monthly
   settlement confirms on-chain.
 

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:

package/package.json

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