DocsTake payments
Payments, capture and refunds
How a payment moves through Kling, from authorisation to capture and refund, and how to charge a saved card in Iceland with the payment intents API.
Every payment in Kling is a payment intent, whether it started in a checkout session, a payment link, a subscription or a direct API call. This page covers its lifecycle and how to charge a saved card, capture later and refund.
Lifecycle
| Status | Meaning |
|---|---|
requires_payment_method |
Created, waiting for a card. |
requires_action |
The customer must finish a step, such as 3-D Secure in their bank app. |
authorized |
The money is reserved on the card but not yet taken. |
pending_settlement |
Approved and being settled. Treat it as a success. On Verifone, a payment that later moves from here to captured sends no payment_intent.captured webhook. |
captured |
Paid. |
awaiting_claim |
An online bank claim was sent and is waiting to be paid. |
failed |
Declined or failed. The error code says why, e.g. card_declined_insufficient_funds. |
canceled |
An authorisation was released before capture. |
partially_refunded, refunded |
Part or all of the payment was returned. |
Capture now or later
By default a payment is authorised and captured in one step. That suits services, digital goods and subscriptions.
To reserve the money first and take it later, for example when the order ships, create the checkout session or payment intent with "capture": false. On a checkout session this works with Straumur only; other processors, and test-mode checkout, capture at once. No webhook is sent when the money is reserved: checkout.session.completed and payment_intent.captured arrive only after you capture, so find reserved payments with GET /v1/payment-intents?status=authorized. Then:
POST /v1/payment-intents/{id}/capturetakes the money. Sendamountto capture less than was authorised, for example when an item is out of stock.POST /v1/payment-intents/{id}/cancelreleases the reservation. If the processor had already taken the money, the payment comes backcapturedinstead, so checkstatusin the response.
Charge a saved card
When a customer has saved a card (checkout with save_payment_method, or a subscription), you can charge it again without them:
curl -X POST https://api.kling.is/v1/payment-intents \
-H "Authorization: Bearer $KLING_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: renewal-2026-10-cus_123" \
-d '{
"amount": 2990,
"customer": "CUSTOMER_ID",
"payment_method": "PAYMENT_METHOD_ID",
"description": "Monthly box, October"
}'Required: amount, customer, payment_method. Optional: currency, capture, description, statement_descriptor (up to 22 characters, shown on the card statement) and metadata. IDs are UUIDs. amount is in the currency's smallest unit: ISK has none (2990 is 2.990 kr), EUR and USD are in cents.
A declined card still returns HTTP 200, with status: "failed" and an error object, so check status before you treat the payment as made.
Refunds
POST /v1/payment-intents/{id}/refund returns money from a captured payment. Leave out amount for a full refund, or send it for a partial one. You can refund several times, up to what was paid. You can also refund from the payment's page in the dashboard. Each refund sends payment_intent.refunded: data.amount is that refund's amount, and data.partial is true when some of the payment is left.
Card processors
Card payments in Kling run through Straumur, Verifone or Rapyd, depending on your account. Kling applies to the acquirer for you, and the API is the same whichever one you use. Apple Pay is available on Straumur and can be switched on for Verifone; Google Pay is available on Straumur.