Efni

SkjölunTaktu við greiðslum

Áskriftir og innheimtugátt

Rukkaðu viðskiptavini á Íslandi sjálfkrafa vikulega, mánaðarlega eða árlega með áskriftum í Kling, reyndu aftur þegar greiðsla mistekst og leyfðu viðskiptavinum að sjá um eigin áskrift í innheimtugáttinni.

Áskrift tengir viðskiptavin við vöru sem er rukkuð reglulega og innheimtir sjálfkrafa á hverju tímabili. Kling reynir aftur þegar kortagreiðsla mistekst og heldur skrá yfir hverja greiðslu. Viðskiptavinir sjá sjálfir um áskriftina sína í innheimtugáttinni.

Án forritunar

  1. Í stjórnborðinu opnar þú Vörur og býrð til áskriftarvöru með verði og tímabili (vika, mánuður eða ár), og prufutíma ef þú vilt.
  2. Opnaðu Greiðsluhlekkir og búðu til hlekk með vörunni. Það er áskriftarhlekkurinn þinn.
  3. Deildu honum. Viðskiptavinurinn skráir sig og greiðir fyrsta tímabilið með korti, og Kling rukkar kortið í byrjun hvers nýs tímabils.

Með API

Búðu til vöru og sendu svo viðskiptavininn í gegnum greiðsluferli með product_id vörunnar (hann slær inn kortið og áskriftin hefst; checkout.session.completed telur nýju áskriftirnar upp í data.subscription_ids), eða stofnaðu áskriftina beint fyrir viðskiptavin sem á vistað kort:

bash
curl -X POST https://api.kling.is/v1/subscriptions \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "product_id": "PRODUCT_ID",
    "payment_method_id": "PAYMENT_METHOD_ID"
  }'

Auðkenni eru UUID. Án prufutíma rukkar Kling fyrsta tímabilið strax. Ef þeirri fyrstu rukkun er hafnað sýnir áskriftin samt active og ekki er reynt aftur, svo athugaðu greiðsluna áður en þú afhendir: bíddu eftir payment_intent.captured (eða payment_intent.failed) með data.subscription_id. Án payment_method_id er kortaáskrift aldrei rukkuð.

collection_method er card (sjálfgefið) eða bank_claim, sem sendir kröfu í heimabanka á hverju tímabili í stað þess að rukka kort. Áskrift með bank_claim þarf payment_method_id fyrir kröfugreiðslumáta með kennitölu greiðanda; án hans er engin krafa nokkurn tíma send. Krafa hvers tímabils kemur fram í claim.created, svo claim.paid og payment_intent.captured þegar hún er greidd. subscription.renewed, subscription.payment_failed og sjálfvirkar nýjar tilraunir eiga aðeins við um kortaáskriftir.

Aðrir endapunktar: POST /v1/subscriptions/{id}/cancel, POST /v1/subscriptions/{id}/reactivate og POST eða DELETE /v1/subscriptions/{id}/discount.

Til að færa áskrift yfir á aðra vöru, til dæmis stærri pakka, sendirðu PATCH /v1/subscriptions/{id} með product_id. Breytingin tekur gildi í upphafi næsta tímabils og ekkert er hlutfallsreiknað: yfirstandandi tímabil helst eins og það var rukkað og við næstu endurnýjun er verð nýju vörunnar rukkað. Þangað til sýnir áskriftin breytinguna í pending_update (product og effective_at). Nýja varan þarf að vera virk áskriftarvara í sama gjaldmiðli og með sama greiðslutímabil. Sé núverandi vara send aftur fellur breytingin niður. Atburðirnir eru subscription.product_change_scheduled þegar beðið er um breytinguna og subscription.product_changed þegar hún tekur gildi.

Til að rukka alla áskrifendur sama dag mánaðarins setur þú billing_day (1 til 28) á mánaðarlega áskriftarvöru. Nýjar áskriftir að vörunni fá þann dag og einnig má stilla hann fyrir hverja áskrift fyrir sig með billing_day í POST /v1/subscriptions eða PATCH /v1/subscriptions/{id}. Greiðslan við skráningu gildir fyrir fyrsta tímabilið. Fyrsta endurnýjun er fyrsti greiðsludagur sem er að minnsta kosti first_renewal_min_days dögum eftir skráningu (sjálfgefið 10, 0 gerir regluna óvirka), annars sá næsti á eftir. Með billing_day 5 er áskrift sem stofnuð er 17. október endurnýjuð 5. nóvember, en áskrift sem stofnuð er 28. október þann 5. desember. Eftir það er rukkað á greiðsludeginum í hverjum mánuði. Ekkert er reiknað hlutfallslega. Breyting á billing_day áskriftar tekur gildi við næstu endurnýjun og dagurinn helst óbreyttur við vöruskipti.

