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",
  "contract_reference": "order-1042",
  "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"
  },
  "contract_reference": "order-1042"
}

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.

metadata lotunnar er skilað í GET /api/v2/checkout-sessions/{token}/ og afritað á samninginn þegar checkout er lokið, sjá Lýsigögn á samningnum.

Með contract_reference getur bakendinn gefið samningnum sem lotan stofnar eigin tilvísun, til dæmis pöntunarnúmer, sjá Tilvísun samnings.

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.

Fast tilboð og forval

Sjálfgefið birtir widgetið öll tilboð sölurásarinnar á fyrsta skrefi kaupferlisins og velur fyrsta verðið sem er í boði. Söluaðili getur í staðinn fest tilboðið eða valið það fyrir fram.

Með offer er tilboðið fast. Widgetið sleppir þá fyrsta skrefinu, þar sem kaupandi velur tilboð, og kaupandi getur ekki breytt tilboðinu:

Askell.mountCheckout("#askell-checkout", {
  sessionToken: "SESSION_TOKEN_FROM_SELLER_BACKEND",
  offer: {
    items: [{ price: 123, quantity: 1 }]
  }
});

Með defaultOffer (eða default_offer) er tilboðið valið fyrir fram en fyrsta skrefið birtist áfram, svo kaupandi getur breytt valinu áður en hann heldur áfram. Þetta hentar til dæmis þegar kaupandi kemur af síðu ákveðinnar vöru en sölurásin býður fleiri vörur:

Askell.mountCheckout("#askell-checkout", {
  sessionToken: "SESSION_TOKEN_FROM_SELLER_BACKEND",
  defaultOffer: {
    items: [{ price: 123, quantity: 2 }],
    promotion_code: "HAUST25"
  }
});

defaultOffer notar reitina items, initial_items, bundle_template, bundle_quantity, bundle_item_selections og promotion_code. Aðrir reitir, til dæmis additional_items og additional_bundles, eru hunsaðir og viðbætur byrja óvaldar eins og annars. Magn er takmarkað við lágmark og hámark verðsins eða pakkasniðsins. Ef bæði offer og defaultOffer eru send gildir offer og defaultOffer er hunsað.

Auðkenni í defaultOffer verða að vera í offer_catalog lotunnar. Verð eða pakkasnið sem er ekki í boði, eða er uppselt, er hunsað og widgetið skrifar aðvörun með console.warn. Ef ekkert gilt stendur eftir notar widgetið venjulega sjálfgefna valið.

Í bundle_item_selections er aðeins hægt að velja fyrir fram verðvalkost fyrir skyldulínur pakkans (required: true), því kaupandi getur ekki valið annað í widgetinu. Færslur fyrir valkvæðar línur (required: false), færslur með include: false og magn (quantity) einstakra lína eru hunsuð með sömu aðvörun; notaðu fast offer til að selja pakka með slíkum línum eða breyttu magni. Verðvalkostur sem línan býður ekki er einnig hunsaður og línan heldur sjálfgefnu verði sínu. Einskiptis vörur (initial_items) er ekki hægt að velja fyrir fram ásamt pakka og þær eru hunsaðar með sömu aðvörun; notaðu fast offer til að selja pakka með einskiptis vörum.

promotion_code í offer eða defaultOffer er virkur frá upphafi, eins og kaupandi hefði slegið hann inn, og kaupandi getur fjarlægt hann á yfirferðarskrefinu. Ef kóðanum er hafnað er hann fjarlægður og ástæðan birtist við reitinn. Fyrir offer er villan einnig send til onError. Fyrir defaultOffer skrifar widgetið í staðinn aðvörun með console.warn, því kaupandi getur breytt valinu og þannig sjálfur valdið því að kóðinn á ekki lengur við.

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.

Widgetið sleppir kortaskráningu aðeins þegar ekkert er til greiðslu núna og tilboðið inniheldur engar endurteknar vörulínur, til dæmis ókeypis stök kaup. Tilboð með endurteknum vörulínum skráir alltaf kort áður en checkout er lokið, jafnvel þótt upphafsupphæðin sé núll vegna prufutíma eða fulls afsláttar á fyrsta tímabili, því kortið er skuldfært þegar fyrsta greidda tímabilið hefst. finalize endapunkturinn framfylgir sömu reglu og hafnar beiðninni með payment_method villu ef viðskiptavinurinn hefur engan staðfestan greiðslumáta hjá völdum færsluhirði.

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

Ef reikningurinn hefur skilgreint virka sendingarmöguleika birtir widgetið einnig sendingarval þegar karfan inniheldur vöru sem er ekki rafræn. Vafraendapunkturinn GET /api/v2/checkout-sessions/<token>/public/ skilar shipping_options og GET /api/v2/checkout-sessions/<token>/shipping-locations/?option=<id> skilar afhendingarstöðum fyrir möguleika sem krefjast staðarvals, til dæmis póstbox eða Dropp-afhendingarstaði. Checkout-beiðnin sendir þá shipping hlut með option og eftir atvikum location_id, og valið er vistað sem shipping_selection á samningnum þegar checkout er lokið.

Listinn í public/ er óverðlagður; sendingarleið með verðskrá eftir svæðum og þyngd kemur þar með price_amount: null og requires_zip: true. Tilboðsbeiðnin (quote/) tekur við delivery_zip_code og svarið skilar shipping_options með leiðunum verðlögðum fyrir það póstnúmer og þyngd vörunnar í tilboðinu (zone og weight_band segja hvaða reitur verðskrárinnar gilti); leið sem verðskráin nær ekki yfir sendinguna er sleppt. Widgetið sendir póstnúmerið með hverri tilboðsbeiðni eftir að heimilisfang hefur verið skráð og birtir listann úr tilboðinu. Checkout-beiðnin er verðlögð á sama hátt út frá delivery_address (annars heimilisfangi viðskiptavinarins) og hafnað með 400, shipping skýringu og shipping_code nái verðskráin ekki yfir sendinguna. Skili tilboðið tómum shipping_options lista þótt reikningurinn bjóði sendingarleiðir stöðvar widgetið kaupin á yfirferðarskrefinu og segir að engin leið sé í boði fyrir afhendingarstaðinn.

Tilboðsbeiðnin tekur einnig við shipping hlutnum sjálfum, eins og checkout-beiðnin. Þegar hann fylgir með er sendingargjaldið reiknað og lagt við subtotal_amount, tax_amount og total_amount tilboðsins, og skilað sér í shipping_fee (amount, subtotal_amount, tax_amount, total_amount). Sendi fyrsta tímabilið enga vöru — prufutímabil frestar vörunum til fyrstu endurnýjunar, sem verður þá fyrsta sendingin — er shipping_fee null og gjaldið hvergi í upphæðum tilboðsins; það er rukkað með fyrstu innheimtunni sem sendir vöru. Fylgi enginn shipping hlutur er shipping_fee einnig null; sé sendingin ókeypis — til dæmis vegna fríðindamarka eða afhendingar í verslun — er shipping_fee skilað með núllum svo hægt sé að sýna kaupanda að sendingin kosti ekkert. Fríðindamörkin eru metin eftir að afsláttarkóðinn hefur verið dreginn frá, alveg eins og við stofnun checkout, og tilboðinu er hafnað með sama 400 og shipping / shipping_code og checkout-beiðninni nái verðskráin ekki yfir sendinguna. Widgetið sendir valið með hverri tilboðsbeiðni og biður um nýtt tilboð þegar kaupandi skiptir um sendingarleið eða afhendingarstað, og birtir sendingargjaldið sem eigin línu á yfirferðarskrefinu. Þannig er upphæðin sem kaupandi sér sú sama og skuldfærð er. Endurnýjanir verðleggja sína eigin sendingu og recurring_total_amount inniheldur hana því ekki.

Ef reikningurinn hefur virkan afsláttarkóða sem kaupandi getur notað skilar GET /api/v2/checkout-sessions/<token>/public/ has_coupons: true og widgetið birtir reit fyrir afsláttarkóða á yfirferðarskrefinu. Kóðinn er sannreyndur með promotion_code í tilboðsbeiðninni (quote/), sendur aftur með checkout-beiðninni og sannreyndur að nýju þegar checkout er lokið. Svar tilboðsbeiðninnar inniheldur discount með upphæð afsláttarins, gildistíma hans (once, repeating eða forever) og afsláttarverði endurnýjunar (recurring_final_amount). Afsláttir sem eru aðeins settir á af söluaðila (án afsláttarkóða) birta engan reit, eins og á greiðslusíðum. Ef afsláttarkóðar eru ekki virkjaðir fyrir reikninginn er promotion_code hafnað í tilboðsbeiðni, við stofnun checkout og þegar checkout er lokið, og sömuleiðis þegar samningur er stofnaður beint gegnum API-ið. Ef kóði hættir að gilda milli stofnunar og loka checkout — eða ef söluaðili breytir skilmálum hans á meðan — er það checkout afturkallað og aftengt lotunni svo hægt sé að stofna nýtt. Bæði tilvik skila 400 með promotion_code; breyttir skilmálar fylgja einnig code: "promotion_terms_changed".

Áð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.
Hafnaðu framendalýsigögnum eða leyfðu lykla fyrir þau 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

Bakendi söluaðila getur hengt lýsigögn við lotuna með metadata þegar hann stofnar hana (POST /api/v2/checkout-sessions/). Regla sölurásarinnar um lýsigögn nær ekki til þeirra.

Vafrinn getur líka sent metadata þegar hann stofnar checkout í lotunni (POST /api/v2/checkout-sessions/{token}/checkout/) eða skráir greiðslumáta. frontend_allowed_keys í metadata_policy sölurásarinnar ræður hvaða lykla hann má senda. metadata_policy getur verið:

{}, eða frontend_allowed_keys með gildið null: vafrinn má senda lýsigögn með hvaða lyklum sem er. Eldri sölurásir sem hafa engan frontend_allowed_keys reit haga sér svona.
{"frontend_allowed_keys": []}: vafrinn má ekki senda nein lýsigögn. Beiðni án metadata eða með tómum metadata hlut er samt samþykkt. Nýjar sölurásir sem eru stofnaðar í stjórnborðinu fá þessa stillingu sjálfgefið.
{"frontend_allowed_keys": ["utm_source", "campaign"]}: vafrinn má aðeins senda lyklana á listanum.

Ef vafrinn sendir lykil sem reglan leyfir ekki er beiðninni hafnað með 400 og metadata villu.

Reglan er vistuð í skyndimynd þegar lotan er stofnuð. Breyting á sölurás gildir því aðeins um lotur sem eru stofnaðar eftir breytinguna.

Aðvörun

Sölurás sem leyfir hvaða lykla sem er („Allir lyklar viðbótargagna“ í stjórnborðinu, vistað sem {}) takmarkar ekki vafrann: hann má senda hvaða lykla sem er og þeir enda á samningnum. Eldri sölurásir eru stilltar svona. Veldu „Aðeins skráðir lyklar“ og skráðu lyklana sem vafrinn þarf, eða „Engin viðbótargögn úr vafra“. Settu allt sem skiptir máli, til dæmis pöntunarnúmer eða annað sem samþættingin treystir, í lýsigögn lotunnar á bakenda, því gildi lotunnar gengur framar gildi vafrans fyrir sama lykil. Lyklar sem Áskell notar sjálfur eru aldrei afritaðir á samninginn.

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.

Lýsigögn á samningnum

Þegar checkout er lokið eru lýsigögnin afrituð í metadata á samningnum sem verður til. Þau fylgja því samningnum í V2 samningsvefþjónustunni og í öllum subscription_contract.* vefkrókum, þar á meðal subscription_contract.created:

Lýsigögn lotunnar eru áfram á lotunni (GET /api/v2/checkout-sessions/{token}/) og eru afrituð á samninginn.
Lýsigögn vafrans eru vistuð á checkout og afrituð á samninginn.
Lýsigögn sem bakendi sendir með POST /api/v2/checkouts/, án lotu, eru vistuð á checkout og afrituð á samninginn á sama hátt.

Senda lotan og vafrinn sama lykil gildir gildi lotunnar, því það kemur frá bakenda söluaðila. Niðurstaðan er sú sama hvort sem checkout er lokið í vafranum (POST /api/v2/checkout-sessions/{token}/finalize/) eða á bakenda (POST /api/v2/checkouts/{token}/finalize/).

Lyklar sem Áskell notar sjálfur á samningum, til dæmis billing_anchor_mode sem breytir því hvenær er innheimt, eru ekki afritaðir á samninginn heldur verða aðeins eftir á lotunni eða checkout. Listinn er í Tilvísun og lýsigögn samnings.

Áskell skráir uppruna samningsins í askell_source. Samningur úr lotu fær til dæmis:

{
  "seller_cart_id": "cart-456",
  "utm_source": "newsletter",
  "askell_source": {
    "type": "checkout_session",
    "checkout_session_token": "cs_abc123",
    "checkout_id": 15,
    "checkout_token": "f2dd7db2-4ae1-45c0-b8f6-2f98d1b70a9a"
  }
}

Samningur úr POST /api/v2/checkouts/ án lotu fær "type": "checkout", checkout_id og checkout_token en engan checkout_session_token.

Tilvísun samnings

Bakendi söluaðila getur gefið samningnum eigin tilvísun, til dæmis pöntunarnúmer, með contract_reference. Hann sendir hana þegar hann stofnar lotuna (POST /api/v2/checkout-sessions/) eða þegar hann stofnar checkout án lotu (POST /api/v2/checkouts/). Þegar checkout er lokið fer tilvísunin í reference á samningnum um leið og hann verður til. Hún er því í öllum subscription_contract.* vefkrókum, þar á meðal subscription_contract.created, og GET /api/v2/subscription-contracts/?reference=... finnur samninginn strax. Ekki þarf þá að bæta henni við eftir á með PATCH, sem gerist of seint fyrir fyrstu vefkrókana.

Aðeins bakendi söluaðila getur sett tilvísunina, aldrei vafrinn. Sendi vafrinn contract_reference þegar hann stofnar checkout í lotunni er beiðninni hafnað með 400. Tilvísunin er hvorki í opinberum lotugögnum né í svörum til vafrans.
Hún má vera að hámarki 128 stafir og má ekki innihalda kommu; annars er beiðninni hafnað með 400 og villu á contract_reference. Bil fremst og aftast eru fjarlægð og autt gildi eða null þýðir engin tilvísun.
Hún þarf ekki að vera einkvæm og ?reference= skilar því lista.
GET /api/v2/checkout-sessions/{token}/ skilar tilvísun lotunnar og GET /api/v2/checkouts/{token}/ tilvísun checkout. Checkout sem vafrinn stofnar í lotu hefur enga eigin tilvísun, og samningurinn fær tilvísun lotunnar.

contract_reference er ekki það sama og customer_reference. customer_reference er tilvísun viðskiptavinarins og bindur lotuna við viðskiptavin, en contract_reference er tilvísun samningsins sem verður til.

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

Þegar áskriftarlíkan aðgangsins er orðið contracts hætta eldri form sem selja PlanVariant að virka, og þau hafna kaupum áður en nokkuð er skuldfært. POST /api/checkouts/ með plan og greiðslusíður sem selja eldri áskriftarleiðir svara með villu 400 og code legacy_subscriptions_disabled. Áskriftarhnappurinn hafnar kaupum á sama hátt, áður en viðskiptavinur er stofnaður, en svarar með villusíðu (400) fyrir kaupandann en ekki JSON svari með code. POST /api/checkouts/ án plan (skráning korts eða stök upphæð) virkar áfram. Skiptu formunum því út fyrir innfellt kaupferli áður en aðgangurinn er færður yfir. Sjá Áskriftir.

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. Tilboð með endurteknum vörulínum krefst staðfests greiðslumáta þótt upphafsupphæðin sé núll. Þ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.

Geymt verðtilboð greiðslusíðu

POST /public/api/payment-pages/quote/ skilar nú quote_token og expires_at ásamt verðtilboðinu sjálfu. Verðið er reiknað einu sinni, geymt á PaymentPageQuote og gildir í 30 mínútur. Svarið ber einnig promotion: afsláttarkóðann sem verðið var reiknað með, í sama sniði og validate_promotion_code skilar, eða null hafi kóðinn ekki átt við lengur. Yfirlitið á síðunni sýnir afsláttinn úr tilboðinu, ekki úr fyrri staðfestingu kóðans. Endapunkturinn er takmarkaður við 120 beiðnir á mínútu á hverja IP-tölu (PAYMENT_PAGE_QUOTE_THROTTLE).

Öll síðari skref taka við quote_token og verðleggja út frá geymda tilboðinu: kortalotur (POST /adyen/checkout/ og POST /teya/checkout/), POST /public/api/payment-pages/verify_card/ og POST /public/api/payment-pages/process_payment_and_finalize/. Með tókanum er upphæðin total_amount úr tilboðinu, sendingargjaldið er innheimt óbreytt eins og það var verðlagt, afsláttarkóðinn er sá sem tilboðið notaði og sendingarvalið er vistað úr geymdu afriti. Tilboðið er nýtt þegar samningur verður til; sami tóki verður ekki notaður aftur.

Vörulínur (items, initial_items, bundle_template_id, bundle_selections, additional_items, additional_bundles), promotion_code, shipping og zip_code sem verðlagsinntak eru úrelt á þessum endapunktum. Þau virka enn í eina útgáfu fyrir eldri vafraútgáfur og eru þá skráð með aðvörun í annál, en verða fjarlægð í næstu útgáfu. zip_code sem hluti af heimilisfangi viðskiptavinar við process_payment_and_finalize heldur sér.

Villukóðar þegar geymt tilboð stenst ekki:

quote_not_found: Tókinn finnst ekki (HTTP 404).
quote_page_mismatch: Tókinn tilheyrir annarri greiðslusíðu.
quote_expired: Tilboðið er útrunnið; síðan þarf að sækja nýtt verðtilboð.
quote_consumed: Þegar hefur verið greitt eftir þessu tilboði.
quote_mismatch: Kortið var staðfest (eða kortalotan stofnuð) fyrir annað tilboð en það sem sent er í process_payment_and_finalize.
quote_changed: Verðskrá eða tilboð hefur breyst síðan verðið var gefið.
promotion_terms_changed: Skilmálum afsláttarkóðans var breytt eftir að tilboðið var gefið.
combo_eligibility_changed: Pakkaafslættir sem eiga við hafa breyst.
invalid_promotion_code: Geymdi afsláttarkóðinn gildir ekki lengur.

Á verify_card og process_payment_and_finalize skila villurnar {"message": ..., "code": ...} með HTTP 400, nema quote_not_found sem skilar HTTP 404. Kortalotu-endapunktarnir (POST /adyen/checkout/ og POST /teya/checkout/) halda sínu sniði og skila sömu kóðum sem {"error": ..., "code": ...} með sömu stöðukóðum.

Greiðslusíða sem er eydd tekur tilboðin sín ekki með sér: ógreidd tilboð hætta að gilda (quote_page_mismatch) en greidd tilboð halda tengingunni við samninginn.