Efni

SkjölunTaktu við greiðslum

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 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. Ef varan hefur afbrigði sendirðu líka variant_id.
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). Lína án product_id og án tax_rate fær 0% VSK.
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": "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" }
  }'

Með sama Idempotency-Key skilar endurtekin beiðni sama greiðsluferli. Notaðu nýjan lykil í hvert sinn sem karfan breytist: sami lykill með öðru innihaldi innan 24 klukkustunda fær svarið 422.

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. Í greiðsluglugganum ræður locale sem þú sendir í Kling.init().
  • customer_id, eða customer_email, customer_name, customer_phone og customer_national_id (kennitala) til að fylla út fyrir fram (sjá neðar).
  • promotion_code: afsláttarkóði. Sendu sjálfan kóðann (t.d. "VELKOMIN50"), ekki auðkenni hans; óþekktum eða útrunnum kóða er hafnað með 400. allow_promotion_codes: true leyfir viðskiptavininum að slá inn kóða.
  • save_payment_method: geyma kortið fyrir seinni greiðslur.
  • capture: false: taka frá upphæðina núna og innheimta seinna, sjá Greiðslur. Þetta virkar aðeins fyrir kortagreiðslur í gegnum Straum; aðrir færsluhirðar, og test-umhverfið, innheimta strax. Á meðan greiðsla er frátekin en ekki innheimt er ferlið áfram open og payment_status er unpaid.
  • payment_method_type: card býður aðeins upp á kort, bank_claim aðeins upp á kröfu í heimabanka (eingöngu ISK). Ef þú sleppir því býður greiðslusíðan upp á alla greiðslumáta sem eru virkir á aðganginum, líka kröfur í heimabanka þegar þær hafa verið virkjaðar.
  • allow_custom_amount og minimum_amount: viðskiptavinurinn velur upphæðina sjálfur.
  • form_fields: hvaða upplýsingar greiðslusíðan biður um. Án þess er beðið um nafn og netfang; [] biður ekki um neitt.
  • metadata: þín eigin gögn, til dæmis pöntunarnúmer.

Upplýsingar úr þínu eigin formi

Ef þín eigin síða biður nú þegar um upplýsingar viðskiptavinarins geturðu sent þær með þegar þú stofnar greiðsluferlið. Þegar nafn, netfang og öll svæði sem þú telur upp í form_fields eru útfyllt sleppir Kling upplýsingaskrefinu og viðskiptavinurinn fer beint í greiðsluna. Annars opnast upplýsingaskrefið með þínum gildum útfylltum og viðskiptavinurinn bætir aðeins við því sem vantar. Beðið er um öll svæði sem þú telur upp, líka valkvæð, svo slepptu þeim svæðum sem Kling á ekki að biðja um.

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 verður að vera gild kennitala, með eða án bandstriks, annars er beiðninni hafnað með invalid_kennitala. Greiðsluferlið skilar henni sem 10 tölustöfum. Ef þú lætur greiðslusíðuna biðja um kennitöluna geturðu lesið hana úr customer_national_id á greiðsluferlinu.

Hvað kemur til baka

Í svarinu eru meðal annars id, url, status, payment_status, amount, currency, payment_intent og expires_at, auk svæðanna sem þú sendir. Línurnar koma til baka í items með unit_amount og vat_rate. Sendu viðskiptavininn á url, eða opnaðu ferlið í greiðsluglugganum með id.

  • status: open á meðan beðið er, complete þegar viðskiptavinurinn hefur lokið ferlinu, 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.

complete þýðir ekki alltaf að búið sé að greiða: ferli sem greitt er með kröfu getur verið complete með payment_status: "awaiting_claim".

Staðfestu greiðsluna á þjóninum

Ekki líta á það sem sönnun fyrir greiðslu að viðskiptavinurinn komi á success_url. Afgreiddu pantanir út frá webhooks á þjóninum:

  • Kort: checkout.session.completed þýðir að búið er að greiða. Fyrir kortagreiðslur er ekkert payment_status svæði í atburðinum.
  • Krafa, sjálfgefið: viðskiptavinurinn fær kröfu með gjalddaga í dag og greiðslusíðan bíður í um 5 mínútur eftir bankanum. checkout.session.completed berst ekki fyrr en krafan er greidd, með payment_status: "paid".
  • Krafa með greiðslufresti: ef stillt er „Með greiðslufresti“ í kröfustillingunum (eða kröfurnar fara í gegnum Landsbankann) berst checkout.session.completed um leið og krafan er stofnuð, með payment_status: "awaiting_claim". Ekki afhenda strax. Geymdu payment_intent_id úr þeim atburði og afhentu þegar payment_intent.captured berst með sama data.id. Sá atburður inniheldur ekki metadata greiðsluferlisins.

Þetta á líka við ef þú setur aldrei payment_method_type: "bank_claim": þegar kröfur hafa verið virkjaðar býður greiðslusíðan upp á þær nema þú setjir payment_method_type: "card". Gættu þess að hver pöntun sé aðeins afgreidd einu sinni: checkout.session.completed og payment_intent.captured eru ólíkir atburðir með ólík id, svo id atburðarins eitt og sér kemur ekki í veg fyrir að pöntun sé afhent tvisvar.

Ef þú sækir stöðuna reglulega í stað þess að nota webhooks skaltu sækja ferlið með GET /v1/checkout/sessions/{id} og afhenda þegar payment_status er paid, ekki þegar status er complete.

GET /v1/checkout/sessions listar greiðsluferli, nýjustu fyrst, síað eftir status og created_gte og með síðuskiptingu með limit og starting_after.

Upphæðir og gjaldmiðlar

Upphæðir eru heiltölur í minnstu einingu gjaldmiðilsins. 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); þar eru upphæðir í sentum, svo 4990 er €49,90.

Skoða sem markdown