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
npm install @klingis/embedOr use a script tag, no build step needed:
<script src="https://api.kling.is/v1/kling.js"></script>1. Create a session on your server
// 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();
if (!res.ok) return Response.json(session, { status: res.status });
return Response.json({ sessionId: session.id });
}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"),
});With the script tag, Kling is a global:
<script src="https://api.kling.is/v1/kling.js"></script>
<script>
const kling = Kling.init({ locale: "is" });
kling.checkout({ sessionId: "SESSION_ID_FROM_YOUR_SERVER" });
</script>The session id is a UUID that your server gets back when it creates the session.
Options
Kling.init(options):
| Option | Default | Description |
|---|---|---|
locale |
the browser's language (is if it is Icelandic, otherwise en) |
is or en. Overrides the session's locale, so a shop that sells in Icelandic should set is |
baseUrl |
https://pay.kling.is |
Checkout URL, for local development |
apiUrl |
https://api.kling.is |
Only used to find the checkout URL when it points at localhost |
kling.checkout(options):
| Option | Description |
|---|---|
sessionId |
Required. The session your server created |
onSuccess |
Called when the payment succeeds |
onError |
Called when a payment attempt fails. The overlay stays open so the customer can try again |
onCancel |
Called when the customer closes the overlay without paying |
showSuccessScreen |
Show Kling's success screen (default true). With false the overlay closes as soon as the payment succeeds |
kling.checkout() returns a controller: await it for the result, or call .close() to close the overlay. It resolves when the payment succeeds or the overlay is closed, not on a failed attempt. kling.preload({ sessionId }) starts loading before the customer clicks, so the overlay opens faster.
When the overlay closes
If the session has a success_url, the overlay sends your page there when it closes after a payment (with ?session_id=...). If it has a cancel_url, closing without paying sends your page there. Leave them out of the session if you want the customer to stay on the page and you handle onSuccess and onCancel yourself.
Payment status in the browser
onSuccess and the result include paymentStatus:
paid: the payment went through, by card, wallet or an online bank claim paid right away.awaiting_claim: an online bank claim was issued with a payment window 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, as described in Confirm the payment on your server.
Contribution pages from your own form
A contribution page (open-payment-pages in the API) takes gifts at an amount the supporter picks, once or monthly, optionally with a dropdown question such as which department a gift is for. To run the giving form on your own site, start each gift with POST /v1/open-payment-pages/{id}/checkout-sessions instead of /v1/checkout/sessions, then open the session as in step 2. The gift is recorded on the page like one given on Kling's own page: it shows under Contributions in the dashboard with the option picked, and a monthly gift bills the chosen amount every month.
// On your server, e.g. a route handler your giving form posts to
const res = await fetch(`https://api.kling.is/v1/open-payment-pages/${PAGE_ID}/checkout-sessions`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KLING_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
amount: 5000, // 5.000 kr.
cadence: "recurring", // or "one_time", on a page that offers both
choice_option_slug: "korfubolti",
// The supporter, from your own form. national_id is optional.
customer: { name, email, national_id },
}),
});
const session = await res.json();
if (!res.ok) return Response.json(session, { status: res.status });
return Response.json({ sessionId: session.id });amountfollows the page's rules: one of its suggested amounts, or any amount when the page allows custom amounts.choice_option_idorchoice_option_slugpicks the dropdown option, and one is required when the question is. An option the page doesn't have is refused withchoice_field_answer_unknown_option.customerfinds the supporter by kennitala, then by email, or creates them. An existing supporter's details are only filled in where empty, never replaced. If you already created the customer, sendcustomer_idinstead.- With
customerorcustomer_idthe payment window asks for no payer details and opens straight on payment. With neither, the window collects the details the page is set to collect. - Leave out
success_urlandcancel_urlto keep the supporter on your page.
Keeping the list in step
If the dropdown's options live in your own system, change them one at a time instead of resending the whole list with PATCH /v1/open-payment-pages/{id}:
POST /v1/open-payment-pages/{id}/choice-optionswith{ name, slug }adds one. Use your own id as theslug(lowercase letters, digits and hyphens), so the same id works in your system, in links and inchoice_option_slug. A slug another option has, or had, is refused withchoice_option_slug_taken.PATCH /v1/open-payment-pages/{id}/choice-options/{option}renames one, found by its id or slug. The slug never changes.DELETE /v1/open-payment-pages/{id}/choice-options/{option}removes one. Gifts already given keep it, and its slug is never given to another option, so an old link or QR code can't open the wrong one.