Embed button
A pay button on any web page, from one script tag.
How it works
pay.jsputs a Pay with Bitcoin button on the page, right after its own<script>tag.- When the customer clicks it,
pay.jscreates a checkout session with your publishable key (POST /api/v1/pub/checkout_sessions), on the host it was loaded from. - The hosted checkout opens, in an overlay on your page or in a new tab.
- The customer pays from their own wallet, straight to yours.
- Once it is paid,
pay.jscloses the overlay, calls yourdata-on-completefunction and firessatsrail:paymentondocument.
Add the button
Load pay.js from https://app.satsrail.com: it sends its requests to the host it came from. Paste the tag
where the button should appear, in the page's body, never in <head>. One tag makes one button. On
WordPress, use a Custom HTML block; on Shopify, a Custom Liquid section.
For a product
Make the product in your dashboard and give its slug to data-product. The price is the product's: the button reads
Pay $25.00 with Bitcoin. A product sold in options at different prices reads
Pay with Bitcoin, and the customer chooses an option at checkout.
<script src="https://app.satsrail.com/js/pay.js"
data-key="pk_live_..."
data-product="prod_abc123def456">
</script>
For an amount
Your page names the amount, in your currency's smallest unit, and can pass the customer's details so the checkout doesn't ask for them.
<script src="https://app.satsrail.com/js/pay.js"
data-key="pk_live_..."
data-amount="2500"
data-customer-email="buyer@example.com"
data-customer-name="Alice Smith"
data-on-complete="orderPaid">
</script>
data-amount works only once you turn on "Let my website name the amount" in Settings → Checkout.
Until then POST /api/v1/pub/checkout_sessions answers 403 with the code open_amounts_disabled.
A publishable key is public, so anyone on the page can change the amount: read what the order came to
(data.order_total_amount_cents on payment.received) before you deliver.
Attributes
| Attribute | Description |
|---|---|
data-key |
Required. Your publishable key, pk_live_... or pk_test_.... |
data-product |
The product's slug (prod_...). Its price is used. Either this or data-amount. |
data-amount |
The amount in your currency's smallest unit (2500 is $25.00). Needs open amounts turned on, above. |
data-currency |
Leave it out. A checkout is always in your business's currency, and any other is refused with a validation_error naming yours. |
data-label |
The button's text, in place of Pay with Bitcoin. |
data-customer-email, data-customer-name |
The customer's details. Send either and the checkout skips its details form. |
data-on-complete |
A function on your page, called once the payment is made, with { order_id, order_number } (and, for a product, items and an access_token). satsrail:payment fires on document with the same data. |
data-on-detected |
A function called when an on-chain payment is seen and waits for its confirmations, with { order_id, order_number, required_confirmations }. satsrail:detected fires too. The overlay closes a few seconds later, so data-on-complete doesn't follow: the payment.received webhook does, once it confirms. |
data-on-expired |
For a product with a time limit on its access: a function called when that access runs out. satsrail:access_expired fires too. |
data-delivery |
For content encrypted with a media key (MediaKeys in the API reference): the wrapped content key. After the payment, pay.js unwraps it, loads deliver.js and decrypts the content on the page, then fires privapaid:unlocked (or privapaid:error). |
The callbacks and events come from the overlay only. A checkout in a tab ends on SatsRail's confirmation page: there
is no return URL. data-mode, which older snippets carry, changes nothing (below). Deliver on the
payment.received webhook, never on the callback alone.
How the checkout opens
Settings → Checkout → Checkout mode decides, for every button. Embedded checkout, the default, opens it in an overlay on your page: 500×700 on a computer, the whole screen on a phone. New tab opens a new browser tab, or the same tab on a phone. Closing the overlay before paying cancels the session.
Card payments. When the merchant takes cards through its own payment gateway (Starter and above), the
checkout offers Pay by card after bitcoin. Card processors' pages refuse to load inside an iframe, so in the
overlay the card choice opens the processor's page in a new tab, and the overlay waits until the processor confirms the
payment. Closing the overlay then doesn't cancel the checkout. data-on-complete and
satsrail:payment fire for a card payment as for bitcoin.
Styling
The button is a <button> with the class .satsrail-pay-btn, orange with white text.
Restyle it with your own CSS:
.satsrail-pay-btn {
background: #333 !important;
border-radius: 0 !important;
}
Errors and limits
If the session can't be made (a wrong key, amounts not turned on, no network), the button turns red with a warning for 3 seconds, then comes back. Your browser's network tab shows the API's answer.
A publishable key is limited per visitor: 60 requests a minute for each visitor's address, and 3,000 a minute for the
key as a whole. Past either, the answer is 429 with the code rate_limit_exceeded and a
Retry-After header.
Allowed websites
/api/v1/pub/checkout_sessions answers CORS from any origin. While a merchant lists no website, its
publishable key works on any website, and a merchant without the e-commerce module has nowhere to list one: the list
is on Ecommerce → Your website, which comes with that module (SatsRail switches it on; no plan
includes it yet).
Once one is listed, only the websites listed can use the publishable key and frame the checkout; a page anywhere else
gets 403 origin_not_allowed. A request with no Origin or Referer (a server's)
is never refused. See Your menu on your website
§ Allowed websites.