@siglume/direct-request-payment 0.3.0 → 0.3.1

package/docs/pricing.md

@@ -1,73 +1,73 @@
-# Pricing
-
-This page documents the trial-phase merchant pricing for Siglume Direct Request
-Payment as of 2026-06-11. Pricing can change by agreement or future product
-release; the Siglume platform response is the source of truth for per-payment
-fee data returned at runtime.
-
-## Settlement Currencies
-
-Siglume Direct Request Payment launches in the US and Japan, and both settlement
-currencies are first-class:
-
-- **JPY**, settled on-chain in **JPYC**
-- **USD**, settled on-chain in **USDC**
-
-A merchant settles in a single currency, chosen at onboarding. The settlement fee
-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.
-
-## Trial Plans
-
-| Plan | Monthly fee (JPY) | Monthly fee (USD) | Payment fee | Intended starting point |
-| --- | ---: | ---: | ---: | --- |
-| Launch | JPY 0 | USD 0 | 1.8% | Proofs of concept and low-volume trials |
-| Starter | JPY 980 | USD 6.00 | 1.0% | Early production checkout trials |
-| Growth | JPY 2,980 | USD 18.00 | 0.7% | Growing EC, booking, membership, and API services |
-| Pro | JPY 9,800 | USD 60.00 | 0.5% | Higher-volume merchant integrations |
-
-Every payment is fee-bearing at the plan rate. The minimum fee is JPY 30
-(USD merchants: USD 0.20) per payment. The minimum covers the worst-case
-per-payment settlement cost (an on-chain signature plus network gas), so small
-payments are never processed at a loss; on larger payments the percentage rate
-applies instead.
-
-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.
-
-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.
-
-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.
-
-## SDK Behavior
-
-The SDK does not calculate merchant invoices or enforce plan limits locally.
-Instead, it exposes billing-related values returned by Siglume, including
-`fee_bps` on a payment requirement. This keeps merchant billing centralized in
-the Siglume platform and avoids stale client-side pricing logic.
-
-## Supported Use Cases
-
-The trial pricing is intended for:
-
-- Small EC checkout
-- Booking and reservation services
-- Membership services
-- Paid API access
-- Agent-to-agent payment experiments
+# Pricing
+
+This page documents the trial-phase merchant pricing for Siglume Direct Request
+Payment as of 2026-06-12. Pricing can change by agreement or future product
+release; the Siglume platform response is the source of truth for per-payment
+fee data returned at runtime.
+
+## Settlement Currencies
+
+Siglume Direct Request Payment launches in the US and Japan, and both settlement
+currencies are first-class:
+
+- **JPY**, settled on-chain in **JPYC**
+- **USD**, settled on-chain in **USDC**
+
+A merchant settles in a single currency, chosen at onboarding. The settlement fee
+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.
+
+## Trial Plans
+
+| Plan | Monthly fee (JPY) | Monthly fee (USD) | Payment fee | Intended starting point |
+| --- | ---: | ---: | ---: | --- |
+| Launch | JPY 0 | USD 0 | 1.8% | Proofs of concept and low-volume trials |
+| Starter | JPY 980 | USD 6.00 | 1.0% | Early production checkout trials |
+| Growth | JPY 2,980 | USD 18.00 | 0.7% | Growing EC, booking, membership, and API services |
+| Pro | JPY 9,800 | USD 60.00 | 0.5% | Higher-volume merchant integrations |
+
+Every payment is fee-bearing at the plan rate. The minimum fee is JPY 30
+(USD merchants: USD 0.20) per payment. The minimum covers the worst-case
+per-payment settlement cost (an on-chain signature plus network gas), so small
+payments are never processed at a loss; on larger payments the percentage rate
+applies instead.
+
+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.
+
+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.
+
+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.
+
+## SDK Behavior
+
+The SDK does not calculate merchant invoices or enforce plan limits locally.
+Instead, it exposes billing-related values returned by Siglume, including
+`fee_bps` on a payment requirement. This keeps merchant billing centralized in
+the Siglume platform and avoids stale client-side pricing logic.
+
+## Supported Use Cases
+
+The trial pricing is intended for:
+
+- Small EC checkout
+- Booking and reservation services
+- Membership services
+- Paid API access
+- Agent-to-agent payment experiments

