# Payment window (embedded checkout)

Open the Kling checkout as an overlay on your own website with @klingis/embed, so customers in Iceland pay by card without leaving your page.

The payment window opens Kling's checkout in an overlay on your site. Your server creates a [checkout session](https://kling.is/en/docs/checkout) with your secret key; the browser opens it with `@klingis/embed`. Card details go straight to Kling and never touch your site.

## Install

```bash
npm install @klingis/embed
```

Or use a script tag, no build step needed:

```html
<script src="https://api.kling.is/v1/kling.js"></script>
```

## 1. Create a session on your server

```typescript
// e.g. a Next.js route handler: app/api/checkout/route.ts
export async function POST() {
  const res = await fetch("https://api.kling.is/v1/checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KLING_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    // ISK has no decimals: 5000 means 5.000 kr.
    body: JSON.stringify({ amount: 5000, currency: "ISK" }),
  });
  const session = await res.json();
  return Response.json({ sessionId: session.id });
}
```

## 2. Open the overlay in the browser

```typescript
import { Kling } from "@klingis/embed";

const kling = Kling.init({ locale: "is" });

const { sessionId } = await fetch("/api/checkout", { method: "POST" }).then((r) => r.json());

const result = await kling.checkout({
  sessionId,
  onSuccess: (res) => console.log("Paid", res.sessionId, res.paymentStatus),
  onError: (err) => console.log("Failed", err.code, err.message),
  onCancel: () => console.log("Closed"),
});
```

With the script tag, `Kling` is a global:

```html
<script src="https://api.kling.is/v1/kling.js"></script>
<script>
  const kling = Kling.init();
  kling.checkout({ sessionId: "cs_..." });
</script>
```

## Options

`Kling.init(options)`:

| Option | Default | Description |
|---|---|---|
| `locale` | detected | `is` or `en` |
| `baseUrl` | `https://pay.kling.is` | Checkout URL, for local development |
| `apiUrl` | `https://api.kling.is` | API URL |

`kling.checkout(options)`:

| Option | Description |
|---|---|
| `sessionId` | Required. The session your server created |
| `onSuccess` | Called when the payment succeeds |
| `onError` | Called when the payment fails |
| `onCancel` | Called when the customer closes the overlay |
| `showSuccessScreen` | Show Kling's success screen (default `true`) |

`kling.checkout()` returns a controller: await it for the result, or call `.close()` to close the overlay. `kling.preload({ sessionId })` starts loading before the customer clicks, so the overlay opens faster.

## Payment status in the browser

`onSuccess` and the result include `paymentStatus`:

- `paid`: a card or wallet payment went through.
- `awaiting_claim`: an online bank claim was issued and the customer pays it later. Don't ship yet.

Treat the browser result as a hint for your UI. Fulfil orders from [webhooks](https://kling.is/en/docs/webhooks) on your server.