@siglume/direct-request-payment 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,116 @@
+# API Reference
+
+The TypeScript package is `@siglume/direct-request-payment`. The Python package
+is `siglume-direct-request-payment` and imports as
+`siglume_direct_request_payment`.
+
+## `createDirectRequestPaymentChallenge(input)` / `create_direct_request_payment_challenge(...)`
+
+Creates the merchant-signed challenge required by Siglume.
+
+```ts
+const challenge = await createDirectRequestPaymentChallenge({
+  merchant: "example_merchant",
+  amount_minor: 1200,
+  currency: "JPY",
+  secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
+  nonce: "order_123-attempt_1",
+});
+```
+
+```py
+import os
+
+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",
+)
+```
+
+Returns:
+
+- `challenge`: value to pass to Siglume
+- `challenge_hash`: value to store on the order
+- `signature`: HMAC-SHA256 hex digest
+- `nonce`
+
+`nonce` must not contain `:` because the platform challenge string is delimited
+as `scheme:nonce:signature`.
+
+## `verifyDirectRequestPaymentChallenge(secret, input)` / `verify_direct_request_payment_challenge(...)`
+
+Verifies a challenge against merchant, amount, currency, and secret. This is
+useful in tests and internal checkout assertions.
+
+## `DirectRequestPaymentClient`
+
+Thin wrapper around the current Siglume Direct Request Payment HTTP contract.
+Use it with the authenticated buyer's Siglume bearer token. Developer Portal
+`cli_` API keys are not accepted by these buyer-authenticated routes.
+
+Payment requirements include `fee_bps` from the Siglume platform. The SDK does
+not calculate merchant plan fees locally; see [Pricing](./pricing.md).
+
+```ts
+const siglume = new DirectRequestPaymentClient({
+  auth_token: buyerSiglumeBearerToken,
+  base_url: "https://siglume.com/v1",
+});
+```
+
+```py
+siglume = DirectRequestPaymentClient(
+    auth_token=buyer_siglume_bearer_token,
+    base_url="https://siglume.com/v1",
+)
+```
+
+### `createPaymentRequirement(input)` / `create_payment_requirement(...)`
+
+Calls:
+
+```text
+POST /v1/market/api-store/direct-payments/requirements
+```
+
+The SDK sends `mode="external_402"` internally.
+
+### `executeAllowanceTransaction(requirement)` / `execute_allowance_transaction(...)`
+
+Executes `requirement.approve_transaction_request` through:
+
+```text
+POST /v1/market/web3/transactions/execute-prepared
+```
+
+Only call this when Siglume returned an approval transaction.
+
+### `executePaymentTransaction(requirement)` / `execute_payment_transaction(...)`
+
+Executes `requirement.transaction_request` through the same prepared transaction
+route.
+
+### `verifyPaymentRequirement(requirement_id, input)` / `verify_payment_requirement(...)`
+
+Calls:
+
+```text
+POST /v1/market/api-store/direct-payments/requirements/{requirement_id}/verify
+```
+
+## Webhook Helpers
+
+- `buildWebhookSignatureHeader(secret, body)` for tests
+- `verifyWebhookSignature(secret, body, header)`
+- `verifyDirectRequestPaymentWebhook(secret, body, header)`
+- `parseDirectRequestPaymentWebhookEvent(payload)`
+- Python equivalents use snake_case:
+  `build_webhook_signature_header`, `verify_webhook_signature`,
+  `verify_direct_request_payment_webhook`, and
+  `parse_direct_request_payment_webhook_event`.
+
+`verifyDirectRequestPaymentWebhook` verifies the signature and parses the event
+in one call.

package/docs/merchant-quickstart.md

