@siglume/direct-request-payment 0.4.2 → 0.4.4

package/docs/security.md

@@ -61,6 +61,11 @@ 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.
 
+Production allowlist entries must use `https`. Development `http` entries are
+accepted only for `http://localhost`, `http://127.0.0.1`, or `http://[::1]`
+(with optional ports). Userinfo such as `https://user@shop.example.com` is
+rejected so an attacker cannot rely on origin-spoofing URL forms.
+
 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
@@ -114,6 +119,31 @@ Fulfill exactly once per order. Store at least:
 Duplicate webhook deliveries and manual redelivery can occur. A duplicate
 webhook with the same requirement id must not ship the order twice.
 
+## Micro / Nano Statement Privacy
+
+Micro Payment and Nano Payment introduce operational statement APIs and CSV
+exports because revenue is settled later in aggregated on-chain batches.
+
+Provider-facing statement APIs intentionally do not expose raw `buyer_user_id`,
+buyer email, buyer wallet address, relayer id, nonce, gas data, raw RPC errors,
+or raw platform failure messages. Use `buyer_period_ref` for provider-side
+reconciliation within a statement period, and show only the sanitized public
+failure fields:
+
+- `failure_reason_code`
+- `failure_reason_label`
+- `failure_reason_help`
+- `support_reference`
+
+Buyer-facing APIs may include past-due block reasons and balance / allowance /
+BudgetVault sufficiency indicators for the buyer's own account. Do not forward
+those buyer-account details to providers.
+
+Webhooks remain required for fulfillment, but webhooks alone are not a complete
+Micro / Nano revenue ledger. Use the statement APIs or CSV in
+[Micro / Nano Statements and Notices](./metered-statements.md) to separate
+settled, unsettled, and past-due provider amounts.
+
 ## What Direct Request Payment Is Not
 
 Direct Request Payment is not:
@@ -125,12 +155,18 @@ Direct Request Payment is not:
 - a card payment fallback
 
 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
+payments in the Micro and Nano amount bands are aggregated and settled on
+account-assigned weekly / monthly slots 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 aggregated 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.
+
+A Micro / Nano budget reservation is not a token lock, escrow, or payment
+guarantee. It reserves room against Siglume spending limits only. A later
+settlement can still fail if the buyer no longer has sufficient balance,
+allowance, BudgetVault authorization, or cap room; `past_due` records the issue
+but does not guarantee eventual collection or provider payment.

package/examples/express-checkout.ts

@@ -1,13 +1,15 @@
 import express from "express";
 import {
-  createDirectRequestPaymentChallenge,
-  DirectRequestPaymentClient,
+  DirectRequestPaymentMerchantClient,
   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";
+const siglumeMerchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN,
+});
 
 // Use JSON for normal routes. Use raw body only on the webhook route.
 app.use((req, res, next) => {
@@ -35,49 +37,29 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
   }
 
   order.payment_attempt = Number(order.payment_attempt || 0) + 1;
-  const challenge = await createDirectRequestPaymentChallenge({
+  const session = await siglumeMerchant.createCheckoutSession({
     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}`,
+    success_url: `${process.env.SHOP_PUBLIC_ORIGIN || "https://shop.example.com"}/thanks`,
+    cancel_url: `${process.env.SHOP_PUBLIC_ORIGIN || "https://shop.example.com"}/cart`,
+    metadata: { order_id: order.id },
   });
 
-  order.siglume_challenge_hash = challenge.challenge_hash;
+  order.siglume_challenge_hash = session.challenge_hash;
+  order.siglume_checkout_session_id = session.session_id;
   order.siglume_payment_status = "pending";
 
   res.json({
     order_id: order.id,
     amount_minor: order.amount_minor,
     currency: order.currency,
-    siglume_challenge: challenge.challenge,
+    checkout_url: session.checkout_url,
+    session_id: session.session_id,
   });
 }));
 
-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(

package/package.json

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