Vefkrókar
Vefkrókar (e. webhooks) kalla í vefslóð sem þú skráir inn í Áskel þegar ákveðnir atburðir gerast. Atburðir sem er hægt að skrá sig fyrir:
Auðkenni atburðar |
Lýsing |
|---|---|
|
Allir atburðir sem tengjast áskriftum |
|
Áskrift stofnuð |
|
Áskrift breytt |
|
Áskrift endurnýjuð |
|
Allir atburðir sem tengjast samningsáskriftum |
|
Samningsáskrift stofnuð |
|
Samningsáskrift breytt |
|
Samningsáskrift endurnýjuð |
|
Eldri áskrift færð yfir í samningsáskrift |
|
Samningsáskrift virkjuð |
|
Hlé gert á samningsáskrift |
|
Samningsáskrift hafin á ný eftir hlé |
|
Samningsáskrift sagt upp án tafar |
|
Samningsáskrift lokið |
|
Allir atburðir sem tengjast samningsliðum |
|
Þjónusturéttindi samningsliðar breyttust (fellur ekki undir |
|
Allir atburðir sem tengjast skipulögðum breytingum á samningsliðum (falla ekki undir |
|
Breyting á lið skipulögð við næstu endurnýjun |
|
Skipulögð breyting á lið tók gildi við endurnýjun |
|
Skipulögð breyting á lið afturkölluð |
|
Allir atburðir sem tengjast keyrslum reikningagerðar |
|
Keyrsla reikningagerðar stofnuð |
|
Keyrsla reikningagerðar breytt |
|
Keyrsla reikningagerðar tókst |
|
Keyrsla reikningagerðar mistókst endanlega |
|
Fyrirhugað að reyna aftur keyrslu reikningagerðar |
|
Allir atburðir sem tengjast afgreiðslupöntunum |
|
Afgreiðslupöntun stofnuð |
|
Afgreiðslupöntun afgreidd |
|
Afgreiðslupöntun afturkölluð |
|
Sending bókuð hjá flutningsaðila (rekjanúmer fylgir) |
|
Allir atburðir sem tengjast viðskiptavinum |
|
Viðskiptavinur stofnaður |
|
Viðskiptavini breytt |
|
Allir atburðir sem tengjast greiðslum (stökum greiðslum og skuldfærslum samningsáskrifta) |
|
Greiðsla stofnuð |
|
Greiðslu breytt (t.d. tekst eða tekst ekki að skuldfæra) |
|
Fyrirhugað að reyna aftur að skuldfæra greiðslu |
|
Allir atburðir sem tengjast kaupferlum |
|
Kaupferli stofnað |
|
Kaupferli breytt |
Auðkenning
Við mælum með því að allir vefkrókar séu auðkenndir. Við undirritum hvert kall með haus (e. header) sem heitir Hook-HMAC. Gildið er HMAC hakkaður strengur byggður á innihaldi vefkallsins og svo leynilegu gildi sem er aðeins þekkt af okkur og þér. Þú færð þetta leynilega gildi í hendurnar þegar þú stofnar nýjan vefkrók. Tegund atburðar kemur einnig fram í hausnum Hook-Event. Útgáfa API gagna kemur fram í hausnum Hook-API-Version. Eldri plan/áskriftar vefkrókar senda v1, en nýja samningsáskriftarkerfið sendir v2.
Hér er sýnidæmi í Python. Ferlið er mjög líkt því sem Shopify notar og má finna fleiri kóðadæmi í skjölun þeirra.
import base64
import hmac
import hashlib
WEBHOOK_SECRET = "Your webhook secret".encode()
WEBHOOK_DIGEST_TYPE = 'sha512'
def verify(hmac_header, digest_method, secret, message):
digestmod = getattr(hashlib, digest_method)
signed = base64.b64encode(
hmac.new(secret, message, digestmod).digest(),
).strip()
return hmac.compare_digest(signed, hmac_header)
# your view function
def handle_webhook(request):
# The signature
digest = request.META.get('HTTP_HOOK_HMAC').encode()
# The name of the webhook event
event = request.META.get('HTTP_HOOK_EVENT').encode()
body = request.body
if verify(digest, WEBHOOK_DIGEST_TYPE, WEBHOOK_SECRET, body):
payload = json.loads(body)
# ... the rest of your code here```
require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'
WEBHOOK_SECRET = 'Your webhook secret'
WEBHOOK_DIGEST_TYPE = 'sha512'
helpers do
def verify_webhook(secret, data, hmac_header)
digested = ::OpenSSL::HMAC.digest(WEBHOOK_DIGEST_TYPE, secret, data)
calculated_hmac = Base64.encode64(digested).strip
return calculated_hmac == hmac_header
end
end
post '/' do
request.body.rewind
data = request.body.read
if verify_webhook(WEBHOOK_SECRET, env["HTTP_HOOK_HMAC"])
# deserialize data' using json and process webhook
end
end
<?php
define('WEBHOOK_SECRET', 'Your webhook secret')
define('WEBHOOK_DIGEST_TYPE', 'sha512')
function verify_webhook($data, $hmac_header)
{
$calculated_hmac = base64_encode(hash_hmac(WEBHOOK_DIGEST_TYPE, $data,
WEBHOOK_SECRET, true));
return ($hmac_header == $calculated_hmac);
}
$hmac_header = $_SERVER['HTTP_HOOK_HMAC'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);
?>
Samningsáskriftir og flutningur úr eldra áskriftarkerfi
V2 samningsáskriftir nota subscription_contract.* atburði. Þegar eldri áskrift er flutt yfir
í V2 er sendur subscription_contract.migrated atburður. Hann táknar að V2 samningurinn sé
nýr innheimtu- og aðgangsheimildaraðili fyrir viðkomandi áskrift.
Við flutning eru ekki sendir eldri subscription.* samheiti fyrir V2 samninginn, því gögnin í
atburðinum eru byggð á SubscriptionContract en ekki eldri Subscription hlut. Af sömu
ástæðu er ekki sendur subscription.canceled atburður eingöngu vegna þess að innheimta færist
frá eldri áskrift yfir í V2 samning.
Gögn í vefkrókum
Meginmál hvers kalls er JSON hlutur með fjórum reitum:
{
"event": "subscription_contract.created",
"ref": null,
"sender": "notandanafn",
"data": {}
}
event er heiti atburðarins (sama gildi og í hausnum Hook-Event), sender er
notandanafn aðgangsins sem sendir atburðinn og ref er ekki notaður og alltaf null. Sjálf
gögnin eru í data. Dæmin hér að neðan sýna innihald data fyrir hvern flokk atburða.
Áskriftir (subscription.*)
Þegar áskrift er búin til, uppfærist eða endurnýjast eru sendir viðeigandi atburðir. Hér er dæmi um gögn sem koma með atburði um áskrift:
{
"id": 12345,
"plan": {
"id": 12345,
"name": "Titill",
"alternative_name": "Annar titill",
"reference": "",
"interval": "month",
"interval_count": 1,
"amount": "1.0000",
"currency": "ISK",
"trial_period_days": 5,
"enabled": true,
"private": false,
"electronic_only": true,
"description": "Some description"
},
"customer": 12345,
"customer_reference": "customer-12345",
"trial_end": "2024-01-01T00:00:00Z",
"start_date": "2024-01-01T00:00:00Z",
"ended_at": null,
"reference": "reference-12345",
"active": true,
"meta": "{}",
"description": "Some subscription description",
"active_until": "2024-02-01T00:00:00Z",
"is_on_trial": false,
"token": "md5sumtokenwith32chars",
"is_failing": false,
"last_billing_log": {
"id": 12345,
"billing_log_type": "renewal",
"billing_date": "2024-01-01T00:00:00Z",
"plan_billed_up_to": "2024-02-01T00:00:00Z",
"total": null,
"transaction": {
"external_reference": null,
"data": {},
"state": "settled",
"uuid": "some-guid-with-numbers-and-letters",
"fail_code": null,
"refund_code": null,
"cancel_code": null,
"amount": "1.00",
"currency": "ISK",
"payment_method": null,
"created_at": "2024-01-01T00:00:00Z"
}
},
"delivery_address": null,
"amount": "1.0000"
}
Samningsáskriftir (subscription_contract.*)
Atburðirnir eru sendir við eftirfarandi aðstæður:
Atburður |
Hvenær |
|---|---|
|
Samningsáskrift er stofnuð. |
|
Samningsáskrift er vistuð með breytingum, t.d. þegar uppsögn er skipulögð við lok tímabils. |
|
Innheimta fyrir nýtt tímabil hefur tekist og samningsáskriftin færist yfir á það. |
|
Eldri áskrift hefur verið flutt yfir í samningsáskrift. Sjá gögnin hér að neðan. |
|
Samningsáskrift verður virk, t.d. þegar fyrsta greiðsla tekst eða þegar uppsögð samningsáskrift er endurræst. |
|
Hlé tekur gildi. |
|
Hléi lýkur og samningsáskriftin er virk á ný. |
|
Samningsáskrift er sagt upp án tafar. |
|
Samningsáskrift lýkur, annaðhvort vegna þess að skipulögð uppsögn tekur gildi eða vegna þess að samningi um stök kaup lýkur. |
subscription_contract.changed er sendur í hvert sinn sem samningsáskrift er vistuð og berst því
oft samhliða öðrum atburðum í töflunni. Athugið að þegar skipulögð uppsögn tekur gildi er sendur
subscription_contract.ended en ekki subscription_contract.canceled, þótt state
samningsáskriftarinnar verði canceled. subscription_contract.canceled er aðeins sendur þegar
samningsáskrift er sagt upp án tafar.
Atburðir um þjónusturéttindi samningsliða (subscription_contract_item.*) og skipulagðar
breytingar á liðum (subscription_contract_scheduled_change.*) senda ekki samningsáskriftina og
falla því ekki undir subscription_contract.*. Skrá þarf vefkrók sérstaklega fyrir þá, sjá
Þjónusturéttindi samningsliða (subscription_contract_item.*) og Skipulagðar breytingar á liðum (subscription_contract_scheduled_change.*).
Allir subscription_contract.* atburðir nema subscription_contract.migrated senda
samningsáskriftina á sama formi og V2 vefþjónustan skilar henni, sjá
Reitir í svari samnings. Hér er dæmi um gögn sem koma með atburði um samningsáskrift:
{
"id": 12345,
"customer_id": 33482,
"customer": {
"id": 33482,
"customer_reference": "customer-12345",
"email": "jon@example.com",
"customer_username": "jon"
},
"customer_reference": "customer-12345",
"reference": null,
"delivery_address": null,
"shipping_selection": null,
"state": "active",
"billing_anchor_at": "2024-01-01T00:00:00Z",
"billing_timezone": "Atlantic/Reykjavik",
"billing_time": "00:00:00",
"billing_advance_policy": "on_run_succeeded",
"service_entitlement_policy": "on_run_succeeded",
"service_active": true,
"service_state": "active",
"active_service_item_count": 1,
"inactive_service_item_count": 0,
"total_active_quantity": 1,
"entitlement_summary": {
"service_active": true,
"service_state": "active",
"active_service_item_count": 1,
"inactive_service_item_count": 0,
"past_due_service_item_count": 0,
"total_active_quantity": 1,
"active_product_ids": [
222
],
"evaluated_at": "2024-01-01T00:00:00Z"
},
"billing_attention_required": false,
"trial_start_at": null,
"trial_end_at": null,
"next_billing_at": "2024-02-01T00:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"ended_at": null,
"currency": "ISK",
"recurring": true,
"contract_version": 1,
"default_proration_behavior": "create_prorations",
"electronic_only": true,
"has_future_pause": false,
"paused_until": null,
"payment_processor_override_id": null,
"accounting_department": null,
"accounting_cost_center": null,
"legacy_subscription_ids": [
9876
],
"legacy_source_mappings": [
{
"legacy_subscription_id": 9876,
"subscription_contract_item_id": 23456,
"role": "item_source",
"migration_effective_at": "2024-01-01T00:00:00Z"
}
],
"metadata": {},
"subscriber_page": "https://askell.is/change_contract/<token>/",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"items": [
{
"id": 23456,
"price_id": 333,
"product": {
"id": 222,
"name": "Mánaðaráskrift",
"reference": "manadaraskrift",
"image_url": null
},
"price": {
"id": 333,
"product_id": 222,
"product_name": "Mánaðaráskrift",
"product_reference": "manadaraskrift",
"currency": "ISK",
"currency_format": "{amount} kr",
"unit_amount": "2990.0000",
"description": "",
"billing_type": "recurring",
"recurrence_type": "interval",
"interval": "month",
"interval_count": 1,
"billing_day_of_month": null,
"billing_schedule_id": null,
"billing_schedule_name": null,
"billing_schedule_timezone": null,
"billing_schedule_rules": [],
"proration_policy": "prorate_by_time",
"initial_billing_policy": "next_scheduled_period",
"next_occurrences": [],
"active": true,
"current_version_id": 444,
"versions": [
{
"id": 444,
"unit_amount": "2990.0000",
"valid_from": null,
"valid_to": null,
"active": true,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"currently_effective": true,
"effective_from": null,
"effective_to": null,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
"quantity": 1,
"unit_amount_override": null,
"discount_percent": null,
"active": true,
"start_at": "2024-01-01T00:00:00Z",
"end_at": null,
"billing_anchor_at": "2024-01-01T00:00:00Z",
"next_billing_date": null,
"next_billing_at": "2024-02-01T00:00:00Z",
"last_billed_at": "2024-01-01T00:00:00Z",
"service_active": true,
"service_state": "active",
"entitled_from": "2024-01-01T00:00:00Z",
"entitled_until": "2024-02-01T00:00:00Z",
"current_service_period_start_at": "2024-01-01T00:00:00Z",
"current_service_period_end_at": "2024-02-01T00:00:00Z",
"entitlement_billing_run_id": 54321,
"metadata": {}
}
],
"pauses": [],
"current_pauses": [],
"future_pauses": [],
"past_pauses": [],
"billing_cadence": {
"recurrence_type": "interval",
"interval": "month",
"interval_count": 1,
"billing_day_of_month": null,
"billing_schedule_id": null,
"billing_schedule_name": null
},
"bundle_purchases": [],
"bundle_purchase_id": null,
"initial_billing_run": {
"id": 54321,
"state": "succeeded",
"run_type": "recurring",
"period_start_at": "2024-01-01T00:00:00Z",
"period_end_at": "2024-02-01T00:00:00Z",
"billing_date": "2024-01-01",
"due_at": "2024-01-01T00:00:00Z",
"currency": "ISK",
"subtotal_amount": "2990.0000",
"tax_amount": "0.0000",
"total_amount": "2990.0000",
"attempt_count": 1,
"max_attempts": 5,
"next_retry_at": null,
"last_attempt_at": "2024-01-01T00:00:00Z",
"transaction_id": 98765,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
"initial_billing_run_id": 54321,
"initial_billing_run_total_amount": "2990.0000",
"latest_billing_run": {
"id": 54321,
"state": "succeeded",
"run_type": "recurring",
"period_start_at": "2024-01-01T00:00:00Z",
"period_end_at": "2024-02-01T00:00:00Z",
"billing_date": "2024-01-01",
"due_at": "2024-01-01T00:00:00Z",
"currency": "ISK",
"subtotal_amount": "2990.0000",
"tax_amount": "0.0000",
"total_amount": "2990.0000",
"attempt_count": 1,
"max_attempts": 5,
"next_retry_at": null,
"last_attempt_at": "2024-01-01T00:00:00Z",
"transaction_id": 98765,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
"discount": null
}
customer er hlutur með upplýsingum um viðskiptavininn en auðkenni hans er í customer_id.
service_active og service_state segja til um hvort veita eigi þjónustu núna.
reference er tilvísun samningsáskriftarinnar í ytra kerfi og metadata lýsigögn
samþættingarinnar, þar á meðal lýsigögn úr checkout og uppruni samningsáskriftarinnar í
askell_source. Bæði eru sett um leið og samningsáskriftin er stofnuð og fylgja því
þegar með subscription_contract.created. Sjá Tilvísun og lýsigögn samnings.
legacy_subscription_ids og legacy_source_mappings tengja samningsáskriftina við eldri
áskriftir sem voru fluttar yfir í hana. Listarnir eru tómir ef engin eldri áskrift var flutt. Hver
færsla í legacy_source_mappings segir hvaða eldri áskrift (legacy_subscription_id) varð að
hvaða samningslið (subscription_contract_item_id), hlutverk hennar í flutningnum (role:
primary, item_source eða history_only) og hvenær flutningurinn tók gildi
(migration_effective_at).
Flutningur úr eldra áskriftarkerfi (subscription_contract.migrated)
subscription_contract.migrated sendir ekki alla samningsáskriftina heldur styttri gögn um
flutninginn:
{
"id": 12345,
"subscription_contract_id": 12345,
"migration_batch_id": 77,
"customer": 33482,
"customer_reference": "customer-12345",
"billing_managed_by": "subscription_contract",
"migration_effective_at": "2024-01-01T00:00:00+00:00",
"legacy_subscription_ids": [
9876
],
"legacy_source_mappings": [
{
"legacy_subscription_id": 9876,
"subscription_contract_item_id": 23456,
"role": "item_source",
"migration_effective_at": "2024-01-01T00:00:00+00:00"
}
]
}
Reitur |
Lýsing |
|---|---|
|
Auðkenni samningsáskriftarinnar. Báðir reitir hafa sama gildi. |
|
Auðkenni flutningslotunnar sem flutti áskriftina. |
|
Auðkenni viðskiptavinar sem tala. Ólíkt öðrum |
|
Tilvísun viðskiptavinar. |
|
Alltaf |
|
Elsti gildistökutíminn í |
|
Auðkenni eldri áskrifta sem voru fluttar yfir í samningsáskriftina. |
|
Sama form og í öðrum |
Keyrslur reikningagerðar (billing_run.*)
Þegar keyrsla reikningagerðar er stofnuð, breytist, tekst, mistekst eða er sett í endurtekningu eru sendir viðeigandi atburðir. Hér er dæmi um gögn sem koma með atburði um keyrslu reikningagerðar:
{
"id": 54321,
"contract_id": 12345,
"source_contract_change_id": null,
"run_type": "recurring",
"customer_id": 33482,
"customer_reference": "customer-12345",
"period_start_at": "2024-01-01T00:00:00Z",
"period_end_at": "2024-02-01T00:00:00Z",
"billing_date": "2024-01-01",
"due_at": "2024-01-01T00:00:00Z",
"state": "succeeded",
"currency": "ISK",
"subtotal_amount": "2990.0000",
"tax_amount": "0.0000",
"total_amount": "2990.0000",
"attempt_count": 1,
"max_attempts": 5,
"next_retry_at": null,
"last_attempt_at": "2024-01-01T00:00:00Z",
"transaction_id": 98765,
"transaction_uuid": "3f1c2a9e-5b7d-4c8e-9a6f-2d4b8e1c7a90",
"transaction_external_reference": "410009982476",
"lines": [
{
"id": 76543,
"contract_id": 12345,
"line_type": "recurring",
"contract_item_id": 23456,
"price_id": 333,
"price_version_id": null,
"product_name": "Mánaðaráskrift",
"product_reference": "manadaraskrift",
"quantity": 1,
"unit_amount": "2990.0000",
"discount_percent": null,
"currency": "ISK",
"line_subtotal_amount": "2990.0000",
"line_tax_amount": "0.0000",
"line_total_amount": "2990.0000",
"service_period_start_at": "2024-01-01T00:00:00Z",
"service_period_end_at": "2024-02-01T00:00:00Z",
"proration_factor": "1.000000",
"proration_reason": null,
"proration_behavior": null,
"settlement_behavior": null,
"change_effective_at": null,
"adjustment_service_start_at": null,
"adjustment_service_end_at": null,
"source_billing_run_line_id": null,
"source_contract_change_id": null,
"imported_billing_run_id": null,
"target_contract_item_id": null,
"target_billing_date": null,
"target_due_at": null,
"tax_rate_id": null,
"tax_rate_version_id": null,
"tax_percent": null,
"tax_calculation_mode": null,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"attempts": [
{
"id": 65432,
"attempt_no": 1,
"state": "succeeded",
"idempotency_key": "v2-billing-run-54321-attempt-1",
"transaction_id": 98765,
"transaction_uuid": "3f1c2a9e-5b7d-4c8e-9a6f-2d4b8e1c7a90",
"transaction_external_reference": "410009982476",
"fail_code": null,
"fail_message": null,
"started_at": "2024-01-01T00:00:00Z",
"finished_at": "2024-01-01T00:00:00Z",
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
contract_id er auðkenni samningsáskriftarinnar. transaction_id, transaction_uuid og
transaction_external_reference vísa á færsluna sem skuldfærði keyrsluna og eru null ef engin
færsla hefur verið stofnuð. lines eru línur keyrslunnar og attempts tilraunir til
skuldfærslu. state er scheduled, processing, retry_scheduled, pending_external,
succeeded, failed_terminal, canceled, voided eða refunded.
Þjónusturéttindi samningsliða (subscription_contract_item.*)
subscription_contract_item.entitlement_changed er sendur þegar þjónusturéttindi samningsliðar
breytast: hvort veita eigi þjónustu (service_active / service_state), til hvenær
(entitled_until), magn eða vara liðarins. Þetta gerist t.d. þegar keyrsla reikningagerðar tekst
og veitir réttindi fyrir nýtt tímabil, þegar prufutímabil hefst, þegar samningsáskrift fer í hlé,
er hafin á ný, er sagt upp eða lýkur, og þegar samningslið er breytt.
Mikilvægt
Atburðurinn fellur ekki undir subscription_contract.*. Til að fá hann þarf að skrá vefkrók
sérstaklega fyrir subscription_contract_item.entitlement_changed eða
subscription_contract_item.*.
{
"id": 23456,
"subscription_contract_id": 12345,
"contract_item_id": 23456,
"customer": 33482,
"customer_reference": "customer-12345",
"product_id": 222,
"product_reference": "manadaraskrift",
"price_id": 333,
"quantity": 1,
"service_active": true,
"service_state": "active",
"entitled_from": "2024-01-01T00:00:00+00:00",
"entitled_until": "2024-02-01T00:00:00+00:00",
"current_service_period_start_at": "2024-01-01T00:00:00+00:00",
"current_service_period_end_at": "2024-02-01T00:00:00+00:00",
"entitlement_billing_run_id": 54321,
"changed_fields": [
"entitled_until",
"service_active",
"service_state"
],
"previous": {
"service_active": false,
"service_state": "inactive",
"entitled_until": null,
"quantity": 1,
"product_id": 222,
"product_reference": "manadaraskrift"
}
}
id og contract_item_id eru auðkenni samningsliðarins. changed_fields segir hvaða reitir
breyttust og previous geymir gildi réttindareitanna (service_active, service_state,
entitled_until, quantity, product_id og product_reference) eins og þau voru fyrir
breytinguna.
entitlement_billing_run_id er keyrsla reikningagerðar sem veitti réttindin, ef einhver.
Skipulagðar breytingar á liðum (subscription_contract_scheduled_change.*)
Atburðirnir fylgja breytingum á liðum sem eru skipulagðar við næstu endurnýjun
(apply_at=period_end), sjá Skipulagðar breytingar á liðum (apply_at=period_end). Þeir eru sendir við
eftirfarandi aðstæður:
Atburður |
Hvenær |
|---|---|
|
Breyting á lið er skipulögð við næstu endurnýjun. |
|
Keyrsla reikningagerðar fyrir endurnýjunina er stofnuð og breytingunni hefur verið beitt á liðinn. |
|
Skipulögð breyting er afturkölluð, eða henni er sjálfkrafa aflýst vegna þess að liðurinn er fjarlægður eða samningsáskriftinni sagt upp. |
Mikilvægt
Atburðirnir falla ekki undir subscription_contract.*. Til að fá þá þarf að skrá vefkrók
sérstaklega fyrir einstaka atburði eða fyrir subscription_contract_scheduled_change.*.
Gögnin eru skipulagða breytingin á sama formi og hún birtist í scheduled_changes í V2
vefþjónustunni, ásamt auðkennum samningsáskriftarinnar og viðskiptavinarins. Hér er dæmi um gögn sem
koma með subscription_contract_scheduled_change.created:
{
"id": 8765,
"contract_item": 23456,
"operation": "update_item",
"state": "scheduled",
"scheduled_for": "2024-02-01T00:00:00Z",
"price_id": 334,
"price": {
"id": 334,
"product_id": 223,
"product_name": "Mánaðaráskrift Plus",
"product_reference": "manadaraskrift-plus",
"currency": "ISK",
"currency_format": "{amount} kr",
"unit_amount": "1990.0000",
"description": "",
"billing_type": "recurring",
"recurrence_type": "interval",
"interval": "month",
"interval_count": 1,
"billing_day_of_month": null,
"billing_schedule_id": null,
"billing_schedule_name": null,
"billing_schedule_timezone": null,
"billing_schedule_rules": [],
"proration_policy": "prorate_by_time",
"initial_billing_policy": "next_scheduled_period",
"next_occurrences": [],
"active": true,
"current_version_id": 445,
"versions": [
{
"id": 445,
"unit_amount": "1990.0000",
"valid_from": null,
"valid_to": null,
"active": true,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"currently_effective": true,
"effective_from": null,
"effective_to": null,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
"product": {
"id": 223,
"name": "Mánaðaráskrift Plus",
"reference": "manadaraskrift-plus"
},
"quantity": 1,
"discount_percent": null,
"unit_amount_override": null,
"from_price_id": 333,
"from_quantity": 1,
"reason": null,
"applied_at": null,
"canceled_at": null,
"applied_change_id": null,
"billing_run_id": null,
"created_at": "2024-01-15T12:00:00Z",
"updated_at": "2024-01-15T12:00:00Z",
"subscription_contract_id": 12345,
"customer": 33482,
"customer_reference": "customer-12345"
}
Reitur |
Lýsing |
|---|---|
|
Auðkenni skipulögðu breytingarinnar, ekki samningsáskriftarinnar. |
|
Samningsáskriftin sem breytingin tilheyrir. |
|
Auðkenni samningsliðarins sem breytist. |
|
Alltaf |
|
|
|
Endurnýjunin sem breytingin tekur gildi við. |
|
Verðið sem liðurinn fær við endurnýjunina, á sama formi og |
|
Magn, afsláttur og sérverð sem liðurinn fær við endurnýjunina. |
|
Verð og magn liðarins þegar breytingin var skipulögð. |
|
Valkvæð ástæða sem var gefin þegar breytingin var skipulögð. |
|
Hvenær breytingunni var beitt, breytingin sem varð til í sögu samningsáskriftarinnar og
keyrsla reikningagerðar fyrir endurnýjunina. |
|
Hvenær breytingin var afturkölluð. |
|
Stofn- og breytingartími skipulögðu breytingarinnar. |
|
Auðkenni viðskiptavinar sem tala og tilvísun hans. |
Breytingar sem bíða fylgja einnig samningsáskriftinni sjálfri, í scheduled_changes og í
scheduled_change á viðkomandi lið, í þeim subscription_contract.* atburðum sem senda
samningsáskriftina.
Afgreiðslupantanir (fulfillment_order.*)
Þegar greitt er fyrir áþreifanlega vöru verður til afgreiðslupöntun sem seljandi þarf að tína til,
pakka og senda. Atburðirnir fylgja henni í gegnum ferlið: fulfillment_order.created þegar hún
verður til (eftir að greiðsla hefur tekist), fulfillment_order.shipment_booked þegar sending er
bókuð hjá flutningsaðila og rekjanúmer liggur fyrir, fulfillment_order.fulfilled þegar pöntunin
telst afgreidd og fulfillment_order.cancelled ef hún er afturkölluð.
Öll fjögur bera sömu gögn, þ.e. alla pöntunina eins og hún stendur þegar atburðurinn er sendur.
Í fulfillment_order.shipment_booked fylgir að auki shipment_id sem vísar á þá sendingu í
fulfillments sem var verið að bóka.
{
"id": 12345,
"number": 42,
"status": "open",
"contract_id": 12345,
"billing_run_id": 54321,
"customer_id": 33482,
"customer_reference": "customer-12345",
"customer_name": "Jón Jónsson",
"customer_email": "jon@example.com",
"delivery_address": {
"id": 9876,
"delivery_name": "Jón Jónsson",
"address_1": "Hringbraut 12",
"address_2": "",
"address_3": "",
"zip_code": "101",
"city": "Reykjavík",
"state": null,
"country": "IS"
},
"shipping_selection": {
"id": 555,
"option_id": 7,
"handler": "posturinn",
"delivery_mode": "pickup_point",
"option_name": "Póstbox",
"service_code": "DPO",
"price_amount": "940.0000",
"currency": "ISK",
"location_id": "9591",
"location_name": "Póstbox Hallveigarstíg",
"location_address": "Hallveigarstíg 1 101 Reykjavík",
"location": {
"id": "9591",
"name": "Póstbox Hallveigarstíg",
"address": "Hallveigarstíg 1 101 Reykjavík",
"street": "Hallveigarstíg 1",
"zip_code": "101",
"town": "Reykjavík",
"external_id": null,
"latitude": 64.1,
"longitude": -21.9
}
},
"lines": [
{
"id": 1111,
"product_id": 222,
"product_reference": "SKU-1",
"product_name": "Kaffipoki",
"quantity": 2,
"quantity_fulfilled": 0
}
],
"fulfillments": [
{
"id": 333,
"order_id": 12345,
"handler": "posturinn",
"status": "booked",
"provider_order_id": "PP123456789",
"tracking_number": "PP123456789",
"weight_grams": 1000,
"error": "",
"booked_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"estimated_weight_grams": 1000,
"metadata": {},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
Seljandi sem selur áþreifanlega vöru en hefur engan flutningsaðila uppsettan fær pantanir án
sendingarvals: shipping_selection er þá null og fulfillments tómur listi. Atburðirnir
fulfillment_order.created og fulfillment_order.fulfilled berast eftir sem áður — pöntunina
þarf að tína til og afgreiða hvort sem Áskell bókar sendinguna eða ekki.
Viðskiptavinir (customer.*)
Þegar viðskiptavinur er stofnaður eða uppfærist eru sendir viðeigandi atburðir. Hér er dæmi um gögn sem koma með atburði um viðskiptavin:
{
"id": 33482,
"first_name": "",
"last_name": "",
"delivery_name": "",
"address_1": "",
"address_2": "",
"address_3": "",
"zip_code": "",
"city": "",
"country": "",
"email": null,
"customer_reference": "0208912039",
"payment_method": [],
"address": null
}
Greiðslur (payment.*)
payment.* atburðir berast með tvenns konar gögnum eftir því hvaðan greiðslan kemur:
Stakar greiðslur sem eru stofnaðar í gegnum Stakar greiðslur (e. Payments) senda eldra formið, með lista af færslum í
transactions. HausinnHook-API-Versioner þáv1.Skuldfærslur samningsáskrifta, þ.e. greiðslur sem keyrsla reikningagerðar stofnar, senda flatt form þar sem ein færsla er lýst beint í gögnunum. Hausinn
Hook-API-Versioner þáv2.
Vefkrókur sem er skráður fyrir payment.*, eða einstökum payment atburði, fær hvort tveggja.
Til að greina á milli má lesa hausinn Hook-API-Version, eða athuga hvort reiturinn
subscription_contract_id er í gögnunum. Hann er aðeins í forminu fyrir skuldfærslur
samningsáskrifta.
Stakar greiðslur (Hook-API-Version: v1)
Þegar stök greiðsla er stofnuð, breytt eða látið er reyna á endurnýjun eru sendir viðeigandi atburðir. Hér er dæmi um gögn sem koma með atburði um staka greiðslu:
{
"uuid": "some-guid-with-numbers-and-letters",
"amount": "1.0000",
"currency": "ISK",
"description": "Description here",
"reference": "some-reference",
"state": "settled",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"transactions": [
{
"external_reference": "410009982476",
"data": {
"id": "4100000000",
"receipt": {}, // receipt contains vendor specific fields, not listed here
"status": "settled"
},
"state": "settled",
"uuid": "some-guid-with-numbers-and-letters",
"fail_code": null,
"refund_code": null,
"cancel_code": null,
"amount": "1.00",
"currency": "ISK",
"payment_method": {
"verified": true,
"canceled": false,
"valid_until": "2025-03-01T00:00:00Z",
"display_info": "XXXX-XXXX-XXXX-4324 (Visa)",
"credit_card": true
},
"created_at": "2024-01-01T00:00:00Z"
}
]
}
Skuldfærslur samningsáskrifta (Hook-API-Version: v2)
Keyrsla reikningagerðar sendir payment.created þegar færsla er stofnuð fyrir tilraun til
skuldfærslu, payment.changed þegar skuldfærslan tekst, mistekst endanlega eða bíður staðfestingar
hjá færsluhirði, og payment.retry þegar ný tilraun er fyrirhuguð. Hér er dæmi um gögn sem koma
með atburði um skuldfærslu samningsáskriftar:
{
"uuid": "3f1c2a9e-5b7d-4c8e-9a6f-2d4b8e1c7a90",
"amount": "2990.00",
"currency": "ISK",
"description": "Billing run 54321",
"reference": "410009982476",
"state": "settled",
"created_at": "2024-01-01T00:00:00+00:00",
"updated_at": "2024-01-01T00:00:00+00:00",
"fail_code": null,
"refund_code": null,
"cancel_code": null,
"payment_method": 1111,
"billing_run_id": 54321,
"billing_run_attempt_id": 65432,
"subscription_contract_id": 12345,
"customer": 33482,
"customer_reference": "customer-12345",
"legacy_subscription_ids": [
9876
]
}
Reitur |
Lýsing |
|---|---|
|
Auðkenni færslunnar. |
|
Upphæð og gjaldmiðill færslunnar. |
|
Alltaf |
|
Tilvísun færsluhirðis í færsluna. |
|
Staða færslunnar: |
|
Stofn- og breytingartími færslunnar. |
|
Kóðar færslunnar ef skuldfærsla mistókst, var endurgreidd eða felld niður. |
|
Auðkenni greiðslumáta sem tala, ekki hlutur eins og í eldra forminu. |
|
Keyrsla reikningagerðar sem stofnaði greiðsluna og tilraunin innan hennar. |
|
Samningsáskriftin sem verið er að innheimta. |
|
Auðkenni viðskiptavinar sem tala og tilvísun hans. |
|
Eldri áskriftir sem voru fluttar yfir í samningsáskriftina. |
Í payment.retry getur verið að engin færsla fylgi, t.d. ef tilraunin mistókst áður en færsla
var stofnuð. Þá eru reitir færslunnar (uuid, reference, created_at, updated_at,
payment_method og kóðarnir) null, amount og currency koma frá keyrslunni og state er staða keyrslunnar, t.d.
retry_scheduled, en ekki staða færslu.
Kaupferli (checkout.*)
Þegar kaupferli er stofnað eða þegar það breytist:
{
"token": "3a44383eb19dc9183be4df5ad655094c88159af4",
"checkout_url": "http://askell.is/checkout/3a44383eb19dc9183be4df5ad655094c88159af4/",
"status": "tokencreated"
}