@siglume/direct-request-payment 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.3.0 - 2026-06-12
+
+Recurring payment approval release.
+
+- Added recurring (subscription / scheduled autopay) merchant approval helpers
+  in TypeScript (`createDirectRequestPaymentRecurringChallenge`,
+  `createDirectRequestPaymentRecurringChallengeSignature`,
+  `verifyDirectRequestPaymentRecurringChallenge`) and Python
+  (`create_direct_request_payment_recurring_challenge`,
+  `create_direct_request_payment_recurring_challenge_signature`,
+  `verify_direct_request_payment_recurring_challenge`).
+- Recurring approvals use a new single-use challenge scheme
+  (`siglume-external-402-recurring-v1`) with the cadence (`monthly` for
+  subscriptions, `daily` for scheduled autopay) bound into the HMAC, so
+  one-time checkout challenges and recurring approvals can never be replayed
+  as each other.
+- Documented the recurring payment flow (subscription and scheduled autopay)
+  in the README.
+- Updated pricing docs: the Launch plan's free monthly allowance of 100
+  payments is retired — Launch is now a flat 1.8% payment fee; the per-payment
+  minimum fee is JPY 30 (USD merchants: USD 0.20); JPY/JPYC and USD/USDC
+  settlement are both documented as first-class.
+
+## 0.2.0 - 2026-06-12
+
+Merchant self-service setup release.
+
+- Added TypeScript `DirectRequestPaymentMerchantClient` and Python
+  `DirectRequestPaymentMerchantClient`.
+- Added `setupCheckout` / `setup_checkout` to claim a merchant key, prepare a
+  billing mandate, and create a webhook subscription from the SDK.
+- Added challenge secret rotation, merchant status lookup, billing mandate
+  preparation, and webhook subscription helpers.
+- Updated docs to remove manual onboarding assumptions and clarify merchant JWT
+  vs buyer JWT responsibilities.
+
+## 0.1.0 - 2026-06-11
+
+Initial public release.
+
+- Published TypeScript/JavaScript SDK as `@siglume/direct-request-payment`.
+- Published Python SDK as `siglume-direct-request-payment`.
+- Added merchant challenge helpers, buyer-authenticated Direct Request Payment
+  client methods, prepared transaction payload helpers, and webhook signature
+  verification helpers.
+- Documented Launch, Starter, Growth, and Pro trial pricing.
+- Documented the distinction from `@siglume/api-sdk` and Developer Portal
+  `cli_` API keys.

package/README.md

@@ -1,5 +1,8 @@
 # @siglume/direct-request-payment
 
+[![npm version](https://img.shields.io/npm/v/@siglume/direct-request-payment.svg)](https://www.npmjs.com/package/@siglume/direct-request-payment)
+[![PyPI version](https://img.shields.io/pypi/v/siglume-direct-request-payment.svg)](https://pypi.org/project/siglume-direct-request-payment/)
+
 Merchant SDK for Siglume Direct Request Payment checkout integrations.
 
 Use this package when an external EC site, booking service, membership service,
@@ -12,18 +15,34 @@ This SDK is intentionally separate from `@siglume/api-sdk`:
 - `@siglume/direct-request-payment` is for external merchants integrating
   Siglume Direct Request Payment into their own checkout.
 
-## Install
-
-```bash
-npm install @siglume/direct-request-payment
-```
-
-```bash
-pip install siglume-direct-request-payment
-```
-
-Node.js 18 or later is required for the TypeScript SDK. Python 3.11 or later is
-required for the Python SDK.
+## What This SDK Covers
+
+- merchant self-service setup with a Siglume merchant JWT
+- challenge secret creation and rotation
+- merchant billing mandate preparation
+- webhook subscription creation
+- merchant-signed payment challenges
+- buyer-authenticated payment requirement creation
+- prepared wallet transaction execution payloads
+- payment requirement verification
+- signed webhook verification
+
+It does not custody funds or manage customer wallets. Merchant setup runs through
+Siglume APIs with the merchant's Siglume JWT; buyer payment creation runs with
+the buyer's Siglume JWT.
+
+## Install
+
+```bash
+npm install @siglume/direct-request-payment
+```
+
+```bash
+pip install siglume-direct-request-payment
+```
+
+Node.js 18 or later is required for the TypeScript SDK. Python 3.11 or later is
+required for the Python SDK.
 
 ## Current Platform Contract
 
@@ -36,8 +55,14 @@ context. Your merchant server must not use a merchant secret or API key to
 charge a customer wallet. The merchant server creates the signed challenge; the
 buyer-facing Siglume payment flow creates and pays the requirement.
 
-`DirectRequestPaymentClient` requires the buyer's Siglume bearer token. Do not
-use a Developer Portal `cli_` API key with this package.
+`DirectRequestPaymentMerchantClient` requires the merchant's Siglume bearer
+token for setup. `DirectRequestPaymentClient` requires the buyer's Siglume
+bearer token for payment requirements. Do not use a Developer Portal `cli_` API
+key with this package.
+
+Current HTTP endpoints live under Siglume's market/API Store route namespace for
+compatibility with the existing platform contract. That does not make this SDK an
+API Store publishing SDK.
 
 ## Trial Pricing
 
@@ -45,28 +70,91 @@ Siglume Direct Request Payment is currently offered with trial-phase merchant
 pricing designed for small EC sites, booking services, membership services, paid
 APIs, and agent-to-agent payment experiments.
 
-| Plan | Monthly fee | Payment fee |
-| --- | ---: | ---: |
-| Launch | JPY 0 | 0% through 100 payments/month, then 1.8% |
-| Starter | JPY 980 | 1.0% |
-| Growth | JPY 2,980 | 0.7% |
-| Pro | JPY 9,800 | 0.5% |
+Both launch settlement currencies are first-class: JPY settled in JPYC, and USD
+settled in USDC. A merchant settles in one currency, chosen at onboarding. The
+settlement fee percentage is identical in both currencies; only the flat
+amounts differ.
 
-The minimum fee is JPY 3 for each fee-bearing payment, including Launch-plan
-payments after the included monthly allowance. A merchant billing mandate is
-required before accepting payments, even on the Launch plan. The API and merchant
-registry may still expose the internal plan key `free` for this tier. See
-[docs/pricing.md](./docs/pricing.md) for details.
+| Plan | Monthly fee (JPY / USD) | Payment fee |
+| --- | ---: | ---: |
+| Launch | JPY 0 / USD 0 | 1.8% |
+| Starter | JPY 980 / USD 6.00 | 1.0% |
+| Growth | JPY 2,980 / USD 18.00 | 0.7% |
+| Pro | JPY 9,800 / USD 60.00 | 0.5% |
+
+Every payment is fee-bearing at the plan rate. The minimum fee is JPY 30
+(USD merchants: USD 0.20) per payment — it recovers the per-payment settlement
+cost (an on-chain signature plus network gas) on small payments; the percentage
+rate applies on larger payments. A merchant billing
+mandate is required before accepting payments, even on the Launch plan. The API
+and merchant registry may still expose the internal plan key `free` for this
+tier. See [docs/pricing.md](./docs/pricing.md) for details.
 
 Per-payment fees are deducted at payment settlement time, so the merchant
 receives the net amount. Monthly base fees are collected through the merchant
-billing mandate. The listed public pricing is JPY-denominated; USD/USDC merchant
-billing requires separately agreed terms.
+billing mandate. `fee_bps` returned on a payment requirement is the authoritative
+per-payment rate for that payment in the merchant's settlement currency.
+
+## Merchant Setup: One SDK Call
+
+Run this once from the merchant server or an integration agent with the
+merchant's Siglume JWT. It reserves the merchant key, creates the challenge
+secret, prepares the billing mandate, and creates the webhook subscription.
+
+```ts
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+});
+
+const setup = await merchant.setupCheckout({
+  merchant: "example_merchant",
+  display_name: "Example Merchant",
+  billing_plan: "launch",
+  billing_currency: "JPY",
+  webhook_callback_url: "https://merchant.example/siglume/webhook",
+  max_amount_minor: 100000,
+});
+
+console.log(setup.env);
+// {
+//   SIGLUME_DIRECT_PAYMENT_MERCHANT: "example_merchant",
+//   SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET: "edrp_...",
+//   SIGLUME_WEBHOOK_SECRET: "whsec_..."
+// }
+```
+
+```py
+import os
+
+from siglume_direct_request_payment import DirectRequestPaymentMerchantClient
+
+merchant = DirectRequestPaymentMerchantClient(
+    auth_token=os.environ["SIGLUME_MERCHANT_AUTH_TOKEN"],
+)
+
+setup = merchant.setup_checkout(
+    merchant="example_merchant",
+    display_name="Example Merchant",
+    billing_plan="launch",
+    billing_currency="JPY",
+    webhook_callback_url="https://merchant.example/siglume/webhook",
+    max_amount_minor=100000,
+)
+
+print(setup["env"])
+```
+
+Store returned secrets on the merchant server. `challenge_secret` and
+`signing_secret` are returned only when they are created or rotated. If a billing
+mandate response requires wallet approval, complete that Siglume wallet step
+before accepting production payments.
 
 ## Merchant Server: Create a Challenge
 
-```ts
-import { createDirectRequestPaymentChallenge } from "@siglume/direct-request-payment";
+```ts
+import { createDirectRequestPaymentChallenge } from "@siglume/direct-request-payment";
 
 const challenge = await createDirectRequestPaymentChallenge({
   merchant: "example_merchant",
@@ -78,26 +166,26 @@ const challenge = await createDirectRequestPaymentChallenge({
 
 // Return only challenge.challenge to the buyer-facing checkout.
 // Never return the challenge secret to the browser.
-console.log(challenge.challenge);
-```
-
-```py
-import os
-
-from siglume_direct_request_payment import create_direct_request_payment_challenge
-
-challenge = create_direct_request_payment_challenge(
-    merchant="example_merchant",
-    amount_minor=1200,
-    currency="JPY",
-    secret=os.environ["SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET"],
-    nonce="order_123-attempt_1",
-)
-
-print(challenge["challenge"])
-```
-
-The signed challenge binds:
+console.log(challenge.challenge);
+```
+
+```py
+import os
+
+from siglume_direct_request_payment import create_direct_request_payment_challenge
+
+challenge = create_direct_request_payment_challenge(
+    merchant="example_merchant",
+    amount_minor=1200,
+    currency="JPY",
+    secret=os.environ["SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET"],
+    nonce="order_123-attempt_1",
+)
+
+print(challenge["challenge"])
+```
+
+The signed challenge binds:
 
 - merchant key
 - amount in minor units
@@ -114,8 +202,8 @@ Use `DirectRequestPaymentClient` only with the authenticated buyer's Siglume
 bearer token. `SIGLUME_AUTH_TOKEN` may be used in server-side payment-confirmation
 helpers; `SIGLUME_API_KEY` and Developer Portal `cli_` keys are not accepted.
 
-```ts
-import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";
+```ts
+import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";
 
 const siglume = new DirectRequestPaymentClient({
   auth_token: buyerSiglumeBearerToken,
@@ -142,37 +230,103 @@ const verified = await siglume.verifyPaymentRequirement(requirement.requirement_
   await_finality: false,
 });
 
-console.log(verified.status);
-```
-
-```py
-from siglume_direct_request_payment import DirectRequestPaymentClient
-
-siglume = DirectRequestPaymentClient(auth_token=buyer_siglume_bearer_token)
-
-requirement = siglume.create_payment_requirement(
-    merchant="example_merchant",
-    amount_minor=1200,
-    currency="JPY",
-    challenge=challenge_from_merchant_server,
-)
-
-if requirement.get("approve_transaction_request"):
-    siglume.execute_allowance_transaction(requirement, await_finality=True)
-
-payment = siglume.execute_payment_transaction(requirement, await_finality=True)
-receipt_id = str((payment.get("receipt") or {}).get("receipt_id") or "")
-
-verified = siglume.verify_payment_requirement(
-    requirement["requirement_id"],
-    receipt_id=receipt_id,
-    await_finality=False,
-)
-
-print(verified["status"])
-```
-
-## Webhooks
+console.log(verified.status);
+```
+
+```py
+from siglume_direct_request_payment import DirectRequestPaymentClient
+
+siglume = DirectRequestPaymentClient(auth_token=buyer_siglume_bearer_token)
+
+requirement = siglume.create_payment_requirement(
+    merchant="example_merchant",
+    amount_minor=1200,
+    currency="JPY",
+    challenge=challenge_from_merchant_server,
+)
+
+if requirement.get("approve_transaction_request"):
+    siglume.execute_allowance_transaction(requirement, await_finality=True)
+
+payment = siglume.execute_payment_transaction(requirement, await_finality=True)
+receipt_id = str((payment.get("receipt") or {}).get("receipt_id") or "")
+
+verified = siglume.verify_payment_requirement(
+    requirement["requirement_id"],
+    receipt_id=receipt_id,
+    await_finality=False,
+)
+
+print(verified["status"])
+```
+
+## Recurring Payments: Subscription and Scheduled Autopay
+
+Beyond one-time checkout, a buyer can authorize recurring payments. The merchant
+approves the price and cadence ONCE by signing a recurring challenge (a distinct
+scheme, so one-time challenges and recurring approvals can never be replayed as
+each other); after that, recurring charges are challenge-free by design — the
+buyer's on-chain payment mandate (frozen payee, amount cap, cadence) is the
+per-charge integrity check.
+
+- **Subscription** (`cadence: "monthly"`): Siglume charges the buyer's wallet
+  monthly and pays your merchant wallet automatically. First month is charged at
+  setup. The buyer can cancel from their Siglume wallet at any time.
+- **Scheduled autopay** (`cadence: "daily"`): the buyer authorizes at most one
+  charge per day at a fixed amount and hands you a `schedule_token`; YOUR
+  scheduler triggers each occurrence with that token.
+
+```ts
+import { createDirectRequestPaymentRecurringChallenge } from "@siglume/direct-request-payment";
+
+// Merchant server: approve a JPY 980 monthly subscription once.
+const recurring = await createDirectRequestPaymentRecurringChallenge({
+  merchant: "example_merchant",
+  amount_minor: 980,
+  currency: "JPY",
+  cadence: "monthly",
+  secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
+  nonce: "subscription_setup_4711",
+});
+
+// Hand recurring.challenge to the buyer-facing page. The buyer creates the
+// subscription with their Siglume token:
+//   POST /v1/market/api-store/direct-payments/subscriptions
+//   { merchant, amount_minor, currency, cadence: "monthly", challenge }
+// For scheduled autopay, the buyer instead creates a scheduled auto-pay
+// authorization (mode: "external_402") and gives you the schedule_token.
+```
+
+```py
+import os
+
+from siglume_direct_request_payment import create_direct_request_payment_recurring_challenge
+
+# Merchant server: approve a JPY 980 monthly subscription once.
+recurring = create_direct_request_payment_recurring_challenge(
+    merchant="example_merchant",
+    amount_minor=980,
+    currency="JPY",
+    cadence="monthly",
+    secret=os.environ["SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET"],
+    nonce="subscription_setup_4711",
+)
+
+# Hand recurring["challenge"] to the buyer-facing page, as in the TS example.
+print(recurring["challenge"])
+```
+
+Each recurring challenge is single-use: it authorizes exactly one subscription
+or schedule, bound to the first buyer who redeems it. Issue a fresh challenge
+per setup. The platform fee on recurring charges is your plan's payment fee
+(with the per-payment minimum), frozen at setup.
+
+Merchant-facing webhook events: `subscription.created`, `subscription.renewed`
+(each monthly charge), `payment.failed` (renewal failure, with `will_retry` /
+`final_failure` flags), `subscription.cancelled`, and — for each scheduled
+autopay occurrence — the usual `direct_payment.confirmed`.
+
+## Webhooks
 
 Your merchant system should treat Siglume webhooks as the durable delivery
 signal. Always verify the signature against the raw request body before trusting
@@ -180,8 +334,8 @@ the payload. Create a marketplace webhook subscription with
 `POST /v1/market/webhooks/subscriptions`; the response returns the `whsec_`
 signing secret once.
 
-```ts
-import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
+```ts
+import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
 
 const { event } = await verifyDirectRequestPaymentWebhook(
   process.env.SIGLUME_WEBHOOK_SECRET!,
@@ -191,26 +345,26 @@ const { event } = await verifyDirectRequestPaymentWebhook(
 
 if (event.type === "direct_payment.confirmed") {
   // Mark the order paid if event.data.challenge_hash/order mapping matches.
-}
-```
-
-```py
-import os
-
-from siglume_direct_request_payment import verify_direct_request_payment_webhook
-
-verified = verify_direct_request_payment_webhook(
-    os.environ["SIGLUME_WEBHOOK_SECRET"],
-    raw_request_body,
-    siglume_signature_header,
-)
-
-if verified["event"]["type"] == "direct_payment.confirmed":
-    # Mark the order paid if event.data.challenge_hash/order mapping matches.
-    pass
-```
-
-## Security Rules
+}
+```
+
+```py
+import os
+
+from siglume_direct_request_payment import verify_direct_request_payment_webhook
+
+verified = verify_direct_request_payment_webhook(
+    os.environ["SIGLUME_WEBHOOK_SECRET"],
+    raw_request_body,
+    siglume_signature_header,
+)
+
+if verified["event"]["type"] == "direct_payment.confirmed":
+    # Mark the order paid if event.data.challenge_hash/order mapping matches.
+    pass
+```
+
+## Security Rules
 
 - Keep the challenge secret on the merchant server only.
 - Keep merchant order amount and currency server-authored.
@@ -224,13 +378,26 @@ if verified["event"]["type"] == "direct_payment.confirmed":
 
 Read [docs/security.md](./docs/security.md) before going live.
 
+## Go-Live Checklist
+
+- Run `setupCheckout` with the merchant Siglume JWT.
+- Complete the merchant billing mandate wallet approval if required.
+- Store `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` only on the merchant server.
+- Store the returned `SIGLUME_WEBHOOK_SECRET` only on the merchant server.
+- Persist `challenge_hash`, `requirement_id`, and fulfillment state per order.
+- Fulfill orders only from verified webhook data, with idempotency.
+- Treat `fee_bps` returned by Siglume as the runtime fee source of truth.
+
 ## Documentation
 
 - [Merchant quickstart](./docs/merchant-quickstart.md)
 - [API reference](./docs/api-reference.md)
 - [Pricing](./docs/pricing.md)
 - [Security guide](./docs/security.md)
+- [Merchant setup example](./examples/setup-merchant.ts)
 - [Express checkout example](./examples/express-checkout.ts)
+- [Japanese launch announcement draft](./docs/announcement-ja.md)
+- [Changelog](./CHANGELOG.md)
 
 ## License