Efni

SkjölunTaktu við greiðslum

Greiðslugluggi á þinni síðu

Opnaðu greiðslusíðu Kling sem glugga ofan á þinni eigin vefsíðu með @klingis/embed, svo viðskiptavinir greiða með korti án þess að fara af síðunni.

Greiðsluglugginn opnar greiðslusíðu Kling í glugga ofan á þinni síðu. Þjónninn þinn býr til greiðsluferli með leynilyklinum; vafrinn opnar það með @klingis/embed. Kortaupplýsingar fara beint til Kling og koma aldrei við síðuna þína.

Uppsetning

bash
npm install @klingis/embed

Eða notaðu script-tag, ekkert byggingarskref:

html
<script src="https://api.kling.is/v1/kling.js"></script>

1. Búðu til greiðsluferli á þjóninum

typescript
// t.d. route handler í Next.js: app/api/checkout/route.ts
export async function POST() {
  const res = await fetch("https://api.kling.is/v1/checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KLING_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    // Krónan hefur enga aukastafi: 5000 þýðir 5.000 kr.
    body: JSON.stringify({ amount: 5000, currency: "ISK" }),
  });
  const session = await res.json();
  if (!res.ok) return Response.json(session, { status: res.status });
  return Response.json({ sessionId: session.id });
}

2. Opnaðu gluggann í vafranum

typescript
import { Kling } from "@klingis/embed";

const kling = Kling.init({ locale: "is" });

const { sessionId } = await fetch("/api/checkout", { method: "POST" }).then((r) => r.json());

const result = await kling.checkout({
  sessionId,
  onSuccess: (res) => console.log("Greitt", res.sessionId, res.paymentStatus),
  onError: (err) => console.log("Mistókst", err.code, err.message),
  onCancel: () => console.log("Lokað"),
});

Með script-taginu er Kling aðgengilegt beint:

html
<script src="https://api.kling.is/v1/kling.js"></script>
<script>
  const kling = Kling.init({ locale: "is" });
  kling.checkout({ sessionId: "SESSION_ID_FROM_YOUR_SERVER" });
</script>

Auðkenni greiðsluferlisins (id) er UUID sem þjónninn fær til baka þegar hann býr ferlið til.

Stillingar

Kling.init(options):

Stilling Sjálfgefið Lýsing
locale tungumál vafrans (is ef það er íslenska, annars en) is eða en. Gengur framar locale greiðsluferlisins, svo verslun sem selur á íslensku ætti að setja is
baseUrl https://pay.kling.is Slóð greiðslusíðunnar, fyrir þróun
apiUrl https://api.kling.is Aðeins notað til að finna slóð greiðslusíðunnar þegar hún vísar á localhost

kling.checkout(options):

Stilling Lýsing
sessionId Nauðsynlegt. Greiðsluferlið sem þjónninn bjó til
onSuccess Kallað þegar greiðsla tekst
onError Kallað þegar greiðslutilraun mistekst. Glugginn er áfram opinn svo viðskiptavinurinn getur reynt aftur
onCancel Kallað þegar viðskiptavinurinn lokar glugganum án þess að greiða
showSuccessScreen Sýna staðfestingarskjá Kling (sjálfgefið true). Með false lokast glugginn um leið og greiðslan tekst

kling.checkout() skilar stýringu: bíddu eftir henni (await) til að fá niðurstöðuna, eða kallaðu á .close() til að loka glugganum. Hún skilar niðurstöðu þegar greiðslan tekst eða glugganum er lokað, ekki þegar greiðslutilraun mistekst. kling.preload({ sessionId }) byrjar að hlaða áður en smellt er, svo glugginn opnast hraðar.

Þegar glugginn lokast

Ef greiðsluferlið hefur success_url sendir glugginn síðuna þína þangað þegar hann lokast eftir greiðslu (með ?session_id=...). Ef það hefur cancel_url fer síðan þangað þegar glugganum er lokað án greiðslu. Slepptu þeim í greiðsluferlinu ef viðskiptavinurinn á að vera áfram á síðunni og kóðinn þinn bregst við onSuccess og onCancel.

Staða greiðslunnar í vafranum

