# Framed checkout (/docs/payments/framed-checkout)

<Callout type="warn" title="Check availability before you build">
Framed checkout needs a signing secret configured on Swop's side. If it isn't set, `POST /embed-token` returns a `400` and checkout can't be framed. Mint one test token first; if it fails with a configuration message, use [headless checkout](/docs/payments/headless-checkout) instead (it doesn't depend on framing) and contact support.
</Callout>

{/* TODO(review): confirm MERCHANT_EMBED_SECRET is set on both swop-app-backend and desktop-app in production before publishing this page without the warning. */}

## How it works [#how-it-works]

Framing is locked down so that a leaked API key can't put your checkout on someone else's website:

1. **You register your website** once, in the Swop app, while signed in. An API key can't do this.
2. **Your server mints a short-lived embed token** for one registered website and one checkout.
3. **Your page frames the checkout** with that token. Swop checks the token when the frame loads.

| Piece | Who does it | Where |
|---|---|---|
| Register `https://shop.acme.com` | You, once | Swop app → Developer → Your website |
| Mint token | Your server, every page load | `POST /embed-token` with scope `commerce.embed` |
| Show checkout | The buyer's browser | `<iframe src=".../checkout/<intentId>?embed_token=...">` |

## 1. Register your website [#1-register-your-website]

In **Developer → Your website → Websites allowed to show your checkout**, add your origin, for example `https://shop.acme.com`.

- `https` only. `http://localhost` and `http://127.0.0.1` are allowed for development.
- Just the origin: no path, query string, fragment or wildcard.
- Register every exact origin you use. `https://acme.com` and `https://www.acme.com` are different.

## 2. Mint an embed token on your server [#2-mint-an-embed-token-on-your-server]

There are two kinds of token:

| `scope` | Frames | Needs | Lifetime |
|---|---|---|---|
| `intent` (default) | One checkout you created with [`POST /checkout-intents`](/docs/payments/headless-checkout) | `intentId` | 10 minutes |
| `store` | Your Swop cart page | `storeHandle` (your Swop handle) | 5 minutes |

```bash tab="curl"
curl -X POST https://apps.apiswop.co/api/v5/merchant/embed-token \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "intent", "intentId": "co_7Hk2mPq9xR4s", "origin": "https://shop.acme.com" }'
```

```js tab="Node"
export async function embedToken(intentId) {
  const res = await fetch('https://apps.apiswop.co/api/v5/merchant/embed-token', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ scope: 'intent', intentId, origin: 'https://shop.acme.com' }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.message);
  return body.data.token;
}
```

```python tab="Python"
import os, requests

def embed_token(intent_id):
    r = requests.post(
        "https://apps.apiswop.co/api/v5/merchant/embed-token",
        headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
        json={"scope": "intent", "intentId": intent_id, "origin": "https://shop.acme.com"},
    )
    r.raise_for_status()
    return r.json()["data"]["token"]
```

```json title="Response"
{
  "state": "success",
  "data": {
    "token": "eyJzYyI6ImludGVudCIs….Q2x…",
    "scope": "intent",
    "origin": "https://shop.acme.com",
    "expiresIn": 600
  }
}
```

If the origin isn't registered you get a `403` that names it: `https://shop.acme.com is not a registered embed origin for this merchant. Add it in the Swop app first.`

## 3. Frame it [#3-frame-it]

Use the `checkoutUrl` returned when you created the checkout, and append the token.

```html
<iframe
  src="https://www.swopme.app/checkout/co_7Hk2mPq9xR4s?embed_token=TOKEN"
  style="width:100%;min-height:720px;border:0">
</iframe>

<!-- or your whole Swop cart -->
<iframe src="https://www.swopme.app/sp/acme/cart?embed_token=TOKEN" style="width:100%;min-height:720px;border:0"></iframe>
```

{/* TODO(review): check whether the card element inside the frame needs allow="payment" for Apple Pay / Google Pay. */}

Mint a fresh token for each page view. Tokens are tied to one origin and one checkout (or one store) and expire within minutes.

<Callout title="Store scope starts empty">
The Swop cart lives in the browser's storage on swopme.app, so your site can't pre-fill it. If you want to pass your own cart into the frame, create a checkout with [`POST /checkout-intents`](/docs/payments/headless-checkout) and frame that intent.
</Callout>

## Knowing when it's paid [#knowing-when-its-paid]

The frame handles payment. For your systems, listen for [`checkout.paid`](/docs/webhooks/events) or poll [`GET /checkout-intents/{intentId}`](/docs/api-reference/checkout-intents).
