Efni

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:

bash
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.completed berst ekki fyrr en hún er greidd, með data.payment_status: "paid".
  • Með greiðslufresti (og kröfur hjá Landsbankanum): checkout.session.completed berst þegar krafan er stofnuð, með data.payment_status: "awaiting_claim", áður en nokkuð hefur verið greitt. Afgreiddu pöntunina á payment_intent.captured þar sem data.id er sama og data.payment_intent_id úr checkout.session.completed. Sá atburður ber ekki metadata greið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.renewed berst fyrir hverja greidda endurnýjun með korti, líka þá sem greiðist í nýrri tilraun. Sú tilraun sendir líka subscription.payment_recovered, svo afgreiddu endurnýjunina einu sinni. Hann berst ekki fyrir:
    • fyrstu rukkun eftir prufutíma. Hún er payment_intent.captured með data.subscription_id; subscription.activated kemur á 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.
  • Áskriftir með bank_claim endurnýjast með því að krafa er stofnuð á hverju tímabili: claim.created þegar hún er stofnuð, svo claim.paid og payment_intent.captured þegar hún er greidd. claim.created og claim.paid bera subscriptionId, billingReason (subscription_cycle fyrir endurnýjun), periodStart og periodEnd; sá payment_intent.captured ber subscription_id, billing_reason, period_start og period_end. Það er enginn subscription.payment_failed og engar sjálfvirkar nýjar tilraunir fyrir kröfu.
  • subscription.canceled berst þegar beðið er um uppsögn í lok tímabils (áskriftin er enn active, með cancel_at_period_end: true) og aftur þegar henni lýkur í raun. Athugaðu status áskriftarinnar áður en þú lokar á aðgang: hún er canceled þ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, svo subscription.canceled.

Beiðnin

Kling sendir POST með JSON:

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ð:

typescript
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í.

Skoða sem markdown