DocsTake payments

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 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 on your server.

View as markdown