Áskriftarsamningar V2

Áskriftarsamningar V2 eru nýja áskriftarlíkan Áskels. Það er aðskilið frá eldra PlanVariant / Subscription flæði og byggir í staðinn á vörulista, verði, pökkum, verðútreikningum, greiðslugangi og innheimtulotum.

Öll köll í V2 vefþjónustur krefjast leynilegs API lykils:

Authorization: Api-Key your-secret-api-key

Eldri token-auðkenning er enn studd í sumum V2 köllum til samræmis við eldri samþættingar. Nýjar samþættingar ættu þó að nota leynilega API lykla.

Stutt yfirlit yfir dæmigert flæði

Algengt samþættingarflæði er þetta:

1. Sækja vörur, verð eða pakka úr vörulista.

2. Reikna verðútreikning með POST /api/v2/subscription-offer-quotes/.

3. Sækja mögulega færsluhirða með POST /api/v2/payment-processor-options/.

4. Stofna checkout með POST /api/v2/checkouts/.

5. Ganga frá checkout með POST /api/v2/checkouts/{token}/finalize/.

6. Fylgjast með stöðu checkout og, eftir atvikum, upphaflegri innheimtulotu.

Ef samþættingin þarf ekki greiðsluforvinnu má sleppa skrefum 3-5 og stofna samning beint með POST /api/v2/subscription-contracts/.

Sjá einnig

Fyrir eldra áskriftarflæði út frá PlanVariant og Subscription skal sjá Áskriftir.

Aðvörun

checkout_url í V2 er ekki opin hýst greiðslusíða. Hún vísar á API slóð fyrir checkout hlutinn sjálfan og hentar því fyrir kerfi-í-kerfi samþættingar, ekki fyrir beina endurvísun notanda í vafra.

Hvenær á að nota V2

V2 á að nota þegar selja á vörur og áskriftir út frá vörulista í stað eldri plana og PlanVariant auðkenna. Þar á meðal:

1. Þegar selja á stakar vörur eða samsetningu vara sem áskriftarsamning.

2. Þegar nota á pakka með vali á verði og magni.

3. Þegar skipuleggja þarf verðbreytingar með verðútgáfum.

4. Þegar halda á utan um endurteknar innheimtulotur með skýrari sögu og möguleika á endurtekningu.

Eldri greiðslusíður og eldra /api/subscriptions/ flæði halda áfram að nota eldra Subscription líkanið og eru skjöluð sér undir Áskriftir.

Kjarna hlutir

Helstu V2 hlutirnir eru þessir:

Hlutur	Lýsing
CatalogProduct	Vara í vörulista.
CatalogPrice	Stöðugt verðauðkenni sem samningur tengist.
CatalogPriceVersion	Tímabundin verðútgáfa sem skilgreinir upphæð á tímabili.
BundleTemplate	Sölupakki sem sameinar eina eða fleiri vörur.
SubscriptionContract	Nýi varanlegi áskriftarsamningurinn.
BillingRun	Ein innheimtulota á samningi.
BillingRunAttempt	Stök tilraun til að innheimta lotu.
V2Checkout	Millihlutur sem geymir verðútreikning og greiðsluforsendur áður en samningur er stofnaður.

Áður en byrjað er

Áður en hægt er að ganga frá greiðslugangi eða stofna samning þarf eftirfarandi að vera til staðar:

1. Viðskiptavinur þarf þegar að vera til í Áskeli.

2. Færsluhirðir (AccountPaymentProcessor) þarf að vera uppsettur fyrir viðeigandi gjaldmiðil og greiðsluaðferð.

3. Ef nota á checkout / finalize ferlið þarf viðskiptavinurinn þegar að vera með staðfestan greiðslumáta sem passar við valinn færsluhirði.

Sjá einnig Forsendur áður en finalize er kallað, þar sem nánar er farið yfir hvað er staðfest rétt áður en finalize stofnar samning og innheimtu.

Leit í vörulista

Til að sækja vörur og verð í vörulista má nota eftirfarandi slóðir:

curl https://askell.is/api/v2/catalog/products/ \
  -H "Authorization: Api-Key your-secret-api-key"

