Innfellt kaupferli

Innfellt kaupferli gerir söluaðilum kleift að bjóða kaupferli á eigin vef. Bakendi söluaðila stofnar skammlífa checkout-lotu með leynilegum API-lykli. Vafrinn fær aðeins lotutákn og getur aðeins framkvæmt þær checkout-aðgerðir sem lotan heimilar.

Notaðu innfellt kaupferli þegar verið er að færa eldri PlanVariant og Subscription form yfir í V2 líkanið fyrir vörur, verð, pakka og samninga.

Yfirlit

Venjuleg tenging er í fjórum hlutum:

Setja upp V2 vörulista, verð eða pakkasnið.
Stofna sölurás sem stýrir hvaða tilboð, upprunar og greiðsluleiðir eru í boði.
Stofna checkout-lotu frá bakenda söluaðila.
Setja upp askell.js útgáfuna fyrir innfellt kaupferli með lotutákninu sem var skilað.

Leynilegi API-lykillinn má aðeins vera á bakenda söluaðila.

Stofna lotu

POST /api/v2/checkout-sessions/
Authorization: Api-Key your-secret-api-key
Content-Type: application/json

{
  "sales_channel": "memberships",
  "customer_reference": "seller-user-123",
  "terms_url": "https://seller.example/terms",
  "terms_required": true,
  "metadata": {
    "seller_cart_id": "cart-456"
  },
  "expires_in_seconds": 1800
}

Svar:

{
  "token": "cs_abc123",
  "status": "pending",
  "expires_at": "2026-06-16T12:30:00Z",
  "sales_channel": "memberships",
  "allowed_origins": ["https://seller.example"],
  "theme": {
    "primary_color": "#0F766E"
  }
}

Lotutáknið er öruggt til að senda í vafrann. Það kemur ekki í stað API-lykils söluaðila og er ekki hægt að nota það til að kalla á almennar lokaðar V2 vefþjónustur.

Ef skilmálar eru stilltir á sölurás þarf ekki að senda terms_url eða terms_required þegar lota er stofnuð. Þessir reitir eru aðeins notaðir þegar stök lota á að nota aðra skilmála en sölurásin.

Setja upp widget

<div id="askell-checkout"></div>
<script src="https://cdn.askell.is/js/dist/askell.js"></script>
<script>
  Askell.mountCheckout("#askell-checkout", {
    sessionToken: "SESSION_TOKEN_FROM_SELLER_BACKEND",
    title: "Veldu áskrift",
    description: "Veldu áskriftarleið og viðbætur áður en gengið er frá greiðslu.",
    language: "is",
    colorScheme: "auto",
    onSuccess(result) {
      window.location.href = "/account?checkout=success";
    },
    onError(error) {
      console.error(error);
    }
  });
</script>

askell.js hleður sjálfkrafa fylgjandi askell.css stílsniði úr sömu möppu og skriftan sjálf. Ef skriftan er sjálfhýst þarf því að birta askell.css á sama stað.

Nota má title til að stilla fyrirsögn widgetsins. Ef title er ekki sent notar widgetið sjálfgefna fyrirsögn.

Nota má description til að birta stuttan hjálpartexta undir fyrirsögn á fyrsta skrefi kaupferlisins. Ef description er ekki sent birtist enginn aukatexti.

Nota má language til að velja tungumál fyrir texta widgetsins. Studd gildi eru "is" og "en". Ef language er ekki sent reynir widgetið að nota lang á síðunni, en annars er enska notuð.

Nota má colorScheme til að velja ljóst eða dökkt útlit fyrir widgetið. Studd gildi eru "light", "dark" og "auto". "auto" fylgir prefers-color-scheme stillingu vafrans. Sjálfgefið gildi er "light". Einnig má nota color_scheme ef bakendi söluaðila notar snake_case.

Vafra-API

Vafra-SDK notar endapunkta með lotutákni:

GET  /api/v2/checkout-sessions/{token}/public/
POST /api/v2/checkout-sessions/{token}/quote/
POST /api/v2/checkout-sessions/{token}/payment-processor-options/
POST /api/v2/checkout-sessions/{token}/checkout/
POST /api/v2/checkout-sessions/{token}/payment-method-registrations/
GET  /api/v2/checkout-sessions/{token}/payment-method-registrations/{registration_token}/
POST /api/v2/checkout-sessions/{token}/finalize/

Lotutáknið er sent í URL-slóð þessara vafraendapunkta. Vafrinn getur ekki víkkað reglur lotunnar, breytt tengingu við viðskiptavin, sett handahófskenndar upphæðir eða sent óheimiluð lýsigögn.

Uppsetning sölurása

Sölurásir eru endurnýtanleg checkout-snið. Þær stýra hvað kaupandi má kaupa og hvaðan má nota checkout.

Viðbætur eru sóttar sjálfkrafa úr virkum viðbótarreglum fyrir valdar vörur og pakka. Sölurás þarf ekki að velja viðbótarvörur sérstaklega; aðeins þarf að slökkva á viðbótum á sölurás ef þær eiga ekki að birtast.

Ef verð eru valkostir fyrir sömu vöru, til dæmis mánaðar- og ársverð, má stilla offer_policy.price_selection_mode á "single". Þá birtir widgetið verð sem valkosti þar sem kaupandi velur eitt verð og vefþjónustan hafnar beiðnum sem reyna að kaupa fleiri en eitt grunnverð. Sjálfgefið gildi er "multiple" og heldur eldri hegðun þar sem kaupandi getur valið fleiri en eitt verð.

Sölurás stýrir einnig hvernig widgetið fær tilvísun viðskiptavinar með customer_reference_setting. Gildið "kennitala" birtir reit fyrir íslenska kennitölu og sannreynir hana áður en viðskiptavinur er tengdur við lotuna. Gildið "random" felur reitinn og widgetið býr til handahófskennt UUID sem tilvísun.

Ef valin vara eða vara í pakka er ekki merkt sem rafræn safnar widgetið heimilisfangi kaupanda. Kaupandi getur einnig valið annan afhendingarstað. Þegar land er Ísland birtir widgetið leitarreit fyrir íslensk póstnúmer og fyllir stað út frá póstnúmerinu. Fyrir önnur lönd birtir widgetið frjálsan reit fyrir póstnúmer og sérstakan reit fyrir stað. Widgetið sendir delivery_address með checkout-beiðninni þegar annar afhendingarstaður er valinn og afhendingarstaðurinn er vistaður á samningnum þegar checkout er lokið.

Áður en sölurás er virkjuð skaltu staðfesta að:

vörur séu virkar
verð séu virk
pakkasnið séu með virkum línum og gildum sjálfgefnum verðum
valdir gjaldmiðlar og innheimtutíðni séu samhæfð
heimilaðir upprunar séu skráðir
heimilaðar innheimtuaðferðir séu skráðar
regla um færsluhirða sé annaðhvort tóm, gildur leyfilisti eða einn valinn færsluhirðir reiknings
regla um lýsigögn leyfi aðeins hættulausa rakningarlykla frá framenda

Heimilaðir upprunar verða að vera upprunar eingöngu:

https://seller.example
http://localhost:3000

Ekki setja inn slóðir, query-strengi, auðkenningarupplýsingar eða algildistákn:

https://seller.example/checkout
https://user:pass@seller.example
https://*.seller.example

Skilmálar

Sölurás getur skilgreint skilmála sem kaupandi þarf að samþykkja áður en checkout er stofnað. Þetta er venjulega stillt einu sinni á sölurásinni:

{
  "terms_policy": {
    "url": "https://seller.example/terms",
    "required": true
  }
}

terms_policy.url er slóð á skilmálasíðu söluaðila. terms_policy.required segir að kaupandi verði að samþykkja skilmálana áður en hann getur greitt. Ef url er skráð birtir widgetið tengil við samþykkisreitinn.

Hægt er að yfirskrifa skilmála fyrir staka checkout-lotu með terms_url og terms_required í POST /api/v2/checkout-sessions/. Núverandi lotur halda skyndimynd af skilmálareglu, svo stofna þarf nýja lotu eftir breytingu á sölurás.

