DocsTake payments
Checkout sessions
A checkout session is the simplest way to take a payment in Iceland with Kling. Your server creates it with an amount or products, and the customer pays on a Kling checkout page or in an overlay on your site.
A checkout session is one payment attempt by one customer. Your server creates it with your secret key; Kling returns a url for a hosted checkout page and an id you can open as an overlay on your own site with the payment window. Card details go straight to Kling's checkout and never touch your server.
Create a session
POST /v1/checkout/sessions. Set the amount in one of three ways (use only one):
| Field | Use it when |
|---|---|
amount |
You just need to charge a sum, e.g. 4990 for 4.990 kr. |
product_id |
You sell a product set up in Kling. A subscription product starts a subscription. If the product has variants, also send variant_id. |
items |
You want a receipt with lines: each item has a product_id, or a description and amount, plus quantity and tax_rate (0, 11 or 24, VAT included in the amount). A line without product_id and without tax_rate gets 0% VAT. |
curl -X POST https://api.kling.is/v1/checkout/sessions \
-H "Authorization: Bearer $KLING_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-v1" \
-d '{
"items": [
{ "description": "T-shirt", "amount": 3990, "quantity": 2, "tax_rate": 24 }
],
"currency": "ISK",
"customer_email": "anna@example.is",
"success_url": "https://example.is/thanks",
"cancel_url": "https://example.is/cart",
"metadata": { "order_id": "1042" }
}'With the same Idempotency-Key, a retry returns the same session. Use a new key whenever the cart changes: the same key with a different body within 24 hours is refused with 422.
Useful optional fields:
success_url,cancel_url: where the customer goes afterwards. Kling adds?session_id=...to the success URL.locale:isorenfor the checkout language. In the payment window thelocaleyou pass toKling.init()wins.customer_id, orcustomer_email,customer_name,customer_phone,customer_national_id(kennitala) to pre-fill (see below).promotion_code: apply a discount code. Send the code itself (e.g."VELKOMIN50"), not its ID; an unknown or expired code is refused with400.allow_promotion_codes: truelets the customer enter a code.save_payment_method: keep the card for later charges.capture: false: authorise now and capture later, see Payments. This only works for card payments through Straumur; other card providers, and test mode, capture straight away. While a payment is authorised but not captured, the session staysopenandpayment_statusisunpaid.payment_method_type:cardoffers cards only,bank_claimoffers only an online bank claim (ISK only). Leave it out and the checkout offers every method switched on for your account, including online bank claims once they are activated.allow_custom_amountandminimum_amount: let the customer choose the amount.form_fields: which customer details the checkout asks for. Omit it for name and email;[]asks for nothing.metadata: your own keys and values, such as an order number.
Customer details from your own form
If your own page already asks for the customer's details, pass them when you create the session. When name, email and every field you list in form_fields are pre-filled, Kling skips the details step and the customer goes straight to payment. Otherwise the details step opens with your values filled in, so the customer only adds what is missing. A field you list is asked for even when it is optional, so leave out any field you don't want Kling to ask for.
{
"amount": 5000,
"customer_name": "Anna Jónsdóttir",
"customer_email": "anna@example.is",
"customer_national_id": "0101302989",
"form_fields": [
{ "name": "name", "type": "text", "required": true },
{ "name": "email", "type": "email", "required": true },
{ "name": "nationalId", "type": "text", "required": true }
]
}customer_national_id must be a valid kennitala, with or without the hyphen, or the request fails with invalid_kennitala. The session returns it as 10 digits. If you let the checkout ask for the kennitala instead, read it back from customer_national_id on the session.
What comes back
The response includes id, url, status, payment_status, amount, currency, payment_intent, expires_at and the fields you sent. Lines come back in items with unit_amount and vat_rate. Send the customer to url, or open the session in the overlay with its id.
status:openwhile waiting,completewhen the customer has finished,expiredafter 24 hours.payment_status:paid,unpaid,awaiting_claim(a bank claim was issued and the customer pays it in their online bank) orno_payment_required.
complete does not always mean paid: a session paid with an online bank claim can be complete with payment_status: "awaiting_claim".
Confirm the payment on your server
Don't treat the redirect to success_url as proof of payment. Fulfil orders from the webhooks on your server:
- Card:
checkout.session.completedmeans paid. For card payments the event has nopayment_statusfield. - Online bank claim, default: the customer gets a claim due today, and the checkout waits about 5 minutes for the bank.
checkout.session.completedonly arrives once the claim is paid, withpayment_status: "paid". - Online bank claim with a payment window: if your claims settings say "With a payment window" (or your claims go through Landsbanki),
checkout.session.completedarrives as soon as the claim is issued, withpayment_status: "awaiting_claim". Don't ship yet. Keep thepayment_intent_idfrom that event and ship whenpayment_intent.capturedarrives with the samedata.id. That event does not carry your sessionmetadata.
This applies even if you never set payment_method_type: "bank_claim": once online bank claims are activated, the checkout offers them unless you set payment_method_type: "card". Make fulfilment idempotent per order: checkout.session.completed and payment_intent.captured are different events with different ids, so the event id alone doesn't stop an order shipping twice.
If you poll instead of using webhooks, fetch the session with GET /v1/checkout/sessions/{id} and ship when payment_status is paid, not when status is complete.
GET /v1/checkout/sessions lists sessions, newest first, filtered by status and created_gte and paginated with limit and starting_after.
Amounts and currency
Amounts are integers in the currency's smallest unit. ISK has no decimals, so 4990 is 4.990 kr. Euros and US dollars can be switched on for your account (ask us at hallo@kling.is); they are in cents, so 4990 is €49,90.