curl "https://askell.is/api/v2/catalog/prices/?billing_type=recurring&currency=ISK" \
  -H "Authorization: Api-Key your-secret-api-key"

Algengar síur á vörulista:

Sía	Lýsing
active	Sjálfgefið eru aðeins virk gögn sýnd. Nota má all eða any.
reference	Tilvísun á vöru eða pakka, eftir slóð.
product	Auðkenni vöru eða vöru-tilvísun á verðslóð.
currency	Gjaldmiðill verðs.
billing_type	recurring eða one_time.
recurrence_type	Tegund endurtekningar fyrir endurtekin verð.

Verðútgáfur

Í V2 tengist samningur stöðugu CatalogPrice auðkenni, en sjálf upphæðin getur breyst með tímanum í gegnum CatalogPriceVersion. Þetta gerir kleift að skipuleggja verðbreytingar fyrirfram án þess að viðskiptavinur þurfi að flytjast á nýtt verðauðkenni.

Í svörum frá verðslóðum vörulistans birtast meðal annars eftirfarandi reitir:

Reitur	Lýsing
unit_amount	Núverandi sýnd upphæð fyrir verðið.
current_version_id	Auðkenni þeirrar verðútgáfu sem telst virk núna.
versions	Fortíðar-, núverandi- og framtíðar verðútgáfur.
effective_from	Upphaf gildistíma þeirrar útgáfu sem nú er sýnd.
effective_to	Lok gildistíma þeirrar útgáfu sem nú er sýnd.

Samþættingar sem þurfa aðeins að vita núverandi upphæð geta yfirleitt lesið unit_amount. Samþættingar sem vilja sýna eða skipuleggja verðbreytingar ættu að nota versions.

Pakkar og verðval

Pakkar eru sóttir á sérstökum vefslóðum:

curl https://askell.is/api/v2/bundle-templates/ \
  -H "Authorization: Api-Key your-secret-api-key"

curl https://askell.is/api/v2/bundle-templates/42/ \
  -H "Authorization: Api-Key your-secret-api-key"

Pakki getur innihaldið fasta vöruuppsetningu, leyft val á verði fyrir ákveðna pakkaliði eða notað sjálfkrafa virk endurtekin verð á tengdri vöru.

Viðbótarvörur

Þegar pakki hefur verið valinn og viðeigandi verðval tiltekið er hægt að spyrja hvaða viðbótarvörur eða viðbótarpakkar séu í boði:

curl https://askell.is/api/v2/bundle-templates/42/addons/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_item_selections": [
      {
        "bundle_item": 100,
        "selected_price": 200
      }
    ]
  }'

Verðútreikningur og beiðnigögn

Sömu grunnreitir eru notaðir aftur og aftur í verðútreikningum, greiðslugangsferli og beinni stofnun samninga.

Reitur	Lýsing
bundle_template	Auðkenni valins pakka.
bundle_quantity	Magn pakka.
bundle_item_selections	Val á verði eða magni fyrir einstaka liði innan pakka.
items	Beint valdar endurteknar vörur án pakka.
initial_items	Einskiptis vörur eða vörur sem eiga aðeins að birtast í fyrstu innheimtu.
initial_billing_mode	Stýrir hvort upphafstímabil sé ekki innheimt, innheimt strax eða sett á næstu innheimtu.
additional_items	Viðbótarvörur sem valdar eru út frá viðbótarreglum.
additional_bundles	Viðbótarpakkar sem valdir eru út frá viðbótarreglum.

Aðeins eitt aðalinnsláttarform fyrir endurtekna vöru má nota í einu:

• bundle_template

• items

initial_items eru aðeins notaðir við upphaflega innheimtu. Þeir verða ekki varanlegir SubscriptionContractItem liðir. Sjá einnig kaflann Bein stofnun samnings.

Föst innheimtudagsetning

Endurtekin mánaðarleg eða árleg verð geta haft billing_day_of_month. Ef fleiri en eitt endurtekið verð í sama verðútreikningi eða samningi hefur slíkan dag verða þau að vísa á sama dag mánaðarins. Ekki er hægt að blanda saman verði sem eru föst á mismunandi daga, til dæmis eitt verð á 1. degi og annað á 15. degi mánaðarins.