Checkout-þema er ekki hluti af sölurásinni. Widgetið notar innbyggt sjálfgefið þema, en bakendi söluaðila getur sent yfirskrift fyrir staka lotu og JavaScript-uppsetning widgetsins getur yfirskrifað einstök þemagildi.

Þemabreytur

Checkout-þemu eru hreinsuð og vistuð sem skyndimynd þegar checkout-lota er stofnuð. Bakendar söluaðila geta sent yfirskrift fyrir staka lotu í beiðni um checkout-lotu:

{
  "sales_channel": "memberships",
  "customer_reference": "seller-user-123",
  "theme": {
    "primary_color": "#0F766E",
    "accent_color": "#2563EB",
    "background_color": "#FFFFFF",
    "surface_color": "#F8FAFC",
    "text_color": "#0F172A",
    "muted_text_color": "#475569",
    "border_color": "#CBD5E1",
    "error_color": "#DC2626",
    "success_color": "#15803D",
    "border_radius": "md",
    "font_family": "system"
  }
}

Innfellda widgetið setur leysta þemað sem CSS-breytur á rótareiningu checkout:

Þemareitur	CSS-breyta	Hlutverk
`primary_color`	`--askell-primary-color`	Aðalhnappar og áhersluaðgerðir.
`accent_color`	`--askell-accent-color`	Aukalitir og stuðningsáherslur.
`background_color`	`--askell-background-color`	Bakgrunnur checkout-síðu.
`surface_color`	`--askell-surface-color`	Vöruspjöld, spjöld og staðfestingarfletir.
`text_color`	`--askell-text-color`	Aðaltexti.
`muted_text_color`	`--askell-muted-text-color`	Aukatexti og lýsingar.
`border_color`	`--askell-border-color`	Rammar og skil.
`error_color`	`--askell-error-color`	Villustöður.
`success_color`	`--askell-success-color`	Staða þegar aðgerð tókst.
`border_radius`	`--askell-border-radius`	Hornradíus widgets.
`font_family`	`--askell-font-family`	Leturstafli widgets.

Litir verða að vera gild hex-gildi, annaðhvort #RGB eða #RRGGBB. Óstuddir þemareitir eru hafnaðir. border_radius styður none, sm, md og lg. font_family styður system, inter og inherit.

API-ið athugar einnig grunnreglur um birtuskil: texti verður að hafa birtuskil við bakgrunns- og yfirborðsliti, aukatexti verður að hafa birtuskil við bakgrunn, og primary_color verður að hafa birtuskil við hvítan hnappatexta.

Hýstir greiðslurammar erfa ekki endilega allar útlitsstillingar widgetsins. Checkout-ramminn notar allt þemað, en skráning greiðslumáta sendir hreinsað lotuþema áfram þar sem valinn færsluhirðir styður það.

Öryggislisti

Geymdu leynilykla aðeins í stillingum eða umhverfisbreytum á bakenda.
Stofnaðu lotur aðeins úr traustum bakendakóða.
Tengdu lotur við customer eða customer_reference þegar checkout er bundið ákveðnum viðskiptavini.
Skráðu heimilaða uppruna áður en sölurás er virkjuð.
Hafðu líftíma lota stuttan.
Leyfðu lykla fyrir framendalýsigögn með skýrum leyfilista.
Staðfestu stofnaðan samning á bakenda áður en greiddur aðgangur er veittur.

Vafrinn má ekki fá:

ASKELL_SECRET_KEY
lokaða API-lykla
leynigögn færsluhirða reiknings
ótakmarkaða reiti fyrir vörur, verð, upphæðir, bókhald, samninga eða flutning
ótakmörkuð lýsigögn

Lýsigögn frá framenda

Bakendalýsigögn má hengja við þegar bakendi söluaðila stofnar lotuna. Framendalýsigögn eru aðeins samþykkt ef sölurásin leyfir lyklana:

{
  "metadata_policy": {
    "frontend_allowed_keys": ["utm_source", "campaign"]
  }
}

Ekki leyfa framendalykla sem hafa áhrif á bókhald, réttindi, tilvísanir samninga, auðkenni eldri flutnings, val á færsluhirði eða auðkenni viðskiptavinar.

Dæmi um Django-bakenda

Með django-askell:

from django.http import JsonResponse
from askell.client import client


def create_askell_session(request):
    result = client.create_checkout_session(
        sales_channel="memberships",
        user=request.user,
        metadata={"source": "pricing-page"},
        expires_in_seconds=1800,
    )
    if result["status"] != "success":
        return JsonResponse(
            {"error": result["response"]},
            status=result["status_code"],
        )
    return JsonResponse({"sessionToken": result["response"]["token"]})

Pakkinn birtir einnig innskráða hjálparsýn á /askell/checkout-session/ þegar URL-slóðir pakkans eru tengdar. Þú getur erft frá sýninni og stillt sales_channel ef rásin á að vera föst á bakenda.

Flutningur úr eldri áætlunarformum

Fyrir hvert eldra PlanVariant sem er birt í framenda söluaðila skal korta það yfir í eitt af eftirfarandi:

V2 CatalogProduct og CatalogPrice
V2 BundleTemplate
upphaflegt stakt CatalogPrice

Stofnaðu síðan sölurás sem birtir aðeins kortuðu V2 tilboðin og skiptu út eldra framendaforminu fyrir innfellt kaupferli.

Eldri aðgangsprófanir ættu að færast frá „virk eldri áskrift að áætlun“ yfir í „virkur V2 samningsliður fyrir vöru eða verð“. Ekki veita aðgang eingöngu út frá callbacki í vafra; staðfestu samninginn sem varð til á bakenda.

Stjórnendastýrður flutningur núverandi lifandi eldri áskrifta er skjalaður í innri flutningshandbók. Innfellt kaupferli breytir aðeins því hvernig nýir kaupendur fara inn í V2 samningslíkanið.

Algengar villur

Lota skilar 404

Algengar ástæður:

tákn er rangt eða úrelt
lota er útrunnin
lota er lokið eða henni hefur verið aflýst
framendi notar tákn úr öðru umhverfi

Stofnaðu nýja lotu og staðfestu tákn, stöðu og gildistíma.

Uppruni passar ekki

Ef checkout virkar staðbundið en bilar í framleiðslu skaltu athuga heimilaða uppruna sölurásarinnar. Núverandi lotur halda skyndimynd af upprunareglu, svo stofna þarf nýja lotu eftir breytingu á sölurás.

Tilboði hafnað

Staðfestu að valið verð, vara, pakki eða viðbót birtist í offer_catalog í opinberum lotugögnum. Ef ekki, uppfærðu tilboðsreglu sölurásarinnar og stofnaðu nýja lotu.

Færsluhirðir ekki tiltækur

Athugaðu að valinn eða festur færsluhirðir reiknings styðji gjaldmiðilinn og innheimtuaðferðina. Innheimtuaðferðir sem eru ekki kort krefjast viðskiptavinar með nauðsynlegan staðfestan greiðslumáta.

Skráning greiðslumáta mistekst

Stofnaðu checkout áður en greiðslumáti er skráður, notaðu skráningartáknið sem lotuendapunkturinn skilar og spurðu reglulega um stöðu á lotubundna skráningarendapunktinum þar til hún nær lokastöðu.

Finalize mistekst

Staðfestu að lotan sé enn í bið, checkoutið tilheyri lotunni og skráning greiðslumáta hafi tekist. Það er öruggt að endurkalla finalize eftir lokna lotu þar sem endapunkturinn skilar sömu niðurstöðu aftur.

Greiðslusíður og sölurásir

Greiðslusíður geta valkvætt tengst sölurás. Eldri greiðslusíður án sölurásar halda sínum síðusértæku stillingum. Þegar sölurás er tengd nota V2 pakkagreiðslusíður leyfilista sölurásarinnar fyrir pakka, innheimtuaðferðir og reglu um færsluhirða.