@@ -0,0 +1,255 @@
+# Merchant Quickstart
+
+This guide shows the minimum safe Siglume Direct Request Payment flow for an
+external merchant.
+
+## Actors
+
+- Merchant server: owns the order, amount, currency, challenge secret, webhook
+  endpoint, and order fulfillment.
+- Buyer: owns the Siglume wallet that pays the DirectPaymentHub transaction.
+- Siglume: creates the payment requirement, prepares the wallet transaction,
+  verifies the receipt, and emits signed webhooks.
+
+The merchant server must not create charges with a customer wallet. It signs the
+order challenge; the buyer-facing Siglume payment flow pays it.
+
+## 1. Configure the Merchant
+
+During onboarding, Siglume assigns:
+
+- `merchant` key, for example `example_merchant`
+- challenge secret
+- allowed currency and token, initially `JPY`/`JPYC`; `USD`/`USDC` requires
+  separately agreed merchant billing terms
+- billing plan; see [Pricing](./pricing.md)
+
+Keep the challenge secret server-side. Create a marketplace webhook subscription
+to receive the `whsec_` signing secret.
+
+```bash
+curl -X POST https://siglume.com/v1/market/webhooks/subscriptions \
+  -H "Authorization: Bearer <merchant-siglume-bearer-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "callback_url": "https://merchant.example/siglume/webhook",
+    "event_types": ["direct_payment.confirmed"],
+    "description": "Direct Request Payment production webhook"
+  }'
+```
+
+The `signing_secret` is returned only when the subscription is created or
+rotated. Store it as `SIGLUME_WEBHOOK_SECRET`.
+
+## 2. Create an Order and Challenge
+
+The merchant server creates the order before asking Siglume for payment.
+
+```ts
+import { createDirectRequestPaymentChallenge } from "@siglume/direct-request-payment";
+
+const order = {
+  id: "order_123",
+  amount_minor: 1200,
+  currency: "JPY",
+};
+
+const challenge = await createDirectRequestPaymentChallenge({
+  merchant: "example_merchant",
+  amount_minor: order.amount_minor,
+  currency: order.currency,
+  secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
+  nonce: `${order.id}-attempt_1`,
+});
+
+await orders.update(order.id, {
+  siglume_challenge_hash: challenge.challenge_hash,
+  siglume_payment_status: "pending",
+});
+
+return {
+  order_id: order.id,
+  amount_minor: order.amount_minor,
+  currency: order.currency,
+  siglume_challenge: challenge.challenge,
+};
+```
+
+Python:
+
+```py
+import os
+
+from siglume_direct_request_payment import create_direct_request_payment_challenge
+
+order = {
+    "id": "order_123",
+    "amount_minor": 1200,
+    "currency": "JPY",
+}
+
+challenge = create_direct_request_payment_challenge(
+    merchant="example_merchant",
+    amount_minor=order["amount_minor"],
+    currency=order["currency"],
+    secret=os.environ["SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET"],
+    nonce=f"{order['id']}-attempt_1",
+)
+
+orders.update(
+    order["id"],
+    {
+        "siglume_challenge_hash": challenge["challenge_hash"],
+        "siglume_payment_status": "pending",
+    },
+)
+
+return {
+    "order_id": order["id"],
+    "amount_minor": order["amount_minor"],
+    "currency": order["currency"],
+    "siglume_challenge": challenge["challenge"],
+}
+```
+
+Never calculate `amount_minor` from browser input.
+The nonce must be unique per order payment attempt and must not contain `:`.
+
+## 3. Buyer Creates and Pays the Requirement
+
+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.
+
+```ts
+import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";
+
+const siglume = new DirectRequestPaymentClient({
+  auth_token: buyerSiglumeBearerToken,
+});
+
+const requirement = await siglume.createPaymentRequirement({
+  merchant: "example_merchant",
+  amount_minor: order.amount_minor,
+  currency: order.currency,
+  challenge: order.siglume_challenge,
+});
+```
+
+Python:
+
+```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=order["amount_minor"],
+    currency=order["currency"],
+    challenge=order["siglume_challenge"],
+)
+```
+
+If Siglume returns `approve_transaction_request`, execute it first. Then execute
+the payment transaction and verify the receipt.
+
+```ts
+if (requirement.approve_transaction_request) {
+  await siglume.executeAllowanceTransaction(requirement, { await_finality: true });
+}
+
+const payment = await siglume.executePaymentTransaction(requirement, {
+  await_finality: true,
+});
+
+await siglume.verifyPaymentRequirement(requirement.requirement_id, {
+  receipt_id: String(payment.receipt?.receipt_id ?? ""),
+});
+```
+
+Python:
+
+```py
+if requirement.get("approve_transaction_request"):
+    siglume.execute_allowance_transaction(requirement, await_finality=True)
+
+payment = siglume.execute_payment_transaction(requirement, await_finality=True)
+
+siglume.verify_payment_requirement(
+    requirement["requirement_id"],
+    receipt_id=str((payment.get("receipt") or {}).get("receipt_id") or ""),
+)
+```
+
+## 4. Fulfill from Webhook
+
+Use the webhook as the durable signal, not just the browser return path.
+
+```ts
+import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
+
+const { event } = await verifyDirectRequestPaymentWebhook(
+  process.env.SIGLUME_WEBHOOK_SECRET!,
+  rawRequestBody,
+  siglumeSignatureHeader,
+);
+
+if (event.type === "direct_payment.confirmed") {
+  const data = event.data;
+  const order = await orders.findByChallengeHash(String(data.challenge_hash ?? ""));
+  if (!order) {
+    throw new Error("Unknown Siglume challenge hash");
+  }
+  await orders.markPaidOnce(order.id, {
+    siglume_requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+  });
+}
+```
+
+Python:
+
+```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":
+    data = verified["event"]["data"]
+    order = orders.find_by_challenge_hash(str(data.get("challenge_hash") or ""))
+    if not order:
+        raise RuntimeError("Unknown Siglume challenge hash")
+    orders.mark_paid_once(
+        order["id"],
+        siglume_requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+    )
+```
+
+## Failure Handling
+
+- `EXTERNAL_402_CHALLENGE_REQUIRED`: the merchant server did not provide a
+  challenge.
+- `INVALID_EXTERNAL_402_CHALLENGE`: the amount, currency, merchant, nonce, or
+  signature does not match.
+- `EXTERNAL_402_CHALLENGE_ALREADY_USED`: the challenge is already bound to a
+  different buyer.
+- `EXTERNAL_402_MERCHANT_BILLING_SETUP_REQUIRED`: merchant onboarding is not
+  complete.
+- `EXTERNAL_402_MERCHANT_BILLING_PAST_DUE` or
+  `EXTERNAL_402_MERCHANT_BILLING_SUSPENDED`: merchant billing must be fixed
+  before new payments can be accepted.
+
+## Go-Live Checklist
+
+- Challenge secret is only in server-side environment variables.
+- Webhook endpoint receives raw body and verifies `Siglume-Signature`.
+- Orders store `challenge_hash`, `requirement_id`, and fulfillment status.
+- Fulfillment is idempotent.
+- Browser input cannot change the amount or currency.
+- Nonces cannot be reused for separate order attempts.

package/docs/pricing.md

@@ -0,0 +1,56 @@
+# 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.
+
+## Trial Plans
+
+| Plan | Monthly fee | Payment fee | Intended starting point |
+| --- | ---: | ---: | --- |
+| Launch | JPY 0 | 0% through 100 payments/month, then 1.8% | Proofs of concept and low-volume trials |
+| Starter | JPY 980 | 1.0% | Early production checkout trials |
+| Growth | JPY 2,980 | 0.7% | Growing EC, booking, membership, and API services |
+| Pro | JPY 9,800 | 0.5% | Higher-volume merchant integrations |
+
+The minimum fee is JPY 3 for each fee-bearing payment, including Launch-plan
+payments after the included monthly allowance.
+
+If no paid plan is selected during onboarding, the merchant account uses the
+Launch plan. A merchant billing mandate is still required before accepting
+payments so Siglume can collect fees automatically after the 100-payment monthly
+allowance is exceeded.
+
+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.
+
+The 100-payment monthly allowance is not a hard processing cap. Payments after
+the allowance can continue when merchant billing is active, and those payments
+are fee-bearing at the Launch overage rate.
+
+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 public trial pricing above is JPY-denominated. If a merchant needs USD/USDC
+settlement, agree the USD merchant billing terms during onboarding; do not infer
+USD monthly or minimum fees from the JPY table.
+
+## 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

@@ -0,0 +1,85 @@
+# 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.
+
+## 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.
+
+## 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

@@ -0,0 +1,105 @@
+import express from "express";
+import {
+  createDirectRequestPaymentChallenge,
+  DirectRequestPaymentClient,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+
+// 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: "example_merchant",
+    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: "example_merchant",
+    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/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@siglume/direct-request-payment",
+  "version": "0.1.0",
+  "description": "Merchant SDK for Siglume Direct Request Payment checkout integrations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taihei-05/siglume-direct-request-payment.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lint": "npm run typecheck",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:check": "npm pack --json"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.5",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}