Það má hins vegar blanda saman verði með föstum degi og verði án billing_day_of_month. Verð án eigin dags fylgja þá eina fasta deginum sem er til staðar í samningnum.

Verðútreikningur áður en samningur er stofnaður

POST /api/v2/subscription-offer-quotes/ býr til óvaranlegan verðútreikning út frá beiðnigögnunum og skilar samantekt á endurteknum línum, upphafslínum, sköttum, samtölum og áætlaðri tímasetningu innheimtu.

Fyrir endurtekna liði aðgreinir svarið nú:

• first_period_recurring_*: það sem er gjaldfært í fyrstu lotu, þar með talið upphafshlutfallsgreiðsla þegar fyrsta lotan er styttri en venjuleg endurnýjunarlota.

• recurring_*: venjuleg endurnýjunarfjárhæð eftir að fyrsta styttri lota er liðin.

Á einstökum endurteknum línum eru einnig birt service_period_start_at, service_period_end_at, proration_factor og renewal_line_* svo samþætting geti sýnt skýrt muninn á fyrstu innheimtu og seinni endurnýjunum.

Dæmi um verðútreikning fyrir pakka:

curl https://askell.is/api/v2/subscription-offer-quotes/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_template": 42,
    "bundle_quantity": 2,
    "bundle_item_selections": [
      {
        "bundle_item": 100,
        "selected_price": 200
      }
    ],
    "additional_items": [
      {
        "rule_id": 300,
        "price": 400,
        "quantity": 1
      }
    ],
    "initial_items": [
      {
        "price": 500,
        "quantity": 1
      }
    ]
  }'

Stytt svar gæti litið svona út:

{
  "input_mode": "bundle",
  "bundle_template_id": 42,
  "bundle_quantity": 2,
  "currency": "ISK",
  "period_start_at": "2026-05-20T00:00:00Z",
  "period_end_at": "2026-06-20T00:00:00Z",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "first_period_recurring_subtotal_amount": "4000.0000",
  "first_period_recurring_tax_amount": "0.0000",
  "first_period_recurring_total_amount": "4000.0000",
  "recurring_subtotal_amount": "4000.0000",
  "recurring_tax_amount": "0.0000",
  "recurring_total_amount": "4000.0000",
  "billing_schedule_preview": {
    "kind": "interval"
  },
  "recurring_items": [
    {
      "key": "bundle-item-100",
      "source": "bundle",
      "creates_contract_item": true,
      "price_id": 200,
      "product_id": 10,
      "product_name": "Vefáskrift",
      "billing_type": "recurring",
      "quantity": 2,
      "unit_amount": "2000.0000",
      "service_period_start_at": "2026-05-20T00:00:00Z",
      "service_period_end_at": "2026-06-20T00:00:00Z",
      "proration_factor": "1.000000",
      "line_total_amount": "4000.0000",
      "renewal_line_total_amount": "4000.0000"
    }
  ],
  "initial_lines": [
    {
      "key": "initial-item-500",
      "source": "initial_items",
      "creates_contract_item": false,
      "price_id": 500,
      "product_id": 11,
      "product_name": "Áskrifendagjöf",
      "billing_type": "one_time",
      "quantity": 1,
      "unit_amount": "500.0000",
      "line_total_amount": "500.0000"
    }
  ]
}

Dæmi um verðútreikning fyrir beinar vörur án pakka:

curl https://askell.is/api/v2/subscription-offer-quotes/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "ISK",
    "items": [
      {
        "price": 200,
        "quantity": 1
      }
    ],
    "initial_items": [
      {
        "price": 500,
        "quantity": 1
      }
    ]
  }'

Bein stofnun samnings

POST /api/v2/subscription-contracts/ stofnar V2 samning beint. Þetta flæði hentar þegar samþættingin hefur þegar staðfest pöntunina og þarf ekki að keyra greiðsluforvinnu í sama kalli.

Þú getur meðal annars sent inn:

• customer_reference

• currency

• bundle_template eða items

• bundle_item_selections

• additional_items

• additional_bundles

• initial_items

• initial_billing_mode

• metadata

