SkjölunFyrir forritara
Webhooks
Kling sendir undirritaðan webhook á þjóninn þinn þegar greiðsla, krafa eða áskrift breytist. Hvernig þú skráir endapunkt, hvaða atburðir eru til, hvenær pöntun er greidd, hvernig þú staðfestir X-Kling-Signature hausinn og hvernig endurtekningar virka.
Webhook er beiðni sem Kling sendir á þjóninn þinn þegar eitthvað gerist, til dæmis þegar greiðsla fer í gegn. Afgreiddu pantanir út frá webhooks, ekki út frá vafra viðskiptavinarins: vafrinn getur lokast áður en hann kemst aftur á síðuna þína.
Skráðu endapunkt
Í stjórnborðinu opnar þú Forritarar → Webhooks og bætir við webhook með slóðinni þinni og atburðunum sem þú vilt fá. Eða notaðu API:
curl -X POST https://api.kling.is/v1/notification-channels \
-H "Authorization: Bearer $KLING_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "webhook",
"name": "Vefverslunin mín",
"config": { "url": "https://example.is/api/webhooks/kling" },
"event_subscriptions": ["checkout.session.completed", "payment_intent.captured"]
}'type, name, config.url og að minnsta kosti einn atburður í event_subscriptions eru nauðsynleg. Kling býr til undirritunarlykil og skilar honum í config.secret; hann sést líka í stjórnborðinu. Slóðin þarf að vera opinber og nota https://. Geymdu lykilinn á þjóninum, til dæmis sem KLING_WEBHOOK_SECRET.
Prófun og raunumhverfi hafa aðskilda endapunkta og lykla.
Atburðir
| Atburður | Hvenær |
|---|---|
checkout.session.completed |
Greiðsluferli lauk. Í kortagreiðslu er upphæðin komin. Í kröfu getur atburðurinn borist áður en greitt er: sjá Hvenær pöntun er greidd. |
payment_intent.captured |
Upphæðin var innheimt: kortagreiðsla (á netinu eða á staðnum), eða krafa sem var greidd að fullu. amount upp á 0 er staðfesting á korti (kort var vistað eða uppfært), ekki sala. |
payment_intent.failed |
Greiðslutilraun mistókst: kortinu var hafnað í greiðsluferli (viðskiptavinurinn getur reynt aftur), eða rukkun eða ný tilraun í áskrift mistókst. |
payment_intent.refunded |
Greiðsla var endurgreidd, að fullu eða að hluta. data.amount er þessi endurgreiðsla og data.partial segir hvort eitthvað sé eftir. |
claim.created |
Krafa í heimabanka var stofnuð. |
claim.paid |
Krafa var greidd að fullu. |
subscription.created |
Áskrift var stofnuð. |
subscription.trial_ended |
Prufutíma lauk. |
subscription.activated |
Áskriftin varð active eftir prufutímann. Sent áður en fyrsta rukkunin fer fram, svo það þýðir ekki að greitt hafi verið. |
subscription.updated |
Áskrift breyttist: virkjuð aftur, nýtt kort, afsláttur settur á eða tekinn af. |
subscription.product_change_scheduled |
Beðið var um að færa áskrift yfir á aðra vöru. data.product_id er nýja varan og data.effective_at segir hvenær skiptin taka gildi, í upphafi næsta tímabils. |
subscription.product_changed |
Áskriftin færðist yfir á nýju vöruna í upphafi nýs tímabils. Við endurnýjunina sem því fylgir er verð nýju vörunnar rukkað. |
subscription.canceled |
Beðið var um uppsögn, eða áskriftinni lauk. Sjá Atburðir áskrifta. |
subscription.renewed |
Endurnýjun með korti var greidd. |
subscription.payment_failed |
Endurnýjun með korti, eða fyrsta rukkun eftir prufutíma, mistókst. data.next_retry_at er næsta tilraun, eða null ef engin er eftir. |
subscription.payment_retry_failed |
Ný tilraun mistókst. data.next_retry_at er null eftir þá síðustu og áskriftinni er sagt upp. |
subscription.payment_recovered |
Ný tilraun tókst. |
subscription.paused, subscription.resumed |
Innheimta var sett í hlé eða hafin á ný. |
subscription.cycle_skipped |
Tímabil leið án greiðslu því innheimta er í hléi. |
Kling er ekki með atburði fyrir reikninga (invoices).
Hvenær pöntun er greidd
Afgreiddu hverja pöntun einu sinni og láttu afgreiðsluna þola endurtekningu fyrir hverja pöntun, til dæmis út frá auðkenni greiðsluferlisins eða þínu eigin pöntunarnúmeri í metadata. id atburðarins ver þig aðeins gegn því að sami atburður berist tvisvar: checkout.session.completed og payment_intent.captured fyrir sömu pöntun eru tveir ólíkir atburðir með ólík id, svo meðhöndlun sem afgreiðir á báðum sendir kortapöntun tvisvar.
Kort: checkout.session.completed þýðir að pöntunin er greidd.
Krafa: greiðsluferli býður alla greiðslumáta sem þú hefur kveikt á, þar á meðal kröfur þegar þær hafa verið virkjaðar, jafnvel þótt kóðinn þinn minnist aldrei á þær. Stofnaðu greiðsluferlið með payment_method_type: "card" fyrir kort eingöngu, eða "bank_claim" fyrir kröfur eingöngu (ISK). Hvernig kröfugreiðsluferli lýkur fer eftir hættinum:
- Strax (sjálfgefið hjá kröfuþjónustu Kling): gjalddagi og eindagi eru í dag og greiðsluferlið bíður í um 5 mínútur eftir að viðskiptavinurinn greiði kröfuna í bankanum.
checkout.session.completedberst ekki fyrr en hún er greidd, meðdata.payment_status: "paid". - Með greiðslufresti (og kröfur hjá Landsbankanum):
checkout.session.completedberst þegar krafan er stofnuð, meðdata.payment_status: "awaiting_claim", áður en nokkuð hefur verið greitt. Afgreiddu pöntunina ápayment_intent.capturedþar semdata.ider sama ogdata.payment_intent_idúrcheckout.session.completed. Sá atburður ber ekkimetadatagreiðsluferlisins, svo geymdu tenginguna milli þeirra hjá þér.
Í stuttu máli: líttu á checkout.session.completed sem greitt nema data.payment_status sé "awaiting_claim". Kortagreiðslur hafa engan payment_status reit.
Ef þú spyrð frekar GET /v1/checkout-sessions/{id} reglulega skaltu athuga payment_status === "paid" (eða "no_payment_required" fyrir greiðsluferli upp á 0 kr.), ekki status === "complete".
Atburðir áskrifta
subscription.renewedberst fyrir hverja greidda endurnýjun með korti, líka þá sem greiðist í nýrri tilraun. Sú tilraun sendir líkasubscription.payment_recovered, svo afgreiddu endurnýjunina einu sinni. Hann berst ekki fyrir:- fyrstu rukkun eftir prufutíma. Hún er
payment_intent.capturedmeðdata.subscription_id;subscription.activatedkemur á undan rukkuninni; - tímabil þar sem ekkert er að rukka (frí áskrift, eða afsláttur sem nær yfir allt tímabilið);
- áskriftir með
bank_claim.
- fyrstu rukkun eftir prufutíma. Hún er
- Áskriftir með
bank_claimendurnýjast með því að krafa er stofnuð á hverju tímabili:claim.createdþegar hún er stofnuð, svoclaim.paidogpayment_intent.capturedþegar hún er greidd.claim.createdogclaim.paidberasubscriptionId,billingReason(subscription_cyclefyrir endurnýjun),periodStartogperiodEnd; sápayment_intent.capturedbersubscription_id,billing_reason,period_startogperiod_end. Það er enginnsubscription.payment_failedog engar sjálfvirkar nýjar tilraunir fyrir kröfu. subscription.canceledberst þegar beðið er um uppsögn í lok tímabils (áskriftin er ennactive, meðcancel_at_period_end: true) og aftur þegar henni lýkur í raun. Athugaðustatusáskriftarinnar áður en þú lokar á aðgang: hún ercanceledþegar henni er lokið.- Afdráttarlaus höfnun (til dæmis kort tilkynnt týnt, eða lokaður reikningur) segir áskriftinni upp strax, án fleiri tilrauna: atburður um mistök með
next_retry_at: null, svosubscription.canceled.
Beiðnin
Kling sendir POST með JSON:
{
"id": "5b0c6f0e-2d7a-4f43-9a51-3f0b8f6c1e2d",
"type": "payment_intent.captured",
"created_at": "2026-10-01T12:00:00.000Z",
"data": { "id": "9d2e4b7a-1c3f-4e8a-b6d5-0a7f2c9e4b11", "amount": 4990 },
"merchant_id": "...",
"environment": "test"
}data.id er auðkenni hlutarins sem atburðurinn snýst um: greiðslunnar (payment intent), greiðsluferlisins, kröfunnar eða áskriftarinnar. Aðrir reitir í data fara eftir atburðinum og því hvernig var greitt, og ritháttur þeirra er blandaður (til dæmis checkoutSessionId við hliðina á subscription_id). Sæktu hlutinn í API-ið þegar þú þarft nýjustu stöðu hans. Auðkenni eru UUID. Upphæðir eru í minnstu einingu gjaldmiðilsins: ISK hefur enga (4990 er 4.990 kr.), EUR og USD eru í sentum (4990 er 49,90 €).
Reitirnir sem flestar tengingar nota:
| Atburður | Reitir í data |
|---|---|
checkout.session.completed |
payment_intent_id, customer_id, subscription_ids (listi, tómur ef engin er), payment_status (aðeins kröfur), metadata, custom_fields |
payment_intent.captured |
amount, metadata, og subscription_id þegar Kling rukkaði áskrift (endurnýjun, eða fyrsta rukkun eftir prufutíma eða í gegnum API) |
subscription.renewed |
payment_intent_id, amount, period_start, period_end |
Hausar: X-Kling-Signature, X-Kling-Event (tegund atburðar) og X-Kling-Delivery-Id.
Staðfestu undirritunina
X-Kling-Signature er sha256= og á eftir HMAC-SHA256 af hráum meginmáli beiðninnar, í hex, með undirritunarlyklinum þínum. Reiknaðu hana af nákvæmlega þeim bætum sem bárust, áður en JSON er þáttað:
import crypto from "node:crypto";
export function verifyKlingSignature(rawBody: string, header: string | null, secret: string): boolean {
if (!header) return false;
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(header);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Hafnaðu beiðninni með 401 ef hún passar ekki.
Endurtekningar
Svaraðu með 2xx innan 30 sekúndna. Allt annað telst misheppnað og Kling reynir aftur eftir 1 mínútu, 5 mínútur, 30 mínútur og 2 klukkustundir (fimm tilraunir alls). Tilvísunum (redirects) er ekki fylgt: 3xx svar fellir sendinguna án nýrrar tilraunar. Atburðir geta borist í annarri röð en þeir gerðust, og sami atburður getur borist oftar en einu sinni: notaðu id atburðarins til að sleppa tvíteknum.
POST /v1/notification-channels/test-webhooks sendir debug.check atburð á endapunktinn svo þú getir prófað hann.
Í þróun á eigin vél
Kling sendir webhooks aðeins á opinbera slóð, svo þjónn á localhost getur ekki tekið beint við þeim. Notaðu göng (tunnel), til dæmis ngrok eða Cloudflare Tunnel, sem gefa þjóninum á vélinni opinbera HTTPS-slóð, og skráðu þá slóð sem webhook í test-umhverfinu. Atburðirnir berast þá undirritaðir á vélina þína, nákvæmlega eins og þeir gera í raunumhverfinu, svo staðfesting undirskriftarinnar keyrir eins og hún á að gera.
Til að prófa tenginguna án þess að greiða sendir POST /v1/notification-channels/test-webhooks undirritaðan debug.check atburð, einu sinni og án nýrra tilrauna, á öll virk webhooks í umhverfi API-lykilsins þíns. data hans hefur message en ekkert id. Eða gerðu prufugreiðslu með prufukorti og fylgstu með alvöru atburðunum berast. Að prófunum loknum fjarlægir þú webhookið fyrir göngin í stjórnborðinu, eða slekkur á því.