onSuccess og niðurstaðan innihalda paymentStatus:

  • paid: greiðslan fór í gegn, með korti, veski eða kröfu sem var greidd strax.
  • awaiting_claim: krafa með greiðslufresti var send í heimabanka og viðskiptavinurinn greiðir hana seinna. Ekki afhenda strax.

Notaðu niðurstöðuna í vafranum bara til að uppfæra viðmótið. Afgreiddu pantanir út frá webhooks á þjóninum, eins og lýst er í Staðfestu greiðsluna á þjóninum.

Frjálsar greiðslur úr þínu eigin formi

Síða fyrir frjálsar greiðslur (open-payment-pages í API-inu) tekur við framlögum þar sem greiðandinn velur upphæðina, einu sinni eða mánaðarlega, og getur haft fellilista, til dæmis hvaða deild framlagið er fyrir. Ef formið á að vera á þinni eigin síðu býrðu hvert framlag til með POST /v1/open-payment-pages/{id}/checkout-sessions í stað /v1/checkout/sessions og opnar svo greiðsluferlið eins og í skrefi 2. Framlagið skráist á síðuna eins og það hefði verið gefið á síðu Kling: það birtist undir Frjálsum greiðslum í stjórnborðinu með valinu úr fellilistanum, og mánaðarlegt framlag er rukkað um valda upphæð í hverjum mánuði.

typescript
// Á þjóninum, t.d. í leið sem formið þitt sendir á
const res = await fetch(`https://api.kling.is/v1/open-payment-pages/${PAGE_ID}/checkout-sessions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KLING_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 5000, // 5.000 kr.
    cadence: "recurring", // eða "one_time", á síðu sem býður hvort tveggja
    choice_option_slug: "korfubolti",
    // Greiðandinn, úr þínu formi. national_id (kennitala) er valfrjáls.
    customer: { name, email, national_id },
  }),
});
const session = await res.json();
if (!res.ok) return Response.json(session, { status: res.status });
return Response.json({ sessionId: session.id });
  • amount fylgir reglum síðunnar: ein af tillögðum upphæðum hennar, eða hvaða upphæð sem er ef síðan leyfir eigin upphæð.
  • choice_option_id eða choice_option_slug velur úr fellilistanum, og annað þeirra er skylda ef spurningin er það. Val sem síðan hefur ekki er hafnað með choice_field_answer_unknown_option.
  • customer finnur greiðandann eftir kennitölu, svo eftir netfangi, eða stofnar hann. Upplýsingar um greiðanda sem er þegar til eru aðeins fylltar út þar sem þær vantar, aldrei skrifað yfir þær. Ef þú hefur þegar stofnað viðskiptavininn sendirðu customer_id í staðinn.
  • Með customer eða customer_id biður greiðsluglugginn ekki um upplýsingar um greiðandann og opnast beint á greiðslunni. Án þeirra safnar glugginn þeim upplýsingum sem síðan er stillt til að safna.
  • Slepptu success_url og cancel_url ef greiðandinn á að vera áfram á síðunni þinni.

Að halda listanum í takt

Ef valkostirnir í fellilistanum eru geymdir í þínu eigin kerfi geturðu breytt einum í einu í stað þess að senda allan listann aftur með PATCH /v1/open-payment-pages/{id}:

  • POST /v1/open-payment-pages/{id}/choice-options með { name, slug } bætir einum við. Notaðu þitt eigið auðkenni sem slug (lágstafir, tölustafir og bandstrik), þá gildir sama auðkenni í þínu kerfi, í hlekkjum og í choice_option_slug. Slug sem annar valkostur hefur, eða hafði áður, er hafnað með choice_option_slug_taken.
  • PATCH /v1/open-payment-pages/{id}/choice-options/{option} breytir heiti eins, sem er fundinn eftir auðkenni eða slug. Slug-ið breytist aldrei.
  • DELETE /v1/open-payment-pages/{id}/choice-options/{option} fjarlægir einn. Framlög sem þegar hafa verið gefin halda honum, og slug-ið hans fer aldrei á annan valkost, svo gamall hlekkur eða QR kóði opnar aldrei rangan valkost.

Skoða sem markdown