• payment_processor_override ef samningurinn á að vera bundinn ákveðnum færsluhirði

initial_items verða ekki varanlegir SubscriptionContractItem liðir. Þeir fara eingöngu á fyrstu innheimtulotulínurnar ef fyrsta innheimta er byggð á þeim.

initial_billing_mode gerir upphafsinnheimtu skýra:

none

Sjálfgefið gildi. Samningur og endurteknir samningsliðir eru stofnaðir og next_billing_at er sett út frá næstu innheimtu samningsliðanna. Engin innheimtulota eða upphafshlutfallslína er stofnuð fyrir tímabilið frá stofnun samnings fram að fyrstu skipulögðu innheimtu. Þetta hentar þegar upphafstímabilið á að vera án endurgjalds eða er innheimt utan Áskels.

create_initial_run

Stofnar áætlaða upphaflega BillingRun með endurteknum línum fyrir fyrsta tímabilið og mögulegum einskiptis initial_items. Fyrsta innheimtan fylgir sömu reglum um upphafshlutfallsgreiðslu og POST /api/v2/subscription-offer-quotes/ og getur því verið lægri en recurring_* upphæðirnar ef samningur byrjar inni í styttri upphafslotu.

next_invoice

Stofnar ekki upphaflega BillingRun. Í staðinn eru upphafshlutfallslínur fyrir endurteknu vörurnar geymdar sem biðlínur og merktar á fyrstu skipulögðu innheimtuna. Þegar fyrsta reglulega innheimtulotan er stofnuð fær hún bæði upphafstímabilið og næsta reglulega tímabil. Þetta hentar þegar þjónusta á að hefjast strax en innheimta á hlutfallslega fyrir upphafstímabilið á fyrsta gjalddaga.

initial_items eru aðeins leyfð með initial_billing_mode=create_initial_run. Þau eru ekki leyfð með none eða next_invoice þar sem þau verða ekki varanlegir samningsliðir og geta því ekki verið færð sjálfkrafa á næstu reglulegu innheimtu.

Dæmi: þjónusta byrjar strax en upphafstímabil er innheimt á fyrsta gjalddaga:

curl https://askell.is/api/v2/subscription-contracts/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_reference": "customer-123",
    "currency": "ISK",
    "items": [
      {
        "price": 200,
        "quantity": 1
      }
    ],
    "initial_billing_mode": "next_invoice"
  }'

Ef samningur er stofnaður 21. maí og fyrsta skipulagða innheimta er 1. júní, þá verður hlutfallslega tímabilið 21. maí til 1. júní sett á innheimtuna 1. júní ásamt reglulegu tímabilinu 1. júní til 1. júlí.

Sækja og uppfæra samning

Samningur er sóttur á:

GET /api/v2/subscription-contracts/{id}/

Listar og síur styðja meðal annars:

• state

• customer_reference

• reference

• legacy_subscription_id

Blaðskipting á listum

V2 listar nota blaðskiptingu aðeins ef page_size er sent inn.

• page_size virkjar blaðskiptingu

• sjálfgefið page_size er 10 þegar blaðskipting er virk

• hámarks page_size er 1000

• page velur síðu

Dæmi:

GET /api/v2/subscription-contracts/?page_size=25&page=2

Þegar blaðskipting er virk er svarið á hefðbundnu formi með count, next, previous og results. Ef page_size er ekki sent inn fæst óblaðskiptur listi.

V2 smáatriðaslóðin leyfir aðeins takmarkaðar uppfærslur. Samningurinn er ekki hugsaður sem frjálslega breytanlegur pöntunardráttur, heldur sem viðskiptalega mikilvæg staða sem á að lifa í gegnum skilgreind lífsferilsköll.

Lífsferilsaðgerðir

V2 styður eftirfarandi lífsferilsköll á samninga:

Slóð	Lýsing
POST /cancel/	Hættir við samningi, annaðhvort strax eða við lok tímabils.
POST /restart/	Endurræsir samning sem hefur verið stöðvaður.
POST /pause/	Setur tímabundið hlé á samning.
POST /resume/	Tekur samning úr hléi.
DELETE /pause/{pause_id}/	Eyðir fyrirfram skráðu hléi.
POST /activate/	Virkjar óvirkan samning ef hann má færast í virka stöðu.

