# API reference

Conventions of the Kling payments API for Iceland, including authentication, test and live keys, whole-krónur amounts, idempotency, errors, rate limits and pagination, and where to find the full endpoint reference.

The full, interactive reference for every endpoint is at [api.kling.is/docs](https://api.kling.is/docs), generated from the OpenAPI spec at [api.kling.is/docs/json](https://api.kling.is/docs/json). Point your AI tool at the JSON spec; it is the source of truth for request and response shapes. This page covers what holds for every endpoint.

## Base URL and authentication

```text
https://api.kling.is
Authorization: Bearer sk_test_...
```

Use a secret key from the **API Keys & Docs** page. `sk_test_...` keys work in the test environment, `sk_live_...` keys in the live one. Test and live are fully separate: their customers, products, payments and webhooks never mix. Keep secret keys on your server.

## Amounts

All amounts are integers in the currency's smallest unit. ISK has no decimals, so `5000` is 5.000 kr. Never multiply by 100. Euros and US dollars (two decimals) can be switched on for your account. Prices with a VAT rate (0, 11 or 24) include the VAT.

## Idempotency

Send an `Idempotency-Key` header on a write request to make retries safe. Kling keeps the response for 24 hours: the same key with the same body returns the same response without doing the work twice. The same key with a different body gets a `422 idempotency_error`, and a request still running with the same key gets `409 idempotency_conflict`. Only successful responses are kept, so a failed request can be retried with the same key.

## Errors

Errors have one shape:

```json
{ "error": { "type": "invalid_request_error", "message": "...", "code": "card_declined_insufficient_funds" } }
```

`type` is `authentication_error` (401), `validation_error` (400), `invalid_request_error`, `not_found` (404) or `rate_limit_error` (429). `code`, when present, is a specific, descriptive reason you can act on.

## Rate limits

200 requests per minute per API key. Creating checkout sessions and payment intents is limited to 30 per minute. Over the limit you get a 429 `rate_limit_error`; wait and try again.

## Pagination

List endpoints return `{ "object": "list", "data": [...], "has_more": true }`. Pass `limit`, and `starting_after` with the last `id` you got to fetch the next page. Claims use `limit` and `offset` instead.

## Main endpoints

| Path | What it does |
|---|---|
| `/v1/checkout/sessions` | [Checkout sessions](https://kling.is/en/docs/checkout), hosted or in the [payment window](https://kling.is/en/docs/embedded-checkout) |
| `/v1/payment-intents` | [Payments](https://kling.is/en/docs/payments): charge saved cards, capture, refund |
| `/v1/payment-links` | [Payment links](https://kling.is/en/docs/payment-links) |
| `/v1/products`, `/v1/subscriptions` | [Subscriptions](https://kling.is/en/docs/subscriptions) |
| `/v1/billing-portal/sessions` | The customer [billing portal](https://kling.is/en/docs/subscriptions#billing-portal) |
| `/v1/claims` | [Online bank claims](https://kling.is/en/docs/bank-claims) |
| `/v1/customers`, `/v1/payment-methods` | Customers and their saved cards |
| `/v1/coupons`, `/v1/promotion-codes` | Discounts |
| `/v1/notification-channels` | [Webhooks](https://kling.is/en/docs/webhooks) |
| `/v1/kling.js` | The browser script for the payment window |