Multi-rail payment flow

Inspect /api/payment-methods for the current list of enabled payment rails. Each rail has its own purchase and redemption contract.

Bitcoin Lightning

  1. Request a product endpoint. HTTP 402 returns a BOLT11 invoice and payment hash.
  2. Pay the invoice using a mainnet Lightning wallet.
  3. Get the payment preimage from the wallet.
  4. Retry once with both proof headers.

Stripe Checkout

  1. POST to /api/stripe/checkout with the product ID.
  2. Complete payment in the hosted Stripe Checkout page.
  3. Return to /web/stripe/success and redeem, or call /api/stripe/redeem?session_id=...&product=....

x402 Solana USDC

  1. Request the explicit x402 endpoint when enabled.
  2. HTTP 402 returns an x402 v2 exact payment requirement.
  3. Submit settlement via the x402 payment header.
  4. The facilitator verifies on-chain and the endpoint returns the dataset.

curl

curl -i https://YOUR-WORKER/api/data
curl -H "X-Payment-Hash: HASH" -H "X-Payment-Preimage: PREIMAGE" https://YOUR-WORKER/api/data

Python

import requests
r = requests.get(url)
challenge = r.json()
# Pay challenge["payment_request"] before continuing.
data = requests.get(url, headers={"X-Payment-Hash": challenge["payment_hash"], "X-Payment-Preimage": preimage}).json()

JavaScript

const challenge = await (await fetch(url)).json();
// Pay challenge.payment_request before continuing.
const response = await fetch(url, {headers: {"X-Payment-Hash": challenge.payment_hash, "X-Payment-Preimage": preimage}});

Important: invoices are mainnet, preimages are one-time receipts, and expired challenges require a new invoice. Always consult /api/payment-methods for the current enabled rails.

Need help? Email contact@tradedatahub.net