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

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.

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",
  "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",
      "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

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

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, reason	Báðir valkvæðir
POST /restart/	reason	Valkvæður
POST /pause/	start_date, end_date, reason	start_date og end_date skyldar
POST /resume/	reason	Valkvæður

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"
  }'

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.