siglume-direct-request-payment 0.3.6

SDK for the Siglume Direct Request Payment SDRP payment protocol

@siglume/direct-request-payment

Protocol Overview

Siglume Direct Request Payment (SDRP) is a wallet payment protocol for products that want to accept Siglume wallet payments. The merchant fixes the order, amount, and currency on its server; the buyer pays with a Siglume wallet; Siglume applies the correct pricing and settlement path from the payment amount.

Use this package when an external EC site, booking service, membership service, or paid API wants to accept Siglume wallet payments without taking custody of customer funds. The SDK creates and verifies one-time and recurring wallet payments; it does not hold customer funds or wallets.

Payment requirement creation must run in the authenticated buyer's Siglume context. Your merchant server must not use a merchant secret or API key to charge a customer wallet. The merchant server creates the signed challenge; the buyer-facing Siglume payment flow creates and pays the requirement.

DirectRequestPaymentMerchantClient requires the merchant's Siglume bearer token for setup. DirectRequestPaymentClient requires the buyer's Siglume bearer token for payment requirements. Do not use a Developer Portal cli_ API key with this package.

Amount-Based Pricing and Settlement

Pricing has one structure: you choose a Standard Payment plan once during setup, and after that the applied fee and the settlement timing follow the payment amount automatically. There is nothing else to choose.

• Standard Payment — most payments. Your selected plan's percentage fee, settled on-chain immediately after each payment confirms.
• Micro Payment — small payments, applied automatically by amount. A flat per-transaction protocol fee, settled weekly.
• Nano Payment — very small payments, applied automatically by amount. A flat per-usage protocol fee, settled monthly.

Micro Payment and Nano Payment are not separate products you opt into; they are amount bands Siglume applies on your behalf. Your integration code is the same regardless of which band a payment falls into. The full fee table and the exact weekly / monthly settlement schedule are in docs/pricing.md. Provider revenue in the Micro and Nano bands is not settled revenue until the weekly or monthly on-chain settlement succeeds. Siglume keeps outstanding failed settlements for retry under the published policy, but does not advance or guarantee provider revenue before settlement succeeds.

What This SDK Covers

• merchant self-service setup with a Siglume merchant JWT
• challenge secret creation and rotation
• merchant billing mandate preparation
• webhook subscription creation
• merchant-signed payment challenges
• buyer-authenticated payment requirement creation
• prepared wallet transaction execution payloads
• payment requirement verification
• signed webhook verification

It does not custody funds or manage customer wallets. Merchant setup runs through Siglume APIs with the merchant's Siglume JWT; buyer payment creation runs with the buyer's Siglume JWT.

Install

npm install @siglume/direct-request-payment

pip install siglume-direct-request-payment

Node.js 18 or later is required for the TypeScript SDK. Python 3.11 or later is required for the Python SDK.

Pricing

Pricing has one structure: choose a Standard Payment plan, then Siglume applies the fee for each payment by amount. Micro / Nano are automatic amount bands, not extra setup choices.

Both launch settlement currencies are first-class: JPY settled in JPYC, and USD settled in USDC. A merchant settles in one currency, chosen at onboarding. The settlement fee percentage is identical in both currencies; only the flat amounts differ.

Payment amount	Applied automatically	What you select	Fee	Settlement
Over JPY 500 / over USD 3.00, or whenever immediate finality is required	Standard Payment	Select one Standard plan: Launch, Starter, Growth, or Pro	Launch: JPY 0 / USD 0 monthly, 1.8%; Starter: JPY 980 / USD 6 monthly, 1.0%; Growth: JPY 2,980 / USD 18 monthly, 0.7%; Pro: JPY 9,800 / USD 60 monthly, 0.5%. Minimum JPY 30 / USD 0.20 per payment.	Settled on-chain immediately after the payment confirms
JPY 50-500 / about USD 0.30-3.00	Micro Payment	Applied automatically by amount	USD 0.01 / Tx, about JPY 2	Weekly settlement — see Settlement schedule
Under JPY 1 to JPY 49 / under USD 0.01 to about USD 0.30	Nano Payment	Applied automatically by amount	USD 0.001 / usage, about JPY 0.2	Monthly settlement — see Settlement schedule

A merchant billing mandate is required before accepting payments, even on the Launch plan. fee_bps returned on a payment requirement is the authoritative fee rate for that payment in the merchant's settlement currency. The full fee table and the weekly / monthly settlement schedule live in docs/pricing.md.