Helstu beiðnireitir:

Aðgerð	Reitir	Skylda
POST /cancel/	cancel_at_period_end, cancel_at, effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir
POST /restart/	effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir
POST /pause/	start_date, end_date, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	start_date og end_date skyldar; aðrir valkvæðir
POST /resume/	effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir

Lífsferilsaðgerðir sem geta haft áhrif á verð innan virks þjónustutímabils styðja sama hlutfallsreikningsmynstur og vörubreytingar:

1. Kalla POST /api/v2/subscription-contracts/{id}/proration-preview/ með operation sem er cancel, pause, resume eða restart.

2. Vista preview_token úr svarinu ef framkvæma á sömu aðgerð strax á eftir.

3. Senda sama preview_token aftur í framkvæmdarkallið ásamt sömu stillingum fyrir proration_behavior og settlement_behavior.

include_pending_adjustments=true er aðeins gilt þegar settlement_behavior=invoice_now og þarf þá að vera sent bæði í forskoðun og framkvæmd.

proration_behavior getur verið none, create_prorations eða always_invoice. settlement_behavior getur verið next_invoice, invoice_now eða credit_balance. refund_manual og aðgerðir fyrir stakar endurgreiðslur eða handvirkar leiðréttingar eru ekki hluti af ytra V2 API flæðinu eins og er.

Inneign á samningi

Hlutfallsreiknaður kredit, til dæmis vegna lokunar, hlés eða breytinga á liðum, getur stofnað inneignarfærslu á samningi. Slík inneign er skráð sem óbreytanleg færslusaga á samningnum.

Núverandi regla fyrir framtíðarinnleiðingu er að inneign dragist frá eftir að skattar og línusamtölur hafa verið reiknaðar, en áður en reynt er að skuldfæra færsluhirði. Inneign má nota að hluta eða að fullu, og ef inneign nær yfir alla innheimtulotuna er ekki reynt að skuldfæra færsluhirði. Inneign sem verður til í sömu innheimtulotu má ekki nýtast þeirri sömu lotu.

Sjálfvirk nýting inneignar í næstu innheimtulotu er ekki komin inn í ytra API flæðið enn. Þangað til er inneign skráð og sýnileg í stjórnborði/sögu, en hún lækkar ekki sjálfkrafa næstu skuldfærslu.

Dæmi um að hætta við samning við lok tímabils:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/cancel/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true,
    "reason": "Viðskiptavinur óskaði eftir lokun"
  }'

Dæmi um forskoðun á hlutfallsreiknaðri endurræsingu:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/proration-preview/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "restart",
    "proration_behavior": "create_prorations",
    "settlement_behavior": "invoice_now"
  }'

Greiðslugangur

Þegar óskað er eftir greiðsluforvinnu áður en samningur verður virkur er mælt með checkout ferlinu:

1. Reikna eða staðfesta verðútreikning.

2. Sækja mögulega færsluhirða með POST /api/v2/payment-processor-options/.

3. Stofna checkout með POST /api/v2/checkouts/.

4. Ganga frá checkout með POST /api/v2/checkouts/{token}/finalize/.

POST /api/v2/payment-processor-options/ skilar þeim færsluhirðum sem eru löglegir fyrir viðkomandi verðútreikning, gjaldmiðil og innheimtuaðferð. Ef aðeins einn færsluhirðir er í boði má nota hann sjálfgefinn. Ef fleiri en einn kemur til greina ætti samþættingin að leyfa val.

Stytt svar gæti litið svona út:

{
  "currency": "ISK",
  "collection_method": "card",
  "selected_account_payment_processor_id": 7,
  "selection_reason": "single_eligible",
  "requires_selection": false,
  "results": [
    {
      "account_payment_processor_id": 7,
      "display_name": "Straumur / Adyen",
      "payment_processor": "adyen",
      "collection_method": "card",
      "resolution_source": "eligible",
      "supports_initial_charge": true,
      "supports_recurring_charge": true,
      "render_mode": "adyen_checkout",
      "payment_processor_type": "adyen",
      "is_3d_secure": true,
      "card_collection_in_frontend": true,
      "supports_checkout": true,
      "address_required": false,
      "registration_mode": "delayed_tokenization",
      "public_registration_config": {}
    }
  ]
}

