# Embed Button

> Add a Bitcoin pay button to any website with one script tag. No backend needed. Works on WordPress, Shopify, and static sites.

Source: https://www.satsrail.com/developers/guides/embed/

One script tag. Any website. Bitcoin payments.

## How It Works

Add a single `<script>` tag to your checkout page. The `pay.js` script reads the `data-*` attributes, renders a styled "Pay with Bitcoin" button, and handles the full checkout flow — no backend needed.

1. Script tag loads and renders an orange **Pay with Bitcoin** button
2. Customer clicks the button
3. Script creates a checkout session via `POST /api/v1/checkout_sessions` using your publishable key
4. Checkout page opens (embedded overlay or redirect)
5. Customer pays via Lightning QR code
6. Customer is redirected to your success URL

Two modes: **Cart checkout** (pass amount + customer data from your own checkout) or **Product button** (create a product in your dashboard, reference it by slug — price is fetched automatically).

## Integration Flows

SatsRail supports two integration patterns depending on whether you have your own checkout process or want SatsRail to handle everything.

#### Flow 1 Custom Checkout

Your site already has a cart or checkout page where you collect customer details. Pass the order amount and any customer data to SatsRail — the hosted checkout page skips the info form and goes straight to the payment QR code.

###### Via Embed Button

```
<script src="https://satsrail.com/js/pay.js"
  data-key="pk_live_..."
  data-amount="2500"
  data-currency="usd"
  data-customer-email="buyer@example.com"
  data-customer-name="Alice Smith"
  data-success-url="https://mystore.com/thanks"
  data-mode="iframe">
</script>
```

###### Via API (server-side)

```
curl -X POST https://app.satsrail.com/api/v1/m/checkout_sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_session": {
      "amount_cents": 2500,
      "currency": "usd",
      "customer_email": "buyer@example.com",
      "customer_name": "Alice Smith",
      "metadata": { "order_id": "ORD-42", "plan": "pro" },
      "success_url": "https://mystore.com/thanks",
      "cancel_url": "https://mystore.com/cart"
    }
  }'
```

> When `customer_email` is provided, the checkout page shows the payment QR immediately — no extra form step.

---

#### Flow 2 Product Button (Stripe-style)

No checkout page on your site? Create a **Product** in your SatsRail dashboard and configure which customer fields to collect in your merchant Settings (email, name, phone, shipping address). SatsRail will show a form with the selected fields before the payment QR code.

1. Create a Product in your dashboard
2. Configure which customer fields to collect in Settings
3. Embed a product button or share the Payment Link
4. Customer fills in the requested info, selects payment method, and pays
5. Customer info is stored in the order metadata

###### Embed Button

```
<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123def456"
  data-key="pk_live_..."
  data-mode="iframe">
</script>
```

###### Payment Link

```
https://satsrail.com/pay/prod_abc123def456
```

> Customer fields are configured in your merchant Settings. Choose from email (always required), name, phone, and shipping address. The checkout page only shows the fields you selected.

## Product Button

Instead of hardcoding amounts, create a **Product** in your SatsRail dashboard (with name and price), then reference it by slug. The button fetches the price automatically and displays it.

```
<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123def456"
  data-key="pk_live_..."
  data-mode="iframe">
</script>
```

The button will show **"Pay $25.00 with Bitcoin"** (or whatever the product price is). Override the label with `data-label` if needed.

## Payment Links

Need something even simpler? Every product has a **shareable payment link** — a URL you can paste anywhere. No code, no API keys, no website required.

```
https://satsrail.com/pay/prod_abc123def456
```

Share via email, WhatsApp, social media, or print as a QR code. When someone opens the link, a checkout session is created automatically and they see the payment page with QR code and countdown timer.

## Data Attributes

| Attribute | Required | Description |
| --- | --- | --- |
| `data-key` | Yes | Publishable key (`pk_live_` or `pk_test_`) |
| `data-product` | No* | Product slug (e.g. `prod_abc123`). If set, amount and currency are fetched automatically from the product. |
| `data-amount` | No* | Amount in cents (e.g. 5000 = $50.00). Required if `data-product` is not set. |
| `data-currency` | No | Currency code, default `"usd"` |
| `data-success-url` | No | Redirect URL after payment |
| `data-cancel-url` | No | Redirect URL on cancel |
| `data-label` | No | Button text, default `Pay with Bitcoin ⚡` |
| `data-mode` | No | `iframe` (embedded overlay), `new_tab`, or `redirect`. If omitted, uses your merchant Settings. |
| `data-customer-email` | No | Pre-fill customer email. Skips the info collection form on the checkout page. |
| `data-customer-name` | No | Pre-fill customer name. |
| `data-customer-phone` | No | Pre-fill customer phone number. |
| `data-customer-address` | No | Pre-fill customer shipping address. |

## Full Example

##### Amount Mode

Hardcode the price directly in the script tag:

```
<!DOCTYPE html>
<html>
<body>
  <h1>Buy Coffee Beans — $25.00</h1>

  <!-- The button is rendered automatically -->
  <script src="https://satsrail.com/js/pay.js"
    data-key="pk_live_..."
    data-amount="2500"
    data-currency="usd"
    data-success-url="https://mystore.com/thanks"
    data-cancel-url="https://mystore.com/cart"
    data-mode="iframe">
  </script>
</body>
</html>
```

##### Product Mode

Reference a product — price is fetched automatically:

```
<!DOCTYPE html>
<html>
<body>
  <h1>Buy Coffee Beans</h1>

  <!-- Button shows "Pay $25.00 with Bitcoin" automatically -->
  <script src="https://satsrail.com/js/pay.js"
    data-product="prod_abc123def456"
    data-key="pk_live_..."
    data-mode="iframe">
  </script>
</body>
</html>
```

## Button Styling

The script auto-creates a `<button>` element with the `.satsrail-pay-btn` class and a built-in orange gradient style. Override it with your own CSS:

```
.satsrail-pay-btn {
  background: #333 !important;
  border-radius: 0 !important;
  font-family: monospace !important;
}
```

- Default: orange/amber gradient, rounded corners, white text, hover lift effect
- The button is a standard `<button>` element — target `.satsrail-pay-btn` to restyle

## Embedded Mode

When `data-mode="iframe"` is set (or your merchant checkout mode is set to Embedded), the checkout page opens in an overlay iframe on your page (500×700 on desktop, full-screen on mobile). The customer never leaves your site. No popup blockers.

## Error Handling

If the checkout session fails to create (network error, invalid key, etc.), the button text changes to show the error message for 3 seconds, then reverts to the original label.

## Platform Integration

##### WordPress

Paste the script tag in your theme's `header.php` or use a plugin like "Insert Headers and Footers." Then add the button HTML in any post or page using a Custom HTML block.

##### Shopify

Add the script tag to your theme's `theme.liquid` layout. Use the button HTML in product descriptions or a custom page template.

##### Static Sites

Just paste both the script tag and button HTML into your page. That's it.

## CORS

The `/api/v1/checkout_sessions` endpoint allows wildcard CORS origins, so the embed script works from any domain without additional configuration.

## Add Bitcoin payments in 60 seconds

Copy the code above, swap in your publishable key, and you're live.

[Get Your API Key →](https://satsrail.com/users/sign_up)