@klingis/embed

Kling, payments for Iceland. This is the embeddable checkout for Kling: it opens the Kling payment form as an overlay on your own website, so your customer pays by card in Icelandic krónur (ISK) without leaving your page.

Your server creates a checkout session with your secret key; the browser opens it with this package. Card details go straight to Kling's checkout and never touch your site.

Install

npm install @klingis/embed

Or load it from a script tag (no build step):

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

Quickstart

1. Create a checkout session on your server

Use your secret key (sk_test_... while building) from kling.is/dashboard/api-keys, or run npx @klingis/cli init to get one in .env.local. Never put the secret key in browser code.

// 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 });
}

The typed server SDK, @klingis/sdk, does the same call with types.

2. Open the overlay in the browser

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"),
});

if (result.success) {
  // Confirm on your server (webhook or GET /v1/checkout/sessions/:id) before shipping.
}

With the script tag, Kling is a global:

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

Payment status

onSuccess and the resolved result include paymentStatus:

• "paid": a card or wallet payment went through.
• "awaiting_claim": a bank claim (krafa) was issued and the buyer pays it later in their online bank. Do not ship the order yet; the payment_intent.captured webhook fires when they pay.

Treat the browser result as a hint for the UI and fulfil orders from webhooks on your server.

Options

Kling.init(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | locale | 'is' \| 'en' | auto-detect | Checkout UI language | | baseUrl | string | https://pay.kling.is | Override the checkout URL (local development) | | apiUrl | string | https://api.kling.is | Override the API URL |

kling.checkout(options)

| Option | Type | Description | |--------|------|-------------| | sessionId | string | Required. Checkout session ID created on your server | | onSuccess | (result) => void | Called when the payment succeeds | | onError | (error) => void | Called when the payment fails | | onCancel | () => void | Called when the customer closes the checkout | | showSuccessScreen | boolean | Show the success screen after payment (default: true) |

kling.checkout() returns a promise-like controller. Await it for the result, or call .close() to close the overlay from code.

kling.preload({ sessionId })

Starts loading the checkout before the customer clicks, so the overlay opens faster.

Docs

• Developer docs: kling.is/docs
• API reference: api.kling.is/docs
• Agent quickstart for AI coding tools: kling.is/start

License

MIT