package/docs/security.md

@@ -1,99 +1,110 @@
-# Security Guide
-
-Direct Request Payment is a wallet payment rail. Treat it like payment
-infrastructure, not like a generic API call.
-
-## Do Not Expose Secrets
-
-These values must stay server-side:
-
-- `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET`
-- `SIGLUME_WEBHOOK_SECRET`
-- any merchant administrative credentials
-
-The buyer-facing browser may receive the signed `challenge` string, but never
-the secret that produced it.
-
-## Keep JWT Roles Separate
-
-Use the merchant's Siglume JWT only for setup actions such as `setupCheckout`,
-challenge secret rotation, billing mandate preparation, and webhook subscription
-creation.
-
-Use the buyer's Siglume JWT only when creating and paying a payment requirement.
-A merchant JWT or Developer Portal `cli_` key must not be used to charge a
-customer wallet.
-
-## Bind the Order Server-Side
-
-The HMAC challenge covers:
-
-```text
-merchant:amount_minor:currency:nonce
-```
-
-Use a nonce derived from a durable order payment attempt, for example
-`order_123-attempt_1`. The nonce must not contain `:` because the platform
-challenge is encoded as `scheme:nonce:signature`. Store the returned
-`challenge_hash` on the order. When a
-webhook arrives, look up the order by `challenge_hash`.
-
-## Do Not Trust Browser Amounts
-
-The merchant server owns:
-
-- SKU or plan
-- amount in minor units
-- currency
-- nonce
-
-If a browser says the order total is 1200 JPY, treat that as display state only.
-Re-read the order server-side before generating the challenge.
-
-## Webhook Verification
-
-Verify the `Siglume-Signature` header using the raw request body. Do not parse
-and re-stringify JSON before verification.
-
-The SDK expects the Siglume signature format:
-
-```text
-t=<unix timestamp>,v1=<hex hmac sha256>
-```
-
-The signed payload is:
-
-```text
-<timestamp>.<raw body>
-```
-
-The default tolerance is 300 seconds.
-
-Use verified webhook data as the durable completion signal. Browser redirects,
-client-side callbacks, or local transaction responses can improve UX, but they
-should not be the only source used to fulfill an order.
-
-## Idempotency
-
-Fulfill exactly once per order. Store at least:
-
-- order id
-- challenge hash
-- Siglume requirement id
-- on-chain receipt id or transaction hash if present
-- fulfillment state
-
-Duplicate webhook deliveries and manual redelivery can occur. A duplicate
-webhook with the same requirement id must not ship the order twice.
-
-## What Direct Request Payment Is Not
-
-Direct Request Payment is not:
-
-- stored value
-- prepaid points
-- escrow
-- a platform balance
-- a card payment fallback
-
-It is a one-request wallet payment gate backed by an on-chain receipt.
+# Security Guide
+
+Direct Request Payment is a wallet payment rail. Treat it like payment
+infrastructure, not like a generic API call.
+
+## Do Not Expose Secrets
+
+These values must stay server-side:
+
+- `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET`
+- `SIGLUME_WEBHOOK_SECRET`
+- any merchant administrative credentials
+
+The buyer-facing browser may receive the signed `challenge` string, but never
+the secret that produced it.
+
+## Keep JWT Roles Separate
+
+Use the merchant's Siglume JWT only for setup actions such as `setupCheckout`,
+challenge secret rotation, billing mandate preparation, and webhook subscription
+creation.
+
+Use the buyer's Siglume JWT only when creating and paying a payment requirement.
+A merchant JWT or Developer Portal `cli_` key must not be used to charge a
+customer wallet.
+
+## Bind the Order Server-Side
+
+The HMAC challenge covers:
+
+```text
+merchant:amount_minor:currency:nonce
+```
+
+Use a nonce derived from a durable order payment attempt, for example
+`order_123-attempt_1`. The nonce must not contain `:` because the platform
+challenge is encoded as `scheme:nonce:signature`. Store the returned
+`challenge_hash` on the order. When a
+webhook arrives, look up the order by `challenge_hash`.
+
+Recurring approvals use a different challenge scheme and HMAC material:
+
+```text
+merchant:amount_minor:currency:cadence:nonce
+```
+
+`cadence="monthly"` is for subscriptions. `cadence="daily"` is the scheduled
+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.
+
+## Do Not Trust Browser Amounts
+
+The merchant server owns:
+
+- SKU or plan
+- amount in minor units
+- currency
+- nonce
+
+If a browser says the order total is 1200 JPY, treat that as display state only.
+Re-read the order server-side before generating the challenge.
+
+## Webhook Verification
+
+Verify the `Siglume-Signature` header using the raw request body. Do not parse
+and re-stringify JSON before verification.
+
+The SDK expects the Siglume signature format:
+
+```text
+t=<unix timestamp>,v1=<hex hmac sha256>
+```
+
+The signed payload is:
+
+```text
+<timestamp>.<raw body>
+```
+
+The default tolerance is 300 seconds.
+
+Use verified webhook data as the durable completion signal. Browser redirects,
+client-side callbacks, or local transaction responses can improve UX, but they
+should not be the only source used to fulfill an order.
+
+## Idempotency
+
+Fulfill exactly once per order. Store at least:
+
+- order id
+- challenge hash
+- Siglume requirement id
+- on-chain receipt id or transaction hash if present
+- fulfillment state
+
+Duplicate webhook deliveries and manual redelivery can occur. A duplicate
+webhook with the same requirement id must not ship the order twice.
+
+## What Direct Request Payment Is Not
+
+Direct Request Payment is not:
+
+- stored value
+- prepaid points
+- escrow
+- a platform balance
+- a card payment fallback
+
+It is a one-request wallet payment gate backed by an on-chain receipt.

