Topics

DocsDeveloper reference

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, generated from the OpenAPI spec at 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_...
Content-Type: application/json

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. Send request bodies as JSON with Content-Type: application/json. Without that header the API ignores the body.

One exception to the separation today: GET /v1/claims takes an environment parameter and returns that environment's claims to either key, marked with the calling key's livemode. Don't pass it.

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, so 4990 is €49,90) 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. A key belongs to one endpoint in one environment.

Errors

Error responses have this shape:

json
{ "error": { "type": "invalid_request_error", "message": "...", "code": "bank_claim_currency_not_supported" } }
type Status When
validation_error 400 The body or query does not match the schema
invalid_request_error 400, 403, 404, 409 The request is refused, for example an unknown ID or a key without access
card_error 400 The saved card cannot be charged, for example payment_method_revoked
authentication_error 401 Missing or unknown API key
not_found 404 No such endpoint, and an unknown ID on some endpoints
idempotency_conflict 409 A request with the same Idempotency-Key is still running
idempotency_error 422 The Idempotency-Key was used with a different body
rate_limit_error 429 Too many requests
api_error 500, 502 Something failed at Kling or at the payment provider
service_unavailable 503 A service Kling depends on is not available

Branch on the HTTP status and code, not on type: most unknown IDs are a 404 invalid_request_error. code, when present, is a specific, descriptive reason you can act on. An unexpected server error can return a 500 with a different body, so treat every 5xx as temporary and retry with the same Idempotency-Key.

Declined payments

A declined charge is not an error response. POST /v1/payment-intents answers 200 with the payment intent, status: "failed" and error: { "code": "card_declined_insufficient_funds", "message": "..." }. Always check status: captured means the money is taken. pending_settlement with code: "payment_outcome_pending" means the provider has not confirmed the outcome yet. Don't charge again; Kling checks it.

Rate limits

200 requests per minute per API key. Over the limit you get a 429 rate_limit_error; wait and try again. Responses under the limit carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the limit resets). The 429 has no Retry-After header today.

Pagination

List endpoints return { "object": "list", "data": [...], "has_more": true }, newest first. limit sets the page size, at most 100 (500 for products).

Only three list endpoints take a cursor: GET /v1/checkout/sessions, GET /v1/customers and GET /v1/subscriptions. Pass starting_after with the last id you got to fetch the next page.

The other list endpoints (payment intents, products, coupons, promotion codes, payment links and notification channels) ignore starting_after and always return the newest limit items. There has_more: true only tells you more exist. Don't loop on it: you get the same page every time. To reconcile orders, list checkout sessions with status=complete and created_gte and check each one's payment_status, or use webhooks.

Claims use limit and offset instead. GET /v1/events returns no has_more; pass after (a timestamp) to get newer events.

Main endpoints

Path What it does
/v1/checkout/sessions Checkout sessions, hosted or in the payment window
/v1/payment-intents Payments: charge saved cards, capture, refund
/v1/payment-links Payment links
/v1/products, /v1/subscriptions Subscriptions
/v1/billing-portal/sessions The customer billing portal
/v1/claims Online bank claims
/v1/customers, /v1/payment-methods Customers and their saved cards
/v1/coupons, /v1/promotion-codes Discounts
/v1/notification-channels Webhooks
/v1/kling.js The browser script for the payment window

View as markdown