# Hosted Checkout

Redirect to payments.southbill.com/c/{id} or embed payments.southbill.com/embed/{id} — card data never touches your servers, which minimizes your PCI scope (SAQ A).

# Hosted Checkout

Southbill ships two URLs for the hosted checkout — one for **real payments**, one for **design preview**. Do not mix them up.

| Route | Purpose | Real payment? |
|-------|---------|---------------|
| `/c/{session_id}` | Real hosted checkout for a session created via API | ✅ Yes |
| `/embed/{session_id}` | Same as above, optimised for iframe embedding | ✅ Yes |
| `/c/s/{slug}` | **Preview only** — renders your Checkout Builder branding with a dummy product. Ignores `?session=…`. | ❌ No |

## 1. Create a session (server-side)

```bash
curl -X POST https://api.southbill.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "currency": "CHF",
    "line_items": [{ "name": "T-Shirt", "quantity": 1, "amount": 4990 }],
    "success_url": "https://your-shop.com/thanks",
    "cancel_url":  "https://your-shop.com/cart"
  }'
```

Response:

```json
{
  "id": "cs_01H…",
  "checkout_url": "https://payments.southbill.com/c/cs_01H…?cs=cs_secret_…",
  "embed_url":    "https://payments.southbill.com/embed/cs_01H…"
}
```

## 2. Send the buyer to the real checkout

**Redirect**

```js
window.location = session.checkout_url;   // -> /c/{session_id}?cs={client_secret}
```

**Iframe**

```html
<iframe src="{{embed_url}}"
        style="width:100%;height:720px;border:0"
        allow="payment *"></iframe>
```

**Web component**

```html
<script src="https://payments.southbill.com/southbill.js"></script>
<southbill-checkout session-id="cs_01H…"></southbill-checkout>
```

The `slug` in the snippets from **Dashboard → Checkout builder** only tells Southbill *which branding profile* to apply — the `session_id` is what makes it a real transaction. Without a valid session, the page falls back to preview mode with dummy data.

## 3. What the buyer sees

- Merchant logo, business name and support email (from Checkout builder).
- Line items with product images (`line_items[].image_url`).
- All payment methods enabled for the currency in your plan + Stripe.
- 3-D Secure / SCA when required.
- Success page with southbill-hosted receipt (`/r/{merchant_id}/{tx_id}`) + PDF.

## Preview mode (`/c/s/{slug}`)

Use this URL in your browser to **see how your checkout looks** with the current Builder settings. It renders a hard-coded sample product for CHF 49.90 and a static list of payment methods. **Any `?session=…` parameter is ignored** — this route never talks to Stripe and never charges anyone.

To test a real payment end-to-end, always create a session via the API first and open the returned `checkout_url` **unchanged** — the `?cs=` query parameter is what authorises the browser to load that session.

## Success & cancel URLs

Optional. When set, Southbill redirects the buyer after the session ends and appends `?session_id={id}` so you can look up the result.

## Customising

**Dashboard → Checkout builder** controls colours, logo, business name, support email and return URL. Changes apply to every future session — no code changes needed.


## Ad-hoc vs. catalog line items

| Key type | Allowed `line_items` |
| --- | --- |
| Secret key (`sk_…`, server-side) | Ad-hoc items with `name`, `quantity`, `amount`, or catalog items with `price`. |
| Publishable key (`pk_…`, browser) | **Only** catalog items: `{ "price": "price_…", "quantity": 1 }`. Amounts are resolved server-side from your catalog. |