Topics

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.
bash
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: is or en for the checkout language. In the payment window the locale you pass to Kling.init() wins.
  • customer_id, or customer_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 with 400. allow_promotion_codes: true lets 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 stays open and payment_status is unpaid.
  • payment_method_type: card offers cards only, bank_claim offers 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_amount and minimum_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.

json
{
  "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: open while waiting, complete when the customer has finished, expired after 24 hours.
  • payment_status: paid, unpaid, awaiting_claim (a bank claim was issued and the customer pays it in their online bank) or no_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.completed means paid. For card payments the event has no payment_status field.
  • Online bank claim, default: the customer gets a claim due today, and the checkout waits about 5 minutes for the bank. checkout.session.completed only arrives once the claim is paid, with payment_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.completed arrives as soon as the claim is issued, with payment_status: "awaiting_claim". Don't ship yet. Keep the payment_intent_id from that event and ship when payment_intent.captured arrives with the same data.id. That event does not carry your session metadata.

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.

View as markdown