Líftími áskriftar

Staða Merking
trialing Á prufutíma. Verður active þegar prufutímanum lýkur, rétt áður en fyrsta rukkunin fer fram; ef hún mistekst fer áskriftin í past_due.
active Greidd og endurnýjast.
past_due Kortagreiðsla mistókst. Kling reynir aftur, eða rukkun er stöðvuð þar til úr er leyst.
canceled Lokið: eftir uppsögn, afdráttarlausa höfnun, eða þegar allar tilraunir mistókust.

Þegar endurnýjun með korti er hafnað reynir Kling aftur 1, 3 og 7 dögum eftir hverja fyrri tilraun (þrjár tilraunir). Ef tilraun tekst fer áskriftin aftur í active; ef allar mistakast er henni sagt upp. Kort sem getur aldrei gengið (til dæmis tilkynnt týnt, eða lokaður reikningur) segir áskriftinni upp strax, án nýrra tilrauna. Ef færsluhirðirinn hafnar sjálfri rukkuninni, eða getur ekki sagt til um hvort hún fór í gegn, stöðvast rukkun í past_due án nýrra tilrauna þar til úr er leyst.

Sjálfgefið tekur uppsögn gildi í lok yfirstandandi tímabils, svo viðskiptavinurinn heldur því sem hann greiddi fyrir; þangað til er áskriftin active og sýnir cancel_at_period_end: true. Til að ljúka henni strax sendir þú "cancel_immediately": true. Webhookið subscription.canceled berst bæði þegar beðið er um uppsögnina og þegar áskriftinni lýkur, svo athugaðu status áður en þú lokar á aðgang.

GET /v1/subscriptions/{id} telur upp greiðslur áskriftarinnar, hverja með billing_reason, subscription_create (sú fyrsta) eða subscription_cycle (endurnýjun), svo þú veist alltaf hvað var rukkað og hvers vegna. Varðandi hvaða webhooks þú meðhöndlar: subscription.renewed nær aðeins yfir greiddar endurnýjanir með korti. Fyrsta rukkun eftir prufutíma berst sem payment_intent.captured með data.subscription_id, og endurnýjun sem greiðist í nýrri tilraun sendir líka subscription.payment_recovered.

Innheimtugátt

Innheimtugáttin er síða þar sem viðskiptavinurinn sér áskriftina sína og nýlegar greiðslur, uppfærir kortið, segir upp og virkjar aftur. Búðu til gáttarsetu og sendu viðskiptavininn á url hennar:

bash
curl -X POST https://api.kling.is/v1/billing-portal/sessions \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "CUSTOMER_ID", "return_url": "https://example.is/adgangur" }'

Valkostir: subscription (takmarka við eina áskrift), allow_cancel og allow_update_payment_method (bæði sjálfgefið á) og expires_in í sekúndum (sjálfgefið 1800).

Til að leyfa viðskiptavini að skipta um kort á áskrift býrðu til gáttarsetu með subscription stillt á hana. Kortið sem hann slær inn í gáttinni verður strax kort áskriftarinnar.

Til að senda viðskiptavininn beint á kortaform, án þess að fara í gegnum gáttina, býrðu til kortavistunarsetu (e. setup session) með subscription stillt á áskriftina. Viðskiptavinurinn vistar kort á greiðslusíðu Kling, það verður kort áskriftarinnar og hann er síðan sendur á success_url:

bash
curl -X POST https://api.kling.is/v1/payment-methods/setup \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "CUSTOMER_ID", "subscription": "SUBSCRIPTION_ID", "success_url": "https://example.is/account" }'

Án subscription vistar setan aðeins kort fyrir viðskiptavininn og breytir engri áskrift.

Ef áskriftin er past_due er ógreidda greiðslan rukkuð strax á nýja kortið, líka þegar rukkun hefur verið stöðvuð. Ef hún gengur í gegn fer áskriftin aftur í active og þú færð payment_intent.captured og subscription.payment_recovered. Ef nýja kortinu er hafnað færðu payment_intent.failed og nýjar tilraunir halda áfram eins og áður: höfnunin telst ekki sem tilraun og segir áskriftinni ekki upp.

Skoða sem markdown