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. |
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:iseðaen, tungumál greiðslusíðunnar. Í greiðsluglugganum ræðurlocalesem þú sendir íKling.init().customer_id, eðacustomer_email,customer_name,customer_phoneogcustomer_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: trueleyfir 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ð áframopenogpayment_statuserunpaid.payment_method_type:cardbýður aðeins upp á kort,bank_claimað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_amountogminimum_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.
{
"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,expiredeftir 24 klukkustundir.payment_status:paid,unpaid,awaiting_claim(krafa var send og viðskiptavinurinn greiðir hana í heimabankanum) eðano_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 ekkertpayment_statussvæð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.completedberst 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.completedum leið og krafan er stofnuð, meðpayment_status: "awaiting_claim". Ekki afhenda strax. Geymdupayment_intent_idúr þeim atburði og afhentu þegarpayment_intent.capturedberst með samadata.id. Sá atburður inniheldur ekkimetadatagreið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.