package/examples/express-checkout.ts

@@ -1,106 +1,106 @@
-import express from "express";
-import {
-  createDirectRequestPaymentChallenge,
-  DirectRequestPaymentClient,
-  verifyDirectRequestPaymentWebhook,
-} from "@siglume/direct-request-payment";
-
-const app = express();
-const port = Number(process.env.PORT || 3000);
-const merchantKey = process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant";
-
-// Use JSON for normal routes. Use raw body only on the webhook route.
-app.use((req, res, next) => {
-  if (req.path === "/siglume/webhook") {
-    next();
-    return;
-  }
-  express.json()(req, res, next);
-});
-
-const orders = new Map<string, any>();
-
-const asyncRoute =
-  (handler: express.RequestHandler): express.RequestHandler =>
-  (req, res, next) => {
-    Promise.resolve(handler(req, res, next)).catch(next);
-  };
-
-app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
-  const orderId = String(req.body.order_id || "");
-  const order = orders.get(orderId);
-  if (!order) {
-    res.status(404).json({ error: "order_not_found" });
-    return;
-  }
-
-  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
-  const challenge = await createDirectRequestPaymentChallenge({
-    merchant: merchantKey,
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
-    nonce: `${order.id}-attempt_${order.payment_attempt}`,
-  });
-
-  order.siglume_challenge_hash = challenge.challenge_hash;
-  order.siglume_payment_status = "pending";
-
-  res.json({
-    order_id: order.id,
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    siglume_challenge: challenge.challenge,
-  });
-}));
-
-app.post("/checkout/siglume/pay", asyncRoute(async (req, res) => {
-  const order = orders.get(String(req.body.order_id || ""));
-  if (!order) {
-    res.status(404).json({ error: "order_not_found" });
-    return;
-  }
-
-  // In production, obtain this from the authenticated buyer's Siglume session
-  // or a hosted Siglume payment confirmation flow. Do not use a merchant secret
-  // to charge a customer wallet.
-  const siglume = new DirectRequestPaymentClient({
-    auth_token: String(req.headers.authorization || "").replace(/^Bearer\s+/i, ""),
-  });
-
-  const requirement = await siglume.createPaymentRequirement({
-    merchant: merchantKey,
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    challenge: String(req.body.siglume_challenge || ""),
-  });
-
-  res.json({ requirement });
-}));
-
-app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRoute(async (req, res) => {
-  const header = String(req.headers["siglume-signature"] || "");
-  const { event } = await verifyDirectRequestPaymentWebhook(
-    process.env.SIGLUME_WEBHOOK_SECRET!,
-    req.body,
-    header,
-  );
-
-  if (event.type === "direct_payment.confirmed") {
-    const challengeHash = String(event.data.challenge_hash || "");
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
-    if (order) {
-      order.siglume_payment_status = "paid";
-      order.siglume_requirement_id = event.data.requirement_id || event.data.direct_payment_requirement_id;
-    }
-  }
-
-  res.status(204).send();
-}));
-
-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 });
-});
-
-app.listen(port);
+import express from "express";
+import {
+  createDirectRequestPaymentChallenge,
+  DirectRequestPaymentClient,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+const merchantKey = process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant";
+
+// Use JSON for normal routes. Use raw body only on the webhook route.
+app.use((req, res, next) => {
+  if (req.path === "/siglume/webhook") {
+    next();
+    return;
+  }
+  express.json()(req, res, next);
+});
+
+const orders = new Map<string, any>();
+
+const asyncRoute =
+  (handler: express.RequestHandler): express.RequestHandler =>
+  (req, res, next) => {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+
+app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
+  const orderId = String(req.body.order_id || "");
+  const order = orders.get(orderId);
+  if (!order) {
+    res.status(404).json({ error: "order_not_found" });
+    return;
+  }
+
+  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
+  const challenge = await createDirectRequestPaymentChallenge({
+    merchant: merchantKey,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
+    nonce: `${order.id}-attempt_${order.payment_attempt}`,
+  });
+
+  order.siglume_challenge_hash = challenge.challenge_hash;
+  order.siglume_payment_status = "pending";
+
+  res.json({
+    order_id: order.id,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    siglume_challenge: challenge.challenge,
+  });
+}));
+
+app.post("/checkout/siglume/pay", asyncRoute(async (req, res) => {
+  const order = orders.get(String(req.body.order_id || ""));
+  if (!order) {
+    res.status(404).json({ error: "order_not_found" });
+    return;
+  }
+
+  // In production, obtain this from the authenticated buyer's Siglume session
+  // or a hosted Siglume payment confirmation flow. Do not use a merchant secret
+  // to charge a customer wallet.
+  const siglume = new DirectRequestPaymentClient({
+    auth_token: String(req.headers.authorization || "").replace(/^Bearer\s+/i, ""),
+  });
+
+  const requirement = await siglume.createPaymentRequirement({
+    merchant: merchantKey,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    challenge: String(req.body.siglume_challenge || ""),
+  });
+
+  res.json({ requirement });
+}));
+
+app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRoute(async (req, res) => {
+  const header = String(req.headers["siglume-signature"] || "");
+  const { event } = await verifyDirectRequestPaymentWebhook(
+    process.env.SIGLUME_WEBHOOK_SECRET!,
+    req.body,
+    header,
+  );
+
+  if (event.type === "direct_payment.confirmed") {
+    const challengeHash = String(event.data.challenge_hash || "");
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+    if (order) {
+      order.siglume_payment_status = "paid";
+      order.siglume_requirement_id = event.data.requirement_id || event.data.direct_payment_requirement_id;
+    }
+  }
+
+  res.status(204).send();
+}));
+
+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 });
+});
+
+app.listen(port);

package/examples/setup-merchant.ts

@@ -1,17 +1,17 @@
-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: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant",
-  display_name: process.env.SIGLUME_DIRECT_PAYMENT_DISPLAY_NAME || "Example Merchant",
-  billing_plan: process.env.SIGLUME_DIRECT_PAYMENT_PLAN || "launch",
-  billing_currency: process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CURRENCY || "JPY",
-  webhook_callback_url: process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL,
-  max_amount_minor: Number(process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CAP_MINOR || 100000),
-  create_webhook_subscription: Boolean(process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL),
-});
-
-console.log(JSON.stringify(setup, null, 2));
+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: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant",
+  display_name: process.env.SIGLUME_DIRECT_PAYMENT_DISPLAY_NAME || "Example Merchant",
+  billing_plan: process.env.SIGLUME_DIRECT_PAYMENT_PLAN || "launch",
+  billing_currency: process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CURRENCY || "JPY",
+  webhook_callback_url: process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL,
+  max_amount_minor: Number(process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CAP_MINOR || 100000),
+  create_webhook_subscription: Boolean(process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL),
+});
+
+console.log(JSON.stringify(setup, null, 2));