> 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/api-kliento-sdk/gaires/saugumo-mechanizmai.md). # Saugumo mechanizmai Apsaugokite SDK integracijas naudodami OAuth, JWE šifravimą, webhook apsaugas ir žurnalinimo valdiklius. > Juodraštis · SDK alfa. Taikoma visoms keturioms kalboms; skirtumai nurodomi prie kiekvienos kalbos. Elementai, pažymėti **\[TBC]** dar turi būti pateikti prieš publikavimą. Šiame puslapyje aprašomi trys saugai jautrūs mechanizmai, kuriuos SDK valdo už jus — OAuth 2.0 autentifikavimas, JWE kortelės duomenų šifravimas ir webhook pranešimai — ir ką jūs turite **ne** aplenkti juos savo sprendimais. ## Autentifikavimas SDK autentifikuojasi naudodamas **OAuth 2.0 kliento kredencialus**. Kliento kūrimo metu pateikiate kliento ID ir kliento paslaptį; visa kita vyksta automatiškai: * Prieigos žetonas gaunamas **pagal poreikį** per pirmąjį API iškvietimą ir **saugomas atmintyje**. * Žetonas atnaujinamas iš anksto maždaug 30 sekundžių prieš jo `expires_in` galiojimo pabaigą. Atnaujinimo žetonai nenaudojami. * Jūs niekada pats nevaldote žetono, o SDK niekada nerašo kredencialų ar žetonų į savo žurnalą. Ką turite padaryti: * Laikykite kliento paslaptį aplinkos kintamajame arba paslapčių saugykloje. **Niekada jos neįtraukite į versijų valdymą ir niekada neregistruokite.** * Naudokite vieną kliento egzempliorių pakartotinai; kiekvienas naujas egzempliorius gauna savo žetoną. Ko SDK nedaro: jis nepakartoja užklausos, kuri vykdymo metu nepavyksta su HTTP 401. Žetono galiojimo pabaiga stebima lokaliai, todėl tai įvyksta tik tada, jei kredencialai panaikinami arba nesutampa laikrodžio laikas; iškvietimas pateikia klaidą, o kitas iškvietimas po vietinio galiojimo pabaigos gauna naują žetoną. ## Kortelės duomenų šifravimas (JWE) Kai kuriate **kortelės atsiskaitymo sesiją**, kortelės duomenys (`cardNumber`, `csc`, `expiry`, `cardholderName`) niekada nesiunčiami atviru tekstu. SDK juos užšifruoja į **JWE kompaktišką serializaciją** (RSA-OAEP-256 raktų šifravimą, A256GCM turinio šifravimą) naudojant **viešąjį RSA raktą JWK formatu** automatiškai gaunamą iš EGW rakto galinio taško. Jums nieko nereikia diegti ar keisti rotacijos būdu — tačiau šifravimas yra **jūsų aiškus veiksmas** kuriant užklausą: **Java** (konstruktoriaus pagalbinė priemonė serializuoja ir šifruoja vienu žingsniu): ```java var request = CreateCardCheckoutSessionRequest.builder() .encryptedCard(client, data -> data.card(c -> c .cardNumber("4111111111111111") .csc("123") .expiry(e -> e.month("12").year("30")) .cardholderName("JOHN DOE"))) .build(); var session = client.cardSessions().createCardCheckoutSession(paymentId, request); ``` **C# / PHP / Node.js:** sukurkite nešifruotą duomenų objektą, užšifruokite naudodami `client.EncryptToJweCompact(...)` / `$client->encryptToJweCompact(...)` / `await client.encryptToJweCompact(...)`, o rezultatą nustatykite kaip užklausos `encryptedCard` laukelį. Taisyklės: * **Niekada** nedėkite kortelės laukų nešifruotu tekstu niekur kitur užklausoje, žurnaluose ar saugykloje. JWE eilutė yra vienintelis kortelės duomenų artefaktas, kuris palieka jūsų procesą. * Nekaupkite šifravimo rakto ar JWE išvesties tarp mokėjimų; šifruokite kiekvienai sesijai. * Tik C#: sukonfigūruokite JWK galinį tašką (`EncryptingWith(...)`) kliento kūrimo metu — be jo šifravimo iškvietimai iš karto nepavyks, o ne bus siunčiami atviri duomenys. Node.js: `jwkUri` yra privalomas konfigūracijos laukas. ### Rakto parinkimo ir rotacijos politika Tai yra **normatyvinė politika** visiems API kliento SDK. Šifruodamas SDK pasirenka naudotiną raktą taip: 1. imdamas tik raktus su `use=enc` ir `kty=RSA`; 2. neįtraukdamas panaikintų raktų; 3. pasirinkdamas tą, kurio `iat`; 4. **yra** naujausias; tai iš naujo įvertinama kiekvieno šifravimo metu — pasirinktas raktas niekada nekaupiamas tarp operacijų. Kiekvieną kartą vertinti iš naujo pasirinkta sąmoningai: tai reiškia, kad serverio pusėje atlikta rakto rotacija įsigalioja nedelsiant, nereikia paleisti iš naujo ir nekyla pasenusio rakto klaidų. > ⚠️ **PHP, C# ir Node.js aplinkose periodiškai iš naujo kurkite klientą — kitu atveju serverio pusėje atliekama rakto rotacija suardys ilgai veikiančius procesus.** Šie trys SDK šiuo metu kaupia pirmą gautą raktą visam kliento gyvavimo laikui, užuot įvertinę jį iš naujo kiekvieno šifravimo metu, o C# papildomai paima `keys[0]` nefiltruodamas pagal `use` arba `kty` ir įtvirtina RSA-OAEP-256. Java įgyvendina šią politiką pilnai; kiti trys prieš išleidimą bus suderinti su ja. ## Webhook pranešimai EGW gali siųsti mokėjimo būsenos pranešimus į jūsų pateiktą HTTPS galinį tašką. SDK padeda juos apdoroti: * **Java / PHP / C#** — įmontuotas klausytojas: sukonfigūruokite `listeningAt(...)` / `ListeningOn(...)` gamykloje, tada užregistruokite tvarkytuvą: ```java client.notifications().receiveNotifications(notification -> { // notification.getType(), notification.getPaymentId(), notification.getPaymentStatus() }); ``` Klausytojas atsako **HTTP 200** kai jūsų tvarkytuvas baigia darbą ir **HTTP 500** jei jis išmeta klaidą (tuomet EGW gali persiųsti dar kartą). Tvarkytuvai turi būti greiti ir idempotentiški. * **Node.js** — nėra įmontuoto klausytojo: atskleiskite galinį tašką savo HTTP serveryje ir deserializuokite turinį naudodami `client.notifications().parseWebhook(payload)`. ### Pranešimų autentiškumas > ⚠️ **Visada patvirtinkite būseną per API prieš imdamiesi veiksmų pagal pranešimą — niekada nesiųskite prekių, neatsiskaitykite ir neatnaujinkite užsakymo remdamiesi vien webhook turiniu.** Gavę mokėjimo pranešimą, iškvieskite `getPaymentInformation(paymentId)` (autentifikuotai) ir veikite pagal tą atsakymą. Priežastis: platforma nepasirašo pranešimų turinio ir nesiūlo galinio taško autentifikavimo (nėra mTLS, nėra paprasto autentifikavimo, nėra bendro slaptuko), todėl SDK neturi ko tikrinti, o kiekvienas, kuris gali pasiekti jūsų galinį tašką, gali pateikti tinkamai suformuotą pranešimą. Laikykite kiekvieną pranešimą nepatikimu užuominu, niekada ne faktu — API patvirtinimas yra vienintelė apsauga tarp suklastoto POST ir įvykdyto užsakymo. Leiskite klausytojui veikti už atvirkštinio tarpinio serverio, kuris užbaigia HTTPS. Įmontuoti klausytojai (Java/PHP/C#) kalba paprastu HTTP — Java klausytojo numatytasis prievadas yra 80. Neatidengkite klausytojo prievado tiesiogiai internetui; prieš jį pastatykite tarpinį serverį, kad jis užbaigtų TLS ir persiųstų srautą klausytojui vidiniame tinkle. Be to, taikykite savo organizacijos standartines viešai pasiekiamo galinio taško kontrolės priemones. Pranešimų įvykių tipų katalogas: **\[TBC — nuoroda]** ## Registravimas Numatytasis žurnalo registratorius kiekvienoje kalboje yra tylus neveiksmas — pagal nutylėjimą saugu. Jei prijungsite tikrą registratorių: * SDK niekada neregistruoja kredencialų, žetonų ar kortelės duomenų. * SDK ERROR žurnalus tvarkykite taip, tarsi juose būtų mokėjimo metaduomenų, ir neperduokite jų sistemoms, kurios turi likti be jų. Gavęs HTTP 4xx/5xx atsakymus, SDK registruoja neapdorotą klaidos atsakymo turinį ERROR lygiu, be redagavimo, o klaidų turinys gali turėti užsakymo nuorodas, sumas ir klientui skirtas žinutes. Tai žinoma alfa versijos ribotumo problema, o ne numatytas veikimas — redagavimas planuojamas, bet dar neįdiegtas. * Nepavykusių žetono užklausų išimčių pranešimuose yra autentifikavimo serverio atsakymo turinys. Su išimtimis elkitės ir jas registruokite taip pat atsargiai. --- # 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/api-kliento-sdk/gaires/saugumo-mechanizmai.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.