# Greiðsluferli í gegnum API (checkout sessions)

Greiðsluferli (checkout session) er einfaldasta leiðin til að taka við greiðslu á Íslandi með Kling. Þjónninn þinn býr það til með upphæð eða vörum og viðskiptavinurinn greiðir á greiðslusíðu Kling eða í greiðsluglugga á þinni síðu.

Greiðsluferli (checkout session) er ein greiðslutilraun eins viðskiptavinar. Þjónninn þinn býr það til með leynilyklinum; Kling skilar `url` fyrir greiðslusíðu og `id` sem þú getur opnað sem [greiðsluglugga](https://kling.is/docs/embedded-checkout) ofan á þinni eigin síðu. Kortaupplýsingar fara beint til Kling og koma aldrei við þjóninn þinn.

## Búðu til greiðsluferli

`POST /v1/checkout/sessions`. Upphæðina má gefa upp á einn af þremur vegu (aðeins einn í einu):

| Svæði | Notaðu það þegar |
|---|---|
| `amount` | Þú þarft bara að rukka upphæð, t.d. `4990` fyrir 4.990 kr. |
| `product_id` | Þú selur vöru sem er skráð í Kling. Áskriftarvara stofnar áskrift. |
| `items` | Þú vilt sundurliðaða kvittun: hver lína hefur `product_id`, eða `description` og `amount`, ásamt `quantity` og `tax_rate` (0, 11 eða 24, VSK innifalinn í upphæðinni) |

```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" \
  -d '{
    "items": [
      { "description": "Bolur", "amount": 3990, "quantity": 2, "tax_rate": 24 }
    ],
    "currency": "ISK",
    "customer_email": "anna@example.is",
    "success_url": "https://example.is/takk",
    "cancel_url": "https://example.is/karfa",
    "metadata": { "order_id": "1042" }
  }'
```

Gagnleg valkvæð svæði:

- `success_url`, `cancel_url`: hvert viðskiptavinurinn fer á eftir. Kling bætir `?session_id=...` við success-slóðina.
- `locale`: `is` eða `en`, tungumál greiðslusíðunnar.
- `customer_id`, eða `customer_email`, `customer_name` og `customer_phone` til að fylla út fyrir fram.
- `promotion_code`: afsláttarkóði.
- `save_payment_method`: geyma kortið fyrir seinni greiðslur.
- `capture: false`: taka frá upphæðina núna og innheimta seinna, sjá [Greiðslur](https://kling.is/docs/payments).
- `payment_method_type`: `card` eða `bank_claim` ([krafa í heimabanka](https://kling.is/docs/bank-claims)).
- `allow_custom_amount` og `minimum_amount`: viðskiptavinurinn velur upphæðina sjálfur.
- `metadata`: þín eigin gögn, til dæmis pöntunarnúmer.

## Hvað kemur til baka

Í svarinu eru meðal annars `id`, `url`, `status`, `payment_status`, `amount`, `currency` og `expires_at`, auk svæðanna sem þú sendir. Sendu viðskiptavininn á `url`, eða opnaðu ferlið í greiðsluglugganum með `id`.

- `status`: `open` á meðan beðið er, `complete` þegar því er lokið, `expired` eftir 24 klukkustundir.
- `payment_status`: `paid`, `unpaid`, `awaiting_claim` (krafa var send og viðskiptavinurinn greiðir hana í heimabankanum) eða `no_payment_required`.

## Staðfestu greiðsluna á þjóninum

Ekki líta á það sem sönnun fyrir greiðslu að viðskiptavinurinn komi á `success_url`. Hlustaðu annaðhvort eftir `checkout.session.completed` [webhook](https://kling.is/docs/webhooks), eða sæktu ferlið með `GET /v1/checkout/sessions/{id}` og athugaðu `payment_status`. Fyrir kröfur skaltu afhenda þegar `payment_intent.captured` berst: þá hefur viðskiptavinurinn greitt.

`GET /v1/checkout/sessions` listar greiðsluferli, síað eftir `status` og með síðuskiptingu með `limit` og `starting_after`.

## Upphæðir og gjaldmiðlar

Upphæðir eru heiltölur. Krónan hefur enga aukastafi, svo `4990` er 4.990 kr. Hægt er að virkja evrur og Bandaríkjadali fyrir aðganginn þinn; hafðu samband á [hallo@kling.is](mailto:hallo@kling.is).