Merchant Setup: One SDK Call

Run this once from the merchant server or an integration agent with the merchant's Siglume JWT. It reserves the merchant key, creates the challenge secret, prepares the billing mandate, and creates the webhook subscription.

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: "example_merchant",
  display_name: "Example Merchant",
  billing_plan: "launch",
  billing_currency: "JPY",
  webhook_callback_url: "https://merchant.example/siglume/webhook",
  max_amount_minor: 100000,
});

// setup.env holds the merchant key plus the challenge and webhook secrets:
//   SIGLUME_DIRECT_PAYMENT_MERCHANT       (not secret)
//   SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET  (secret)
//   SIGLUME_WEBHOOK_SECRET                   (secret)
// Write these to your server-side secret store. Do NOT log the secret values.
console.log(`Configured merchant: ${setup.env.SIGLUME_DIRECT_PAYMENT_MERCHANT}`);

import os

from siglume_direct_request_payment import DirectRequestPaymentMerchantClient

merchant = DirectRequestPaymentMerchantClient(
    auth_token=os.environ["SIGLUME_MERCHANT_AUTH_TOKEN"],
)

setup = merchant.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,
)

# setup["env"] holds the merchant key plus the challenge and webhook secrets.
# Persist them to your server-side secret store; do not log the secret values.
print("Configured merchant:", setup["env"]["SIGLUME_DIRECT_PAYMENT_MERCHANT"])

Store returned secrets on the merchant server. challenge_secret and signing_secret are returned only when they are created or rotated. If a billing mandate response requires wallet approval, complete that Siglume wallet step before accepting production payments.

Merchant Server: Create a Challenge

import { createDirectRequestPaymentChallenge } from "@siglume/direct-request-payment";

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",
});

// Return only challenge.challenge to the buyer-facing checkout.
// Never return the challenge secret to the browser.
console.log(challenge.challenge);

import os

from siglume_direct_request_payment import create_direct_request_payment_challenge

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",
)

print(challenge["challenge"])

The signed challenge binds:

• merchant key
• amount in minor units
• currency
• nonce

Changing any of those values invalidates the challenge. The nonce must not contain : because the current platform challenge format is scheme:nonce:signature.

Buyer Payment Flow

Use DirectRequestPaymentClient only with the authenticated buyer's Siglume bearer token. SIGLUME_AUTH_TOKEN may be used in server-side payment-confirmation helpers; SIGLUME_API_KEY and Developer Portal cli_ keys are not accepted.

import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";

const siglume = new DirectRequestPaymentClient({
  auth_token: buyerSiglumeBearerToken,
});

const requirement = await siglume.createPaymentRequirement({
  merchant: "example_merchant",
  amount_minor: 1200,
  currency: "JPY",
  challenge: challengeFromMerchantServer,
});

if (requirement.approve_transaction_request) {
  await siglume.executeAllowanceTransaction(requirement, { await_finality: true });
}

const payment = await siglume.executePaymentTransaction(requirement, {
  await_finality: true,
});

const receiptId = String(payment.receipt?.receipt_id ?? "");
const verified = await siglume.verifyPaymentRequirement(requirement.requirement_id, {
  receipt_id: receiptId,
  await_finality: false,
});

console.log(verified.status);

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=1200,
    currency="JPY",
    challenge=challenge_from_merchant_server,
)

if requirement.get("approve_transaction_request"):
    siglume.execute_allowance_transaction(requirement, await_finality=True)

payment = siglume.execute_payment_transaction(requirement, await_finality=True)
receipt_id = str((payment.get("receipt") or {}).get("receipt_id") or "")

verified = siglume.verify_payment_requirement(
    requirement["requirement_id"],
    receipt_id=receipt_id,
    await_finality=False,
)

print(verified["status"])

Recurring Payments: Subscription and Scheduled Autopay

Beyond one-time checkout, a buyer can authorize recurring payments. The merchant approves the price and recurring product tag ONCE by signing a recurring challenge (a distinct scheme, so one-time challenges and recurring approvals can never be replayed as each other); after that, recurring charges are challenge-free by design. Subscriptions are bounded by the buyer's mandate; scheduled autopay is bounded by the buyer's per-run, daily, and monthly auto-pay budget.

• Subscription (cadence: "monthly"): Siglume charges the buyer's wallet monthly and pays your merchant wallet automatically. First month is charged at setup. The buyer can cancel from their Siglume wallet at any time.
• Scheduled autopay (cadence: "daily"): daily is the approval tag for merchant-triggered scheduled autopay, not a run-count limiter. The buyer authorizes the per-run amount and budget envelope, then hands you a schedule_token; YOUR scheduler triggers each occurrence with that token.

import { createDirectRequestPaymentRecurringChallenge } from "@siglume/direct-request-payment";

// Merchant server: approve a JPY 980 monthly subscription once.
const recurring = await createDirectRequestPaymentRecurringChallenge({
  merchant: "example_merchant",
  amount_minor: 980,
  currency: "JPY",
  cadence: "monthly",
  secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
  nonce: "subscription_setup_4711",
});

// Hand recurring.challenge to the buyer-facing page. The buyer creates the
// subscription with their Siglume token:
//   POST /v1/sdrp/direct-payments/subscriptions
//   { merchant, amount_minor, currency, cadence: "monthly", challenge }
// For scheduled autopay, the buyer instead creates a scheduled auto-pay
// authorization and hands you the schedule_token; your scheduler triggers
// each occurrence with that token.

import os

from siglume_direct_request_payment import create_direct_request_payment_recurring_challenge

# Merchant server: approve a JPY 980 monthly subscription once.
recurring = create_direct_request_payment_recurring_challenge(
    merchant="example_merchant",
    amount_minor=980,
    currency="JPY",
    cadence="monthly",
    secret=os.environ["SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET"],
    nonce="subscription_setup_4711",
)

# Hand recurring["challenge"] to the buyer-facing page, as in the TS example.
print(recurring["challenge"])

Each recurring challenge is single-use: it authorizes exactly one subscription or schedule, bound to the first buyer who redeems it. Issue a fresh challenge per setup. The platform fee on recurring charges is your plan's payment fee (with the per-payment minimum), frozen at setup.

Merchant-facing webhook events: subscription.created, subscription.renewed (each monthly charge), payment.failed (renewal failure, with will_retry / final_failure flags), subscription.cancelled, and — for each scheduled autopay occurrence — the usual direct_payment.confirmed.

Webhooks

Your merchant system should treat Siglume webhooks as the durable delivery signal. Always verify the signature against the raw request body before trusting the payload. Create a marketplace webhook subscription with POST /v1/market/webhooks/subscriptions; the response returns the whsec_ signing secret once.

import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";

const { event } = await verifyDirectRequestPaymentWebhook(
  process.env.SIGLUME_WEBHOOK_SECRET!,
  rawRequestBody,
  request.headers["siglume-signature"],
);

if (event.type === "direct_payment.confirmed") {
  // Mark the order paid if event.data.challenge_hash/order mapping matches.
}

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":
    # Mark the order paid if event.data.challenge_hash/order mapping matches.
    pass

Security Rules

• Keep the challenge secret on the merchant server only.
• Keep merchant order amount and currency server-authored.
• Use one nonce per order payment attempt.
• Store challenge_hash with the order and reject mismatches.
• Make order fulfillment idempotent by requirement_id and order id.
• Verify webhook signatures against the raw body.
• Do not use a merchant token to charge a customer wallet.
• Do not treat Direct Request Payment as stored value, prepaid points, escrow, or a platform balance.

Read docs/security.md before going live.

Go-Live Checklist

• Run setupCheckout with the merchant Siglume JWT.
• Complete the merchant billing mandate wallet approval if required.
• Store SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET only on the merchant server.
• Store the returned SIGLUME_WEBHOOK_SECRET only on the merchant server.
• Persist challenge_hash, requirement_id, and fulfillment state per order.
• Fulfill orders only from verified webhook data, with idempotency.
• Treat fee_bps returned by Siglume as the runtime fee source of truth.

Compatibility Notes

• The Direct Request Payment HTTP endpoints live under /v1/sdrp/direct-payments/...; the SDK targets them for you.
• For wire compatibility the platform still tags these payments with the legacy mode value external_402, and the merchant registry may still expose the legacy billing-plan key free for the Launch tier. The SDK sets and reads these values for you — treat them as compatibility identifiers, not public product names.

Documentation

• Merchant quickstart
• API reference
• Pricing
• Security guide
• Merchant setup example
• Express checkout example
• Japanese launch announcement draft
• Changelog

License

MIT