> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/prekybininko-api/webhooks.md). # Webhooks Serverio į serverį pranešimai, kurie jūsų sistemoms nurodo, kai pasikeičia mokėjimo būsena arba vartų žetonas – patikima alternatyva laukti kliento naršyklės. Kai mokėjimo būsena pasikeičia – jis apmokamas, nepavyksta, atšaukiamas, baigiasi jo galiojimas arba yra grąžinamas – vartai siunčia pranešimą **Webhook'ą (dar vadinamą atgalinio iškvietimo pranešimais)** į sukonfigūruotą Callback URL. Jūsų sistemos tuomet gali automatiškai atnaujinti užsakymą, niekam nestebint Prekybininko portalo ir nepriklausant nuo to, ar kliento naršyklė grįš į jūsų svetainę. Webhooks pristatomi iš serverio į serverį, nepriklausomai nuo to, ką daro klientas. Jie gaunami net jei klientas po apmokėjimo uždaro naršyklę, praranda ryšį arba niekada negrįžta į jūsų parduotuvę. Užsakymus vykdykite remdamiesi mokėjimo būsena, patvirtinta per vartus, o ne kliento grįžimu. Webhooks rekomenduojami visiems integracijos tipams – Merchant API, Hosted Checkout, Web Plugins ir Payment Links. Web Plugins Webhooks apdoroja kaip savo standartinės funkcionalumo dalį. Savo integracijoms įdiekite Webhook galinį tašką. ### Kaip tai veikia 1. Sukonfigūruokite savo Callback URL. Prekybininko portale nustatykite savo pusėje HTTPS galinį tašką, kuris gaus parduotuvės pranešimus. 2. Mokėjimo būsena pasikeičia. Klientas sumoka, nutraukia mokėjimą, užbaigiamas lėšų nuskaitymas, atliekamas grąžinimas – bet koks būsenos pokytis sukelia pranešimą. 3. Vartai praneša jūsų galiniam taškui. Pranešime nurodoma, kuris mokėjimas pasikeitė (Payment ID) ir kokia yra jo naujausia būsena. Jūsų galinis taškas patvirtina gavimą sėkmės atsakymu. 4. Jūs gaunate mokėjimo detales. Gavę pranešimą, iškvieskite Get Payment Information API, kad gautumėte visas, aktualias mokėjimo detales – pranešimas yra suveikimo signalas; API atsakymas yra autoritetingas šaltinis. 5. Atnaujinate savo užsakymą. Remdamiesi patvirtinta būsena, atnaujinkite užsakymą: vykdykite, kai būsena apmokėta, atlaisvinkite atsargas galutinio nesėkmingo mokėjimo atveju, užregistruokite grąžinimą ir t. t. Rekomenduojamą veiksmą pagal kiekvieną būseną žr. skyriuje Payment Statuses. {% hint style="info" %} Pranešimą traktuokite kaip signalą, o ne kaip duomenis. Prieš atnaujindami užsakymą visada gaukite mokėjimo detales per autentifikuotą API – tai suteikia visą dabartinę būseną ir apsaugo nuo suklastotų arba pasenusių pranešimų. {% endhint %} {% hint style="warning" %} Nesikreipkite į Get Payment Information dėl kiekvieno inicijuoto mokėjimo. Naudokite Webhooks kaip įprastą būsenos gavimo suveikimo mechanizmą. API užklauskite tik išimtiniais atvejais, pavyzdžiui, kai pranešimas negaunamas per tikėtiną laikotarpį arba kai operatorius rankiniu būdu paprašo naujausių mokėjimo detalių. {% endhint %} ### Kas sukelia pranešimą * Mokėjimo būsenos pokyčiai. Kiekvienas mokėjimo būsenos pasikeitimas – tiek mokėjimams kortele, tiek Pay by Bank. Tai apima ir grąžinimo sukeltus pokyčius: kai grąžinimas užbaigiamas, mokėjimo būsena pasikeičia į Grąžinta ir išsiunčiamas pranešimas. * Tokenų pokyčiai. Kai įjungtas tokenizavimas, vartai praneša jums apie tokenų pokyčius – pavyzdžiui, kai saugomas tokenas sustabdomas arba deaktyvuojamas – kad galėtumėte atnaujinti išsaugotus mokėjimo būdus ir pristabdyti prekybininko inicijuojamus nuskaičiavimus. Žr. Tokenization. ### Webhook galinio taško kūrimas * Naudokite HTTPS. Webhooks pristatomi tik į saugius galinius taškus. Apribokite galinį tašką tik Webhook apdorojimui. * Atsakykite greitai. Pranešimą patvirtinkite iškart ir, jei įmanoma, apdorokite asinchroniškai. Ilgai veikianti verslo logika užklausos apdorojimo funkcijoje sukelia laiko viršijimus ir nereikalingus pakartotinius bandymus. * Būkite idempotentūs. Tas pats pranešimas gali būti pristatytas daugiau nei vieną kartą – pavyzdžiui, po pakartotinio bandymo. Apdorojant pranešimą du kartus neturi atsirasti dubliuotų įvykdymų, dubliuotų grąžinimų įrašų ar dubliuotų klientų el. laiškų. * Prieš imdamiesi veiksmų, užklauskite. Niekada nespręskite vien tik iš pranešimo turinio – gaukite mokėjimą arba vartų tokeną per API ir veikite pagal patvirtintą būseną. * Tikėkitės, kad įvykiai gali būti gaunami ne eilės tvarka ir grupėmis. Visada veikite remdamiesi naujausia patvirtinta būsena iš API, o ne manydami, kad jie atkeliauja tam tikra tvarka. * Tvarkykite audito žurnalą. Registruokite gautus pranešimus su laiko žymomis – jie neįkainojami pagalbos atvejams ir sutikrinimui. ### Pristatymo pakartotiniai bandymai ir praleisti pranešimai Jei jūsų galinis taškas laikinai nepasiekiamas arba nepatvirtina pranešimo gavimo, vartai automatiškai kartoja pristatymą pagal didėjančių pakartotinių bandymų grafiką. Jei visi bandymai išnaudojami, tam įvykiui daugiau pranešimų nebesiunčiama. Projektuokite taip, kad būtų atsižvelgta į galimybę praleisti pranešimą: * Stebėkite savo galinio taško pasiekiamumą ir klaidų dažnį – sugedęs galinis taškas kliento požiūriu neveikia tyliai. * Po gedimo arba praleistų pranešimų peržiūrėkite neseniai pateiktus užsakymus, kurie vis dar laukia, ir atnaujinkite jų būseną per API. ### Konfigūracija * Nustatykite savo Callback URL Prekybininko portale → Nustatymai → Parduotuvės nustatymai → Techninė informacija. Kiekviena parduotuvė turi savo konfigūraciją. * Sandbox ir Production sukonfigūruokite atskirai – kad bandomieji pranešimai niekada nepasiektų jūsų Production galinio taško ir atvirkščiai. ### Testavimas Prieš paleisdami į gamybą, Sandbox aplinkoje patikrinkite savo Webhook apdorojimą: * Sėkmingi, nesėkmingi, atšaukti ir apleisti mokėjimo scenarijai – patikrinkite, ar kiekvienu atveju gaunamas pranešimas ir ar užsakymas atnaujinamas teisingai. * Grąžinimo scenarijai – patikrinkite, ar grąžinimo sukeltas būsenos pasikeitimas pasiekia jūsų sistemas. * Dubliuotas pristatymas – patikrinkite, ar to paties pranešimo apdorojimas du kartus nesukuria dublikatų. * Galinio taško nepasiekiamumas – išjunkite savo galinį tašką, užbaikite bandomąjį mokėjimą, vėl jį įjunkite ir patikrinkite atkūrimą per API sutikrinimą. ### Dažniausiai užduodami klausimai #### Ar man reikia Webhooks, jei naudoju Hosted Checkout? Taip – talpinamas atsiskaitymo puslapis rūpinasi kliento patirtimi, tačiau jūsų užsakymų apdorojimui vis tiek reikia žinoti mokėjimo rezultatą. Kliento grįžimas į jūsų svetainę nėra mokėjimo patvirtinimas. Jį patvirtina Webhook arba API būsenos užklausa. #### Ar man reikia Webhooks, jei naudoju Web Plugin? Web Plugins apima operacijos būsenos apdorojimą kaip savo standartinės funkcionalumo dalį. Jie apdoroja Webhooks ir atnaujina užsakymų būsenas. Jums nereikia pačiam įgyvendinti galinio taško. #### Kas nutinka, jei mano serveris buvo išjungtas, kai buvo išsiųstas pranešimas? Vartai automatiškai kartoja pristatymą vis didesniais intervalais. Jei visi pakartotiniai bandymai išnaudojami, tas pranešimas nebesiunčiamas dar kartą – sutikrinkite per Get Payment Information API ir Prekybininko portalą, kad susivestumėte praleistus būsenos pokyčius. #### Ar galiu gauti tą patį pranešimą du kartus? Taip – pavyzdžiui, jei jūsų galinis taškas atsakė lėtai ir buvo inicijuotas pakartotinis bandymas. Sukurkite apdorojimą taip, kad jis būtų idempotentinis, kad dublikatas neturėtų jokio poveikio. #### Kaip žinoti, kad pranešimas yra tikras? Nesivadovaukite vien pranešimo turiniu. Naudokite jį tik kaip suveikimo signalą ir gaukite mokėjimo detales per autentifikuotą Get Payment Information API – autoritetinga būsena visada gaunama iš API, todėl suklastotas pranešimas negali sukelti neteisingo užsakymo vykdymo. #### Apie kurias būsenas man bus siunčiami pranešimai? Kiekvienas mokėjimo būsenos pokytis sukuria pranešimą – žr. Payment Statuses (Cards) ir Pay by Bank › Payment Statuses, kur pateikti būsenų modeliai ir rekomenduojami veiksmai pagal kiekvieną būseną. ### Susijusi dokumentacija * [Mokėjimo būsenos (kortelės)](/seb-docs-draft/seb-docs-public-lt/mokejimo-metodai/korteles/mokejimo-busenos.md) * [Pay by Bank › Mokėjimo būsenos](/seb-docs-draft/seb-docs-public-lt/mokejimo-metodai/mokekite-is-banko/mokejimo-busenos.md) * [Vieninga prekybininko API](/seb-docs-draft/seb-docs-public-lt/integracija/prekybininko-api.md) * [Tokenizavimas](/seb-docs-draft/seb-docs-public-lt/mokejimo-metodai/korteles/zetonizavimas.md) * [Merchant Portal](/seb-docs-draft/seb-docs-public-lt/gaires/prekybininko-portalas.md) * [Testavimas](/seb-docs-draft/seb-docs-public-lt/mokejimo-metodai/korteles/testavimas.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/prekybininko-api/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.