Embed button

A pay button on any web page, from one script tag.

How it works

  1. pay.js puts a Pay with Bitcoin button on the page, right after its own <script> tag.
  2. When the customer clicks it, pay.js creates a checkout session with your publishable key (POST /api/v1/pub/checkout_sessions), on the host it was loaded from.
  3. The hosted checkout opens, in an overlay on your page or in a new tab.
  4. The customer pays from their own wallet, straight to yours.
  5. Once it is paid, pay.js closes the overlay, calls your data-on-complete function and fires satsrail:payment on document.

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>
Turn amounts on first. A button with 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.