sBTC PayDocs
GitHub

Widget URL Parameters

Full reference for every URL parameter each widget accepts.

Each widget reads configuration from the URL. You can build widget URLs yourself — no SDK required. This page documents every parameter for each widget type.

Direct payment widget

URL shape:

https://sbtc-pay.com/widget/{MERCHANT_ADDRESS}?<params>
ParameterTypeDescription
merchantAddressrequiredpath segmentStacks address of the merchant receiving the payment.
amountrequiredintegerAmount in base units (sats for sBTC, micro-STX for STX).
tokensbtc | stx
default: sbtc
Which token to pay with.
memostringShort description shown to the customer. Max 280 chars.
themedark | light
default: dark
Widget color theme (light is reserved for future use).

Example

https://sbtc-pay.com/widget/SP1234ABC...?amount=50000&token=sbtc&memo=Monthly+coffee

Invoice widget

URL shape:

https://sbtc-pay.com/widget/invoice/{INVOICE_ID}
ParameterTypeDescription
invoiceIdrequiredpath segment (integer)Numeric invoice ID or human-readable form (e.g., INV-42).

The invoice widget doesn't take amount or token parameters — those are read from the invoice record on-chain. This guarantees the widget can't show a different amount than what's due.

Example

https://sbtc-pay.com/widget/invoice/42

Subscription widget

URL shape:

https://sbtc-pay.com/widget/subscribe/{MERCHANT_ADDRESS}?<params>
ParameterTypeDescription
merchantAddressrequiredpath segmentStacks address of the merchant offering the subscription.
planstring
default: Standard Plan
Display name for the plan. Shown to subscribers.
amountrequiredintegerAmount per billing interval, in base units.
intervaldaily | weekly | biweekly | monthly | quarterly | yearly
default: monthly
Billing cadence. Converted to burn-block count based on the network.
tokensbtc | stx
default: sbtc
Which token the subscription is billed in.

Example

https://sbtc-pay.com/widget/subscribe/SP1234ABC...?plan=Pro+Plan&amount=500000&interval=monthly&token=sbtc

Custom intervals

The interval parameter accepts either a preset name (monthly) or a raw burn-block count (4320). This lets you define non-standard cadences like "every 10 days" if your product needs them.

URL encoding

Remember to URL-encode parameter values that contain spaces or special characters. Most languages have a built-in helper:

javascript
const url = new URL("https://sbtc-pay.com/widget/SP1234...");
url.searchParams.set("amount", "50000");
url.searchParams.set("memo", "Tip for great article");
url.searchParams.set("token", "sbtc");
// url.toString() gives a properly encoded URL

iframe best practices

Always include these iframe attributes for best results:

html
<iframe
  src="..."
  width="100%"
  height="520"
  frameborder="0"
  style="border-radius:12px; max-width:420px;"
  allow="clipboard-write"
></iframe>
  • allow="clipboard-write" — lets the widget copy TX hashes on success
  • frameborder="0" — removes the default 2px browser border
  • max-width:420px — prevents awkward stretching on wide viewports