@siglume/direct-request-payment 0.1.0 → 0.3.0

package/docs/merchant-quickstart.md

@@ -14,39 +14,74 @@ external merchant.
 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"
-  }'
+## 1. Run Merchant Setup
+
+Run setup from the merchant server, CI, or an integration agent with the
+merchant's Siglume JWT. Do not use a Developer Portal `cli_` key here.
+
+TypeScript:
+
+```ts
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchantClient = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+});
+
+const setup = await merchantClient.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);
+```
+
+Python:
+
+```py
+import os
+
+from siglume_direct_request_payment import DirectRequestPaymentMerchantClient
+
+merchant_client = DirectRequestPaymentMerchantClient(
+    auth_token=os.environ["SIGLUME_MERCHANT_AUTH_TOKEN"],
+)
+
+setup = merchant_client.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"])
 ```
 
-The `signing_secret` is returned only when the subscription is created or
-rotated. Store it as `SIGLUME_WEBHOOK_SECRET`.
+`setupCheckout` / `setup_checkout` performs:
+
+- merchant key claim
+- challenge secret creation
+- billing mandate preparation
+- webhook subscription creation for `direct_payment.confirmed` and
+  `direct_payment.spent`
+
+Store `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` and `SIGLUME_WEBHOOK_SECRET`
+server-side only. Secrets are returned only when they are created or rotated.
+If the returned billing mandate requires wallet approval, complete that Siglume
+wallet step before accepting production payments.
 
 ## 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";
+```ts
+import { createDirectRequestPaymentChallenge } from "@siglume/direct-request-payment";
 
 const order = {
   id: "order_123",
@@ -72,48 +107,48 @@ return {
   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 `:`.
+};
+```
+
+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
 
@@ -121,8 +156,8 @@ 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";
+```ts
+import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";
 
 const siglume = new DirectRequestPaymentClient({
   auth_token: buyerSiglumeBearerToken,
@@ -133,26 +168,26 @@ const requirement = await siglume.createPaymentRequirement({
   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.
+});
+```
+
+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) {
@@ -163,31 +198,31 @@ 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
+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";
+```ts
+import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
 
 const { event } = await verifyDirectRequestPaymentWebhook(
   process.env.SIGLUME_WEBHOOK_SECRET!,
@@ -204,34 +239,34 @@ if (event.type === "direct_payment.confirmed") {
   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
+}
+```
+
+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.
@@ -239,17 +274,23 @@ if verified["event"]["type"] == "direct_payment.confirmed":
   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_NOT_FOUND`: run merchant setup with the merchant's
+  Siglume JWT.
+- `EXTERNAL_402_MERCHANT_BILLING_SETUP_REQUIRED`: the merchant billing mandate
+  is not active yet.
 - `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
 
+- `setupCheckout` / `setup_checkout` has claimed the merchant key.
+- Merchant billing mandate is active.
 - 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.
+- The order is fulfilled only after a verified webhook maps back to the stored
+  `challenge_hash`.

package/docs/pricing.md

@@ -5,38 +5,55 @@ 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 | 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 |
+| 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.
 
-The minimum fee is JPY 3 for each fee-bearing payment, including Launch-plan
-payments after the included monthly allowance.
+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 onboarding, the merchant account uses the
+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 fees automatically after the 100-payment monthly
-allowance is exceeded.
+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.
-
-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.
+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 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.
+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
 

package/docs/security.md

@@ -14,6 +14,16 @@ These values must stay server-side:
 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:
@@ -59,6 +69,10 @@ The signed payload is:
 
 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:

package/examples/express-checkout.ts

@@ -7,6 +7,7 @@ import {
 
 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) => {
@@ -35,7 +36,7 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
 
   order.payment_attempt = Number(order.payment_attempt || 0) + 1;
   const challenge = await createDirectRequestPaymentChallenge({
-    merchant: "example_merchant",
+    merchant: merchantKey,
     amount_minor: order.amount_minor,
     currency: order.currency,
     secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
@@ -68,7 +69,7 @@ app.post("/checkout/siglume/pay", asyncRoute(async (req, res) => {
   });
 
   const requirement = await siglume.createPaymentRequirement({
-    merchant: "example_merchant",
+    merchant: merchantKey,
     amount_minor: order.amount_minor,
     currency: order.currency,
     challenge: String(req.body.siglume_challenge || ""),

package/examples/setup-merchant.ts

@@ -0,0 +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));

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Merchant SDK for Siglume Direct Request Payment checkout integrations",
+  "keywords": [
+    "siglume",
+    "payment",
+    "checkout",
+    "external-402",
+    "wallet",
+    "sdk"
+  ],
   "license": "MIT",
+  "author": "Siglume Contributors",
+  "homepage": "https://github.com/taihei-05/siglume-direct-request-payment#readme",
+  "bugs": {
+    "url": "https://github.com/taihei-05/siglume-direct-request-payment/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/taihei-05/siglume-direct-request-payment.git"
@@ -37,6 +50,7 @@
     "docs",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {