@siglume/direct-request-payment 0.1.0 → 0.3.1

package/docs/merchant-quickstart.md

@@ -1,77 +1,112 @@
-# 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.
-
+# 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. 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"])
+```
+
+`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";
-
-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,
+
+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,
 };
 ```
 
@@ -114,25 +149,25 @@ return {
 
 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.
-
+
+## 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,
+
+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,
 });
 ```
 
@@ -153,16 +188,16 @@ requirement = siglume.create_payment_requirement(
 
 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,
-});
-
+
+```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 ?? ""),
 });
@@ -183,27 +218,27 @@ siglume.verify_payment_requirement(
 ```
 
 ## 4. Fulfill from Webhook
-
-Use the webhook as the durable signal, not just the browser return path.
-
+
+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 ?? ""),
-  });
+
+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 ?? ""),
+  });
 }
 ```
 
@@ -232,24 +267,30 @@ if verified["event"]["type"] == "direct_payment.confirmed":
 ```
 
 ## 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.
+
+- `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_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

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