POST /api/v2/checkouts/ býr til checkout hlut sem geymir verðútreikningsmynd, viðskiptavin, valinn færsluhirði og önnur forsendar-gögn.

GET /api/v2/checkouts/{token}/ sækir stöðu checkout hlutarins. checkout_url vísar á þessa slóð.

POST /api/v2/checkouts/{token}/finalize/ reynir að ljúka stofnun samnings og fyrstu innheimtu.

Forsendur áður en finalize er kallað

finalize kallar nú á forskoðun áður en samningur er stofnaður. Eftirfarandi þarf því að vera í lagi áður en finalize er reynt:

1. Viðskiptavinur þarf að vera til.

2. Valinn færsluhirðir þarf að vera löglegur fyrir verðútreikninginn.

3. Viðskiptavinur þarf að vera með staðfestan greiðslumáta sem passar við valinn færsluhirði, nema fyrsta innheimta sé 0 kr.

Ef þessar forsendur standast ekki fæst villusvar og enginn samningur eða innheimtulota verður stofnuð.

Mikilvægt er að greina á milli tveggja tegunda af 400 svörum úr finalize:

1. Forsendubrestur: enginn samningur og engin innheimtulota verða stofnuð.

2. Misheppnuð greiðslutilraun: samningur og innheimtulota geta þegar verið orðin til, en checkout.status verður failed.

Stytt svar úr finalize gæti litið svona út:

{
  "id": 15,
  "token": "f2dd7db2-4ae1-45c0-b8f6-2f98d1b70a9a",
  "checkout_url": "https://askell.is/api/v2/checkouts/f2dd7db2-4ae1-45c0-b8f6-2f98d1b70a9a/",
  "status": "succeeded",
  "customer_id": 1008,
  "customer_reference": "customer-123",
  "currency": "ISK",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "contract_id": 33,
  "initial_billing_run_id": 32,
  "account_payment_processor_id": 7,
  "quote_snapshot": {
    "input_mode": "bundle",
    "total_amount": "4500.0000"
  }
}

Niðurstöður úr finalize

Staða	HTTP	Lýsing	Næsta skref
succeeded	200	Samningur hefur verið stofnaður og fyrstu innheimtu lokið.	Vista contract_id og hefja reglulega stöðuvöktun eftir þörfum.
pending_external	200	Ytri færsluhirðir þarf að ljúka ferli áður en innheimta telst kláruð.	Fylgjast með checkout og tengdri innheimtulotu þar til staða breytist.
failed	400	Greiðslutilraun mistókst eftir að samningur og innheimtulota voru stofnuð.	Athuga contract_id og initial_billing_run_id í svari, lesa villusvar og meta hvort reyna eigi aftur eða bíða eftir annarri aðgerð.
Forsendubrestur	400	Beiðnigögn eða greiðsluforsendur stóðust ekki; enginn samningur stofnaður.	Leiðrétta beiðnigögn eða greiðslumáta áður en reynt er aftur.

Innheimtulotur og endurtekning

V2 innheimtulotur eru lesnar á:

GET /api/v2/billing-runs/
GET /api/v2/billing-runs/{id}/

Innheimtulotu sem hefur mistekist má reyna aftur með eftirfarandi slóð:

POST /api/v2/billing-runs/{id}/retry/

Svar frá smáatriðaslóð innheimtulotu sýnir meðal annars línur, tilraunir, tengdar færslur og stöðu.

Stytt svar gæti litið svona út:

{
  "id": 32,
  "contract_id": 33,
  "customer_id": 1008,
  "customer_reference": "customer-123",
  "period_start_at": "2026-05-20T00:00:00Z",
  "period_end_at": "2026-06-20T00:00:00Z",
  "state": "succeeded",
  "currency": "ISK",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "attempt_count": 1,
  "lines": [
    {
      "id": 71,
      "price_id": 200,
      "price_version_id": 15,
      "product_name": "Vefáskrift",
      "quantity": 2,
      "line_total_amount": "4000.0000",
      "service_period_start_at": "2026-05-20T00:00:00Z",
      "service_period_end_at": "2026-06-20T00:00:00Z"
    }
  ],
  "attempts": [
    {
      "id": 44,
      "attempt_no": 1,
      "state": "succeeded",
      "transaction_id": 19,
      "fail_code": null,
      "fail_message": null
    }
  ]
}

Útgáfustefna og hraðatakmarkanir

V2 er útgáfustýrt með slóð, þ.e. undir /api/v2/. Ný samhæfisbrot ættu því að birtast undir nýrri aðalútgáfuslóð fremur en að breyta merkingu núverandi slóða í kyrrþey.

Engar skjalaðar hraðatakmarkanir eru skilgreindar á þessari síðu. Samþættingar ættu samt að gera ráð fyrir tímabundnum mistökum, nota endurtekningu með biðtíma og skrá svör með stöðukóðum á borð við 400, 404 og 5xx.

Dæmi um heildarflæði í Python

• python

import requests

API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json",
}

quote_payload = {
    "customer_reference": "customer-123",
    "currency": "ISK",
    "bundle_template": 42,
    "bundle_item_selections": [
        {
            "bundle_item": 100,
            "selected_price": 200,
        }
    ],
    "initial_items": [
        {
            "price": 500,
            "quantity": 1,
        }
    ],
}

try:
    quote_response = requests.post(
        "https://askell.is/api/v2/subscription-offer-quotes/",
        json=quote_payload,
        headers=headers,
    )
    quote_response.raise_for_status()

    processor_response = requests.post(
        "https://askell.is/api/v2/payment-processor-options/",
        json=quote_payload,
        headers=headers,
    )
    processor_response.raise_for_status()
    processor_options = processor_response.json()["results"]

    # Hér er gert ráð fyrir að aðeins einn færsluhirðir komi til greina.
    # Ef fleiri en einn er í boði þarf samþættingin að leyfa val.
    checkout_payload = {
        **quote_payload,
        "collection_method": "card",
        "account_payment_processor": processor_options[0]["account_payment_processor_id"],
    }

    checkout_response = requests.post(
        "https://askell.is/api/v2/checkouts/",
        json=checkout_payload,
        headers=headers,
    )
    checkout_response.raise_for_status()
    checkout = checkout_response.json()

    finalize_response = requests.post(
        f"https://askell.is/api/v2/checkouts/{checkout['token']}/finalize/",
        json={},
        headers=headers,
    )
    finalized_checkout = finalize_response.json()

    if finalize_response.status_code == 400:
        contract_id = finalized_checkout.get("contract_id")
        initial_billing_run_id = finalized_checkout.get("initial_billing_run_id")

        if contract_id:
            # Greiðslutilraun mistókst, en samningur og innheimtulota gætu þegar verið til.
            # Hér ætti raunveruleg samþætting að skrá þetta og meta hvort reyna eigi aftur.
            print(
                "Checkout failed after contract creation",
                contract_id,
                initial_billing_run_id,
            )
        else:
            # Forsendubrestur: enginn samningur var stofnaður.
            finalize_response.raise_for_status()
    else:
        finalize_response.raise_for_status()
except requests.HTTPError as exc:
    response = exc.response
    try:
        error_body = response.json()
    except ValueError:
        error_body = {"raw": response.text}
    print(response.status_code, error_body)
    raise

Algengar villur

Villa	HTTP	Lýsing
customer_reference	400	Viðskiptavinur fannst ekki eða vantar í beiðnigögn.
account_payment_processor	400	Valinn færsluhirðir er ekki löglegur fyrir verðútreikninginn.
payment_method	400	Enginn staðfestur greiðslumáti fannst fyrir viðskiptavin.
bundle_item_selections	400	Verðval vantar eða passar ekki við pakkann.
additional_items	400	Val á viðbótarvöru passar ekki við virka reglu fyrir viðbótarvöru.
items	400	Beint verðval er ógilt eða passar ekki við gjaldmiðil.
Ekki fundið	404	Samningur, checkout eða innheimtulota fannst ekki fyrir aðganginn.