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
npm install @klingis/embedEða notaðu script-tag, ekkert byggingarskref:
<script src="https://api.kling.is/v1/kling.js"></script>1. Búðu til greiðsluferli á þjóninum
// 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
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:
<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.
// Á þ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 });amountfylgir 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_ideðachoice_option_slugvelur ú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.customerfinnur 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ðucustomer_idí staðinn.- Með
customereðacustomer_idbið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_urlogcancel_urlef 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-optionsmeð{ name, slug }bætir einum við. Notaðu þitt eigið auðkenni semslug(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.