@siglume/direct-request-payment 0.4.19 → 0.4.20

package/docs/api-reference.md

@@ -356,7 +356,8 @@ Returns:
 `merchant.merchant_account.metadata_jsonb.metered_risk_acceptance` records the
 merchant's Micro / Nano delayed-settlement risk acceptance receipt with
 `terms_version`, `accepted_at`, `principal_user_id`, `receipt_id`, and fixed
-market thresholds `JPY: 10000` / `USD: 10000`.
+market thresholds JPY 10,000 / USD 100.00 (`settlement_threshold_minor` is
+`10000` for both JPY minor units and USD cents).
 
 Secrets are returned only when created or rotated. Existing secrets are not
 replayed by `getMerchant` / `get_merchant`.
@@ -372,7 +373,9 @@ POST /v1/sdrp/direct-payments/merchants
 Creates or updates the merchant account for the authenticated merchant user.
 Accepts the optional `checkout_allowed_origins: string[]` return-URL origin
 allowlist described under `setupCheckout` above; the same normalization and
-webhook-origin auto-allow apply.
+webhook-origin auto-allow apply. Python annotates this direct response as
+`DirectRequestPaymentMerchantResponse`; `setup_checkout(...)` returns
+`DirectRequestPaymentCheckoutSetupResult`.
 
 ### `createCheckoutSession(input)` / `create_checkout_session(...)`
 
@@ -535,6 +538,41 @@ Defaults event types to `direct_payment.confirmed` and
 `direct_payment.spent`. The returned `signing_secret` is shown only at creation
 or rotation.
 
+### `listWebhookSubscriptions()` / `list_webhook_subscriptions()`
+
+Calls:
+
+```text
+GET /v1/market/webhooks/subscriptions
+```
+
+Returns the current user's webhook subscriptions without the full signing
+secret. Use `signing_secret_hint` to confirm that the local
+`SIGLUME_WEBHOOK_SECRET` is the expected secret.
+
+### `queueWebhookTestDelivery(input)` / `queue_webhook_test_delivery(...)`
+
+Calls:
+
+```text
+POST /v1/market/webhooks/test-deliveries
+```
+
+Queues a signed test event to one or more subscription ids. `siglume-check
+readiness` uses this for a harmless `direct_payment.confirmed` readiness probe.
+
+### `listWebhookDeliveries(input)` / `list_webhook_deliveries(...)`
+
+Calls:
+
+```text
+GET /v1/market/webhooks/deliveries
+```
+
+Supports `subscription_id`, `event_type`, `status`, and `limit`. Readiness polls
+this list after queueing the test delivery and only passes when the matching
+delivery status becomes `delivered`.
+
 ## `DirectRequestPaymentClient`
 
 Thin wrapper around the current Siglume Direct Request Payment HTTP contract.
@@ -1012,10 +1050,10 @@ the `Siglume-Signature` header; use
 `verifyDirectRequestPaymentWebhook(...)` /
 `verify_direct_request_payment_webhook(...)` for signature verification and
 parsing together. Throws
-`SiglumeWebhookPayloadError` on a malformed event, or when a
-`direct_payment.confirmed` event does not carry a supported Direct Request
-Payment mode (`external_402` or `metered_settlement_batch`). The `payload`
-argument is positional in both languages.
+`SiglumeWebhookPayloadError` on a malformed event. It does not reject an
+unsupported `direct_payment.confirmed` mode by itself; the classifier returns
+`kind: "unknown"` with `reason: "unsupported_confirmation_mode"` for that case.
+The `payload` argument is positional in both languages.
 
 For `direct_payment.confirmed`, inspect `event.data.pricing_band`,
 `event.data.settlement_cadence`, `event.data.finality`,
@@ -1039,13 +1077,15 @@ Recommended branch: call `classifyDirectPaymentConfirmation(event)` /
   pricing, per-payment on-chain finality, settled status, non-empty
   `requirement_id`, non-empty `challenge_hash`, and non-empty
   `chain_receipt_id`.
-- `metered_usage_accepted`: treat the usage as accepted but unsettled. This
-  requires Micro / Nano pricing, `finality === "aggregated_onchain_settlement"`,
-  the matching settlement cadence (`micro` -> `weekly`, `nano` -> `monthly`),
+- `metered_usage_accepted`: treat the usage as accepted but unsettled only if
+  your integration has explicitly enabled Micro / Nano delayed-settlement
+  handling. This requires Micro / Nano pricing,
+  `finality === "aggregated_onchain_settlement"`, the matching settlement
+  cadence (`micro` -> `weekly`, `nano` -> `monthly`),
   `settlement_status === "pending_settlement"`, non-empty `requirement_id`, and
-  non-empty `challenge_hash`. SDRP merchant setup and terms assume the merchant
-  accepts this delayed aggregated settlement model for Micro / Nano amount
-  bands; reconcile final revenue from statement APIs / settlement batches.
+  non-empty `challenge_hash`. Standard-only integrations should route this to
+  review or return `METERED_INTEGRATION_REQUIRED`; Micro / Nano integrations
+  must reconcile final revenue from statement APIs / settlement batches.
 - `unknown`: do not mark paid or fulfilled from the event type alone; fetch the
   requirement or route the event to manual review.
 
@@ -1153,7 +1193,11 @@ package exports `TypedDict` names for the high-risk response shapes:
 - `DirectRequestPaymentPastDueBlock`
 - `DirectRequestPaymentProviderMeteredTotals`
 - `DirectRequestPaymentListResponse`
-- `DirectRequestPaymentMerchantSetupResponse`
+- `DirectRequestPaymentMerchantResponse`
+- `DirectRequestPaymentCheckoutSetupResult`
+- `DirectRequestPaymentMerchantSetupResponse` (compatibility alias for checkout setup result)
+- `DirectRequestPaymentWebhookSubscription`
+- `DirectRequestPaymentWebhookDelivery`
 - `DirectRequestPaymentWebhookVerification`
 - `DirectRequestPaymentConfirmationClassification`
 

package/docs/merchant-quickstart.md

@@ -459,16 +459,9 @@ if (confirmation.kind === "standard_settled") {
 }
 
 if (confirmation.kind === "metered_usage_accepted") {
-  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
-  if (!order) {
-    await orders.flagForPaymentStateReview({
-      reason: "unknown_metered_challenge_hash",
-      requirement_id: confirmation.requirement_id,
-    });
-    return new Response(null, { status: 204 });
-  }
-  await orders.markFulfilledButUnsettledOnce(order.id, {
-    siglume_requirement_id: confirmation.requirement_id,
+  await orders.flagForPaymentStateReview({
+    reason: "metered_integration_required",
+    requirement_id: confirmation.requirement_id,
     pricing_band: confirmation.pricing_band,
   });
   return new Response(null, { status: 204 });
@@ -531,16 +524,9 @@ if confirmation["kind"] == "standard_settled":
     return "", 204
 
 if confirmation["kind"] == "metered_usage_accepted":
-    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
-    if not order:
-        orders.flag_for_payment_state_review(
-            reason="unknown_metered_challenge_hash",
-            requirement_id=confirmation["requirement_id"],
-        )
-        return "", 204
-    orders.mark_fulfilled_but_unsettled_once(
-        order["id"],
-        siglume_requirement_id=confirmation["requirement_id"],
+    orders.flag_for_payment_state_review(
+        reason="metered_integration_required",
+        requirement_id=confirmation["requirement_id"],
         pricing_band=confirmation["pricing_band"],
     )
     return "", 204

package/docs/metered-statements.md

@@ -195,9 +195,12 @@ Threshold-control fields:
 - `settlement_trigger`: `amount_threshold` or `scheduled_close`
 - `settlement_threshold_minor`: JPY `10000` or USD `10000` minor units
 - `threshold_reached_at`: set when the fixed amount threshold closed the batch
-- `total_unsettled_exposure_minor`: open plus `notice_pending`, `ready`,
-  `submitted`, retrying, and `past_due` provider gross exposure for the same
-  buyer / provider / token / pricing band
+- `total_unsettled_exposure_minor`: chargeable provider gross exposure for the
+  same buyer / provider / token / pricing band where the batch is not
+  `settled`, `uncollectible`, or `written_off`. This includes open usage,
+  `notice_pending`, `notice_delivery_failed`, `ready`, `submitted`,
+  `submitted_reconcile_required`, `failed_retryable`, `retrying`, and
+  `past_due`.
 
 JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
 conversions of one another.
@@ -318,7 +321,7 @@ Important batch fields:
 | `settlement_trigger` | `amount_threshold` for early threshold close, or `scheduled_close` for weekly/monthly close |
 | `settlement_threshold_minor` | Fixed market threshold for early settlement: JPY `10000` or USD `10000` minor units |
 | `threshold_reached_at` | Timestamp when the fixed threshold closed the batch, otherwise null |
-| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token / pricing band |
+| `total_unsettled_exposure_minor` | Chargeable provider gross exposure for the same buyer / provider / token / pricing band where status is not `settled`, `uncollectible`, or `written_off`; includes open, notice, ready, submitted, reconcile-required, retryable, retrying, and past-due states |
 | `expected_scheduled_debit_at` | Expected debit time for an open period before a batch exists |
 | `scheduled_debit_at` | Scheduled debit time after batch creation |
 | `not_before_attempt_at` | Earliest allowed debit attempt; this is the close-plus-3-day gate |
@@ -398,10 +401,10 @@ Siglume retries failed Micro / Nano settlement every 6 hours for up to 28
 automatic attempts. After that the batch remains `past_due` until operator
 requeue.
 
-New Micro / Nano usage for the same buyer / provider / token is paused while
-the total unsettled exposure is at or above the fixed threshold, and while a
-failed or past-due block remains. The provider API is not called for the
-rejected request, and the request is not charged.
+New Micro / Nano usage for the same buyer / provider / token / pricing band is
+paused while the total unsettled exposure is at or above the fixed threshold,
+and while a failed or past-due block remains. The provider API is not called for
+the rejected request, and the request is not charged.
 
 Public failure fields are sanitized. Show `failure_reason_code`,
 `failure_reason_label`, `failure_reason_help`, and `support_reference` to users
@@ -449,13 +452,12 @@ using stable idempotency keys and provider-side completion records.
 | --- | --- | --- | --- | --- |
 | `notice_delivery_failed` | Buyer debit is not yet allowed; provider revenue remains unsettled | Notice delivery can be retried or reviewed | Required if delivery keeps failing | Do not attempt your own debit notice or mark revenue settled. Show support context only. |
 | `submitted_reconcile_required` | A settlement submission exists but final on-chain outcome is not yet reconciled | Reconciliation may complete if a receipt is found | Required if reconciliation stalls | Do not retry payment yourself. Wait for `settled`, `failed_retryable`, or `past_due`. |
-| `past_due` | Buyer has an unresolved settlement block; provider sees past-due revenue | New Micro / Nano usage for the same buyer / plan / token is paused | Operator requeue or manual resolution only | Do not promise collection or provider payment. Ask the buyer to repair balance / allowance / BudgetVault / caps and reference `support_reference`. |
+| `past_due` | Buyer has an unresolved settlement block; provider sees past-due revenue | New Micro / Nano usage for the same buyer / provider / token / pricing band is paused | Operator requeue or manual resolution only | Do not promise collection or provider payment. Ask the buyer to repair balance / allowance / BudgetVault / caps and reference `support_reference`. |
 | `failed_chargeable` | Usage is still chargeable because provider work was accepted or completed | Included in later settlement attempts | Review if the provider disputes completion | Keep fulfillment idempotent and preserve evidence keyed by idempotency key. |
 
-Future platform versions may add explicit terminal states such as
-`closed_unpaid`, `uncollectible`, or `written_off`. Treat unknown terminal
-settlement states as not settled unless `status === "settled"` and
-`chain_receipt_id` is present.
+Terminal public states include `uncollectible` and `written_off` after operator
+review. Treat unknown terminal settlement states as not settled unless
+`status === "settled"` and `chain_receipt_id` is present.
 
 ## Operational Recipes
 

package/docs/payment-lifecycle.md

@@ -32,7 +32,7 @@ checkout open or agent/API payment starts
   -> usage accepted
   -> direct_payment.confirmed webhook
   -> classifier kind: metered_usage_accepted
-  -> merchant may fulfill as fulfilled_unsettled
+  -> merchant may fulfill as fulfilled_unsettled only after enabling Micro/Nano handling
   -> open period closes by amount threshold or schedule
   -> final notice window
   -> submitted / retrying / past_due if needed
@@ -41,10 +41,12 @@ checkout open or agent/API payment starts
   -> provider revenue is settled
 ```
 
-For Micro / Nano, `metered_usage_accepted` means the usage can be fulfilled
-under the SDRP delayed settlement model, but provider revenue is not settled
-yet. Provider revenue becomes settled only when the settlement batch is settled
-on-chain and has a `chain_receipt_id`.
+For Micro / Nano, `metered_usage_accepted` means the usage can be fulfilled only
+by an integration that has explicitly accepted SDRP delayed settlement and
+implemented fulfilled-but-unsettled state, settlement reconciliation, past-due
+handling, and terminal accounting. Provider revenue is not settled yet. Provider
+revenue becomes settled only when the settlement batch is settled on-chain and
+has a `chain_receipt_id`.
 
 ## Field meanings
 
@@ -52,7 +54,7 @@ on-chain and has a `chain_receipt_id`.
 | --- | --- | --- |
 | Hosted Checkout `status: "paid"` | The checkout session accepted the wallet payment flow. | For Micro / Nano, it does not mean provider revenue is settled. |
 | `standard_settled` | Standard payment is on-chain settled and can mark an order paid. | It is not used for Micro / Nano accepted usage. |
-| `metered_usage_accepted` | Micro / Nano usage is accepted and may be fulfilled as unsettled. | It is not settled provider revenue. |
+| `metered_usage_accepted` | Micro / Nano usage is accepted for integrations that have enabled delayed settlement handling. | It is not settled provider revenue, and Standard-only integrations should not fulfill it. |
 | `fulfilled_unsettled` | Your merchant system delivered the item before Micro / Nano settlement. | It is not a Siglume settlement status. |
 | `metered_batch_settled` | Aggregated Micro / Nano batch settled on-chain. | It does not identify one order by challenge hash. |
 | `pending_settlement` | Micro / Nano usage is waiting for aggregated settlement. | It is not a failure by itself. |
@@ -65,9 +67,10 @@ on-chain and has a `chain_receipt_id`.
   re-stringified JSON object.
 - Store `challenge_hash` on the order before redirecting the buyer.
 - For Standard, mark paid only from `standard_settled`.
-- For Micro / Nano, use a separate local state such as
-  `fulfilled_unsettled`; reconcile final revenue from statement APIs and batch
-  settlement events.
+- For Micro / Nano, fulfill only after you have explicitly enabled delayed
+  settlement handling. Use a separate local state such as
+  `fulfilled_unsettled`, then reconcile final revenue from statement APIs and
+  batch settlement events.
 - Treat `unknown` classifications as manual review. Do not mark paid or
   fulfilled from the event name alone.
 

package/docs/pricing.md

@@ -1,7 +1,7 @@
 # Pricing
 
 This page documents the trial-phase merchant pricing for Siglume Direct Request
-Payment as of SDK v0.4.19. Pricing can change by agreement or future product
+Payment as of SDK v0.4.20. 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.
 
@@ -156,9 +156,12 @@ confirmed payment turns into money in your settlement wallet.
 - While the same buyer / provider / token / pricing band has total unsettled
   exposure at or above the fixed threshold, new Micro/Nano usage is paused with the
   machine-readable error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not
-  called. Exposure includes open usage plus `notice_pending`, `ready`,
-  `submitted`, retrying, and `past_due` batches, and remains paused while
-  settlement failure or `past_due` is unresolved.
+  called. Exposure is chargeable provider gross where status is not `settled`,
+  `uncollectible`, or `written_off`; it includes open usage,
+  `notice_pending`, `notice_delivery_failed`, `ready`, `submitted`,
+  `submitted_reconcile_required`, `failed_retryable`, `retrying`, and
+  `past_due`. Usage remains paused while settlement failure or `past_due` is
+  unresolved.
 - Outstanding amounts remain attached to the failed settlement and are retried
   under this policy. They are not settled revenue, and Siglume does not advance,
   guarantee, or insure provider revenue before on-chain settlement succeeds.

package/docs/quickstart-10-minutes.md

@@ -34,27 +34,35 @@ SIGLUME_MERCHANT_AUTH_TOKEN=<merchant Siglume bearer token>
 SIGLUME_DIRECT_PAYMENT_MERCHANT=<merchant key>
 SHOP_PUBLIC_ORIGIN=https://www.your-product.example
 SHOP_WEBHOOK_URL=https://api.your-product.example/payments/webhooks/siglume
+SIGLUME_WEBHOOK_SECRET=<webhook signing secret from setupCheckout/setup_checkout>
 ```
 
-Then run:
+Then run the matching CLI:
 
 ```bash
+# Node / Express
 npx siglume-check readiness
+
+# Python / FastAPI
+siglume-check readiness
 ```
 
 The readiness check fails before you write checkout code if any required item is
-missing. It checks local config, reads the merchant account, and creates one
-unpaid expiring Hosted Checkout probe session to prove the account is enabled
-and the return origin is accepted. No buyer is charged.
+missing. It checks local config, reads the merchant account, requires active
+billing, confirms the webhook subscription points to `SHOP_WEBHOOK_URL`, checks
+that `direct_payment.confirmed` is subscribed, verifies the local webhook secret
+against the subscription hint, creates one unpaid expiring Hosted Checkout probe
+session, and queues a signed webhook test delivery. No buyer is charged.
 
-For CI or a preflight script:
+For a CI local-config smoke test:
 
 ```bash
-npx siglume-check readiness --json
+npx siglume-check readiness --no-api --json
 ```
 
-If this command fails, fix the reported item first. Do not build a human web
-checkout path until readiness passes.
+`--no-api` does not prove Hosted Checkout or webhook delivery. Before opening a
+human web checkout path, run readiness without `--no-api` and fix every FAIL
+item.
 
 ## 1. Copy integration files into your product
 
@@ -78,16 +86,31 @@ generated files are intentionally small and are meant to be edited.
 Express:
 
 ```ts
-import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import express from "express";
+import {
+  createSiglumeSdrpCheckoutRouter,
+  createSiglumeSdrpWebhookHandler,
+  type SiglumeSdrpRouterOptions,
+} from "./siglume/siglume-sdrp-routes.js";
 import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
 
-app.use("/payments", createSiglumeSdrpRouter({
+const siglumeOptions: SiglumeSdrpRouterOptions = {
   merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
   merchant_auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
   webhook_secret: process.env.SIGLUME_WEBHOOK_SECRET!,
   shop_public_origin: process.env.SHOP_PUBLIC_ORIGIN!,
   order_store: siglumeOrderStore,
-}));
+  allow_metered_payments: false,
+};
+
+app.post(
+  "/payments/webhooks/siglume",
+  express.raw({ type: "application/json" }),
+  createSiglumeSdrpWebhookHandler(siglumeOptions),
+);
+
+app.use(express.json());
+app.use("/payments", createSiglumeSdrpCheckoutRouter(siglumeOptions));
 ```
 
 FastAPI:
@@ -97,7 +120,7 @@ from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
 from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
 
 app.include_router(
-    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore(), allow_metered_payments=False),
     prefix="/payments",
 )
 ```
@@ -109,14 +132,20 @@ Replace the example store with your product's order database. The adapter must:
 - load the order by your `order_id`,
 - verify the current user is allowed to pay for that order,
 - return the server-authored `amount_minor` and `currency`,
-- persist `challenge_hash` and `checkout_session_id` before redirecting,
-- record webhook event ids durably,
+- create or reuse one active checkout attempt with a stable nonce,
+- persist `challenge_hash`, `checkout_session_id`, and `checkout_url` before redirecting,
+- process webhook event ids durably in the same transaction as the order update,
 - mark Standard orders paid exactly once,
-- mark Micro / Nano orders as fulfilled but unsettled exactly once,
 - route unknown classifications to manual review.
 
 Do not calculate the amount from browser input.
 
+The generated route defaults to Standard-only. If an order amount falls into
+Micro / Nano, checkout returns `METERED_INTEGRATION_REQUIRED` until you set
+`allow_metered_payments: true` / `allow_metered_payments=True` and implement
+fulfilled-but-unsettled state, settlement reconciliation, past-due handling, and
+terminal write-off handling.
+
 ## 4. Start checkout from your frontend
 
 Call your own server route:
@@ -135,10 +164,10 @@ Your product is integrated when:
 
 - `npx siglume-check readiness` passes,
 - your product has mounted checkout and webhook routes,
-- your order database stores `challenge_hash` for the order,
+- your order database stores one active checkout attempt and `challenge_hash` for the order,
 - the signed webhook verifies against the raw body,
 - `standard_settled` marks the order paid once,
-- `metered_usage_accepted` uses a separate fulfilled-but-unsettled state.
+- duplicate webhook deliveries do not double-fulfill the order.
 
 For Micro / Nano revenue reconciliation, read
 [Payment lifecycle](./payment-lifecycle.md) and

package/docs/troubleshooting.md

@@ -14,16 +14,22 @@ building a human web checkout:
 npx siglume-check readiness
 ```
 
-The command validates local configuration, reads the merchant account, and
-creates one unpaid expiring checkout session to prove Hosted Checkout is
-available for this merchant account.
+The command validates local configuration, reads the merchant account, checks
+the active billing mandate, confirms the webhook subscription, creates one
+unpaid expiring checkout session, and queues a signed webhook test delivery.
 
 - The merchant account exists.
 - The merchant billing mandate is active.
-- The webhook callback URL is HTTPS and reachable.
+- `SIGLUME_WEBHOOK_SECRET` is present and matches the subscription secret hint.
+- The webhook callback URL is HTTPS and matches an active subscription.
+- The subscription includes `direct_payment.confirmed`.
 - The checkout return URL origins are registered through
   `checkout_allowed_origins`.
 - The account has Hosted Checkout enabled.
+- The signed webhook test delivery reaches the endpoint and returns success.
+
+`--no-api` is only for local config smoke tests. `--no-probe` is a partial API
+check and does not report readiness as ready.
 
 If `createCheckoutSession(...)` or `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError`, do not show the raw 404/409 to the buyer.
@@ -46,10 +52,11 @@ contact for Hosted Checkout enablement.
 
 - Verify the exact raw request body bytes or raw body string.
 - Do not verify a parsed JSON object or a re-stringified JSON body.
-- Return a 2xx only after you have durably recorded the event or safely decided
-  it is duplicate/ignored.
-- Store processed webhook event ids or settlement identifiers durably; an
-  in-memory set is not enough for production.
+- Return a 2xx only after the order update or durable manual-review write has
+  succeeded, or after you safely decided the event is duplicate/ignored.
+- Store processed webhook event ids or settlement identifiers durably, in the
+  same database transaction as the order update/review write. An in-memory set
+  is not enough for production.
 - Do not assume delivery order. A settlement batch event may be reconciled from
   statement APIs rather than from one order challenge.
 - On signature failure, return a non-2xx status and do not mutate order state.

package/examples/express-checkout.ts

@@ -36,11 +36,21 @@ app.use((req, res, next) => {
 });
 
 const orders = new Map<string, any>();
+const processedWebhookEvents = new Set<string>();
 
 async function flagForPaymentStateReview(payload: Record<string, any>): Promise<void> {
   console.warn("payment state review required", payload);
 }
 
+async function processWebhookEventOnce(eventId: string, handler: () => Promise<void>): Promise<"processed" | "duplicate"> {
+  if (processedWebhookEvents.has(eventId)) {
+    return "duplicate";
+  }
+  await handler();
+  processedWebhookEvents.add(eventId);
+  return "processed";
+}
+
 async function handleDirectPaymentConfirmed(event: any): Promise<void> {
   const classification = classifyDirectPaymentConfirmation(event);
 
@@ -67,16 +77,11 @@ async function handleDirectPaymentConfirmed(event: any): Promise<void> {
   }
 
   if (classification.kind === "metered_usage_accepted") {
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
-    if (order) {
-      order.siglume_payment_status = "fulfilled_unsettled";
-      order.siglume_requirement_id = classification.requirement_id;
-    } else {
-      await flagForPaymentStateReview({
-        reason: "unknown_metered_challenge_hash",
-        requirement_id: classification.requirement_id,
-      });
-    }
+    await flagForPaymentStateReview({
+      reason: "metered_integration_required",
+      requirement_id: classification.requirement_id,
+      pricing_band: classification.pricing_band,
+    });
     return;
   }
 
@@ -102,7 +107,19 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
     return;
   }
 
-  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
+  if (!Number(order.payment_attempt || 0)) {
+    order.payment_attempt = 1;
+  }
+  if (order.siglume_checkout_url && order.siglume_checkout_session_id) {
+    res.json({
+      order_id: order.id,
+      amount_minor: order.amount_minor,
+      currency: order.currency,
+      checkout_url: order.siglume_checkout_url,
+      session_id: order.siglume_checkout_session_id,
+    });
+    return;
+  }
   const session = await siglumeMerchant.createCheckoutSession({
     merchant: merchantKey,
     amount_minor: order.amount_minor,
@@ -114,6 +131,7 @@ app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
   });
 
   order.siglume_challenge_hash = session.challenge_hash;
+  order.siglume_checkout_url = session.checkout_url;
   order.siglume_checkout_session_id = session.session_id;
   order.siglume_payment_status = "pending";
 
@@ -134,8 +152,14 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
     header,
   );
 
-  if (event.type === "direct_payment.confirmed") {
-    await handleDirectPaymentConfirmed(event);
+  const result = await processWebhookEventOnce(event.id, async () => {
+    if (event.type === "direct_payment.confirmed") {
+      await handleDirectPaymentConfirmed(event);
+    }
+  });
+  if (result === "duplicate") {
+    res.status(204).send();
+    return;
   }
 
   res.status(204).send();