@siglume/direct-request-payment 0.3.6 → 0.4.0

package/docs/api-reference.md

@@ -4,6 +4,32 @@ The TypeScript package is `@siglume/direct-request-payment`. The Python package
 is `siglume-direct-request-payment` and imports as
 `siglume_direct_request_payment`.
 
+## Two Buyer Systems
+
+SDRP serves two kinds of buyer, and you integrate each differently. In both
+cases the buyer pays from a Siglume wallet (JPYC for JPY, USDC for USD) — not a
+card — and the merchant SDK never authenticates the buyer.
+
+- **Human web shopper → Hosted Checkout.** Call
+  [`createCheckoutSession`](#createcheckoutsessioninput--create_checkout_session)
+  on `DirectRequestPaymentMerchantClient` and redirect the shopper to the
+  returned `checkout_url`. The shopper signs into Siglume on the hosted page,
+  approves, and pays from their own wallet.
+- **AI agent / agent-to-agent (AtoA) → direct API / tools.** An autonomous
+  buyer agent pays through `DirectRequestPaymentClient` (your app holds the
+  buyer's Siglume JWT) or through the Siglume marketplace tool
+  `market_confirm_direct_payment_and_execute` (MCP). Agent payment 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. 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).
+
+In both systems the merchant fulfills on the same signed
+`direct_payment.confirmed` webhook. Hosted Checkout adds no new money movement
+and no new webhook.
+
 ## Environment Variables
 
 | Name | Used by | Purpose |
@@ -158,6 +184,12 @@ Input:
 - `billing_currency`: `JPY`; `USD` requires agreed USD/USDC billing terms
 - `webhook_callback_url`: HTTPS callback URL for signed payment events
 - `max_amount_minor`: optional billing mandate cap
+- `checkout_allowed_origins`: optional `string[]` return-URL origin allowlist for
+  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.
 
 Returns:
 
@@ -178,6 +210,97 @@ POST /v1/sdrp/direct-payments/merchants
 ```
 
 Creates or updates the merchant account for the authenticated merchant user.
+Accepts the optional `checkout_allowed_origins: string[]` return-URL origin
+allowlist described under `setupCheckout` above; the same normalization and
+webhook-origin auto-allow apply.
+
+### `createCheckoutSession(input)` / `create_checkout_session(...)`
+
+Creates a single-use, expiring Hosted Checkout session for a human web shopper
+and returns the URL to redirect them to. Requires the merchant's Siglume bearer
+token. The server authors the challenge from the merchant's challenge secret —
+the browser never sees or supplies it.
+
+Calls:
+
+```text
+POST /v1/sdrp/direct-payments/checkout-sessions
+```
+
+```ts
+const session = await merchant.createCheckoutSession({
+  merchant: "example_merchant",
+  amount_minor: 500,
+  currency: "JPY",
+  nonce: order.id,
+  success_url: "https://www.your-shop.com/thanks",
+  cancel_url: "https://www.your-shop.com/cart",
+  metadata: { order_id: order.id },
+});
+```
+
+```py
+session = merchant.create_checkout_session(
+    merchant="example_merchant",
+    amount_minor=500,
+    currency="JPY",
+    nonce=order["id"],
+    success_url="https://www.your-shop.com/thanks",
+    cancel_url="https://www.your-shop.com/cart",
+    metadata={"order_id": order["id"]},
+)
+```
+
+Input:
+
+- `merchant`: Siglume merchant key
+- `amount_minor`: positive integer in minor currency units (server-fixed; the
+  browser cannot change it)
+- `currency`: `JPY`, or `USD` when enabled for the merchant account
+- `nonce`: unique per order; must not contain `:`
+- `success_url`: return URL after a completed payment; must be on a registered
+  `checkout_allowed_origins` origin (or the webhook origin)
+- `cancel_url`: return URL after the shopper cancels; same origin rule
+- `metadata`: optional JSON object
+
+Returns:
+
+- `checkout_url`: hosted page to redirect the shopper to
+  (`https://siglume.com/pay/<session_id>`)
+- `session_id`
+- `challenge_hash`: store this on the order to map the later webhook back
+- `status`
+- `expires_at`: the session is single-use and expires (~30 minutes)
+
+### `getCheckoutSession(session_id)` / `get_checkout_session(session_id)`
+
+Returns the current status of a Hosted Checkout session. Useful if you want to
+show progress in your own UI; the signed `direct_payment.confirmed` webhook
+remains the source of truth for fulfillment. Never exposes the raw challenge or
+buyer PII.
+
+Calls:
+
+```text
+GET /v1/sdrp/direct-payments/checkout-sessions/{session_id}
+```
+
+Returns a session status object with:
+
+- `session_id`
+- `merchant`
+- `currency`
+- `token_symbol`
+- `amount_minor`
+- `status`: one of `open`, `authenticated`, `paid`, `expired`, `cancelled`,
+  `failed`
+- `challenge_hash`
+- `requirement_id`
+- `success_url`
+- `cancel_url`
+- `expires_at`
+- `paid_at`
+- `metadata_jsonb`
 
 ### `getMerchant(merchant)` / `get_merchant(merchant)`
 

package/docs/merchant-quickstart.md

@@ -20,6 +20,124 @@ 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.** 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
 
 Run setup from the merchant server, CI, or an integration agent with the
@@ -162,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/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.0",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",