> 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-et/integratsioon/api-kliendi-sdk/juhendid/turvamehhanismid.md).

# Turvamehhanismid

Kaitske SDK-integratsioone OAuthi, JWE krüptimise, webhook-kaitsete ja logimise juhtimisega.

> Mustand · SDK alfa. Kehtib kõigile neljale keelele; erinevused on keelepõhiselt välja toodud. Märgitud üksused **\[TBC]** tuleb enne avaldamist veel lisada.

See leht käsitleb kolme turvakriitilist mehhanismi, mida SDK teie eest haldab — OAuth 2.0 autentimist, JWE-kaardiandmete krüpteerimist ja veebikonksu teavitusi — ning seda, mida peate **ei** nende ümber ise lahendama.

## Autentimine

SDK autentib **OAuth 2.0 klienditunnustega**. Kliendi loomisel esitate kliendi ID ja kliendisaladuse; kõik muu toimub automaatselt:

* Juurdepääsuluba hangitakse **alles vajaduse korral** esimese API-kutse ajal ja **salvestatakse mällu vahemällu**.
* Token värskendatakse ennetavalt umbes 30 sekundit enne selle `expires_in` -eluea lõppu. Värskendustokeneid ei kasutata.
* Te ei pea tokeniga ise kunagi tegelema ning SDK ei kirjuta mandaate ega tokeneid oma logijasse.

Mida peate tegema:

* Hoidke kliendisaladust keskkonnamuutujas või saladuste hoidlas. **Ärge kunagi lisage seda versioonihaldusesse ega logige seda.**
* Kasutage sama kliendiinstantsi uuesti; iga uus instants hangib oma tokeni.

Mida SDK ei tee: see ei proovi uuesti päringut, mis ebaõnnestub HTTP 401-ga keset edastust. Tokeni aegumist jälgitakse lokaalselt, seega juhtub see vaid siis, kui mandaadid tühistatakse või kell nihkub; kõne kuvab vea ning järgmine kõne pärast kohalikku aegumist hangib värske tokeni.

## Kaardiandmete krüpteerimine (JWE)

Kui loote **kaardi maksesessiooni**, siis kaardiandmeid (`cardNumber`, `csc`, `expiry`, `cardholderName`) ei saadeta kunagi lihttekstina. SDK krüpteerib need JWE kompaktseks esituseks, kasutades **JWE kompaktset serialiseerimist** (RSA-OAEP-256 võtmekrüpteerimine, A256GCM sisukrüpteerimine) ning **JWK-vormingus avalikku RSA-võtit** mis hangitakse automaatselt EGW võtme lõpp-punktist. Teie poolel pole midagi installida ega roteerida — kuid krüpteerimine on **teie selgesõnaline samm** päringu koostamisel:

**Java** (builderi abimeetod serialiseerib ja krüpteerib ühe sammuga):

```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:** koostage lihttekstandmete objekt, krüpteerige funktsiooniga `client.EncryptToJweCompact(...)` / `$client->encryptToJweCompact(...)` / `await client.encryptToJweCompact(...)`, ja määrake tulemus päringu `encryptedCard` väljaks.

Reeglid:

* **Ärge kunagi** paigutage lihttekstis kaardivälju kusagile muusse päringu ossa, logidesse ega salvestusse. JWE string on ainus kaardiandmete artefakt, mis teie protsessist väljub.
* Ärge vahemällu salvestage krüpteerimisvõtit ega JWE väljundit maksete vahel; krüpteerige iga seansi kohta eraldi.
* Ainult C#: seadistage JWK lõpp-punkt (`EncryptingWith(...)`) konstruktori juures — ilma selleta ebaõnnestuvad krüpteerimiskutsed kohe, mitte ei saadeta lihtteksti. Node.js: `jwkUri` on kohustuslik seadistusväli.

### Võtmevaliku ja võtmerotatsiooni poliitika

See on **normatiivne poliitika** kõigi API Client SDK-de jaoks. Krüpteerimisel valib SDK kasutatava võtme järgmiselt:

1. võttes ainult võtmed, millel on `use=enc` ja `kty=RSA`;
2. välistades tühistatud võtmed;
3. valides neist uusima `iat`;
4. **hinnates seda uuesti iga krüpteerimise korral** — valitud võtit ei vahemällustata kunagi toimingute vahel.

Iga kord uuesti hindamine on tahtlik: see tähendab, et serveripoolne võtmerotatsioon jõustub kohe, ilma taaskäivituse ja vananenud võtme tõrgeteta.

> ⚠️ **PHP-s, C#-s ja Node.js-is looge klient perioodiliselt uuesti — vastasel juhul rikub serveripoolne võtmerotatsioon pikaealised protsessid.** Need kolm SDK-d vahemällustavad praegu esimese võtme, mille nad kliendi eluea jooksul hangivad, selle asemel et hinnata iga krüpteerimise puhul uuesti, ning C# võtab lisaks `keys[0]` ilma filtreerimata `use` või `kty` ja kodeerib RSA-OAEP-256 kõvakoodina. Java rakendab poliitikat täielikult; ülejäänud kolm viiakse enne väljalaskmist sellega vastavusse.

## Webhook-teavitused

EGW saab edastada makseoleku teavitusi teie avaldatud HTTPS-i lõpp-punkti. SDK aitab teil neid töödelda:

* **Java / PHP / C#** — sisseehitatud kuulaja: seadistage `listeningAt(...)` / `ListeningOn(...)` tehases, seejärel registreerige käsitleja:

```java
client.notifications().receiveNotifications(notification -> {
    // notification.getType(), notification.getPaymentId(), notification.getPaymentStatus()
});
```

Kuulaja vastab **HTTP 200-ga** kui teie käsitleja lõpetab edukalt ja **HTTP 500-ga** kui see viskab vea (siis saab EGW teate uuesti edastada). Hoidke käsitlejad kiired ja idempotentsed.

* **Node.js** — sisseehitatud kuulajat pole: avaldage lõpp-punkt oma HTTP-serveris ja deserialiseerige keha funktsiooniga `client.notifications().parseWebhook(payload)`.

### Teavituste autentsus

> ⚠️ **Kinnitage olek alati API kaudu enne teavituse põhjal tegutsemist — ärge kunagi saatke kaupa välja, arveldage ega uuendage tellimust üksnes webhooki keha põhjal.** Makseteavituse korral kutsuge `getPaymentInformation(paymentId)` (autentitud) ja tegutsege selle vastuse põhjal. Põhjus: platvorm ei allkirjasta teavituse payload’e ega paku lõpp-punkti autentimist (ei mTLS-i, ei basic auth’i, ei jagatud saladust), seega pole SDK-l midagi kontrollida ning igaüks, kes pääseb teie lõpp-punktile ligi, võib saata korrektse teavituse. Kohtlege iga teavitust usaldusväärse vihjena, mitte faktina — API kinnitus on ainus kontroll forgitud POST-i ja täidetud tellimuse vahel.

Käivitage kuulaja HTTPS-i lõpetava reverse proxy taga. Sisseehitatud kuulajad (Java/PHP/C#) kasutavad tavalist HTTP-d — Java kuulaja vaikimisi pordil 80. Ärge avage kuulaja porti otse internetti; pange selle ette proxy, mis lõpetab TLS-i ja edastab sisemises võrgus kuulajale.

Lisaks rakendage oma organisatsiooni tavapäraseid kontrollimeetmeid avalikult ligipääsetava lõpp-punkti jaoks.

Teavituste sündmuse tüübi kataloog: **\[TBC — link]**

## Logimine

Kõigi keelte vaikimisi logija on vaikne tühi toiming — vaikimisi turvaline. Kui ühendate päris logija:

* SDK ei logi kunagi mandaate, tokeneid ega kaardiandmeid.
* Käsitle SDK ERROR-logisid nii, nagu need sisaldaksid maksemetaandmeid, ja ärge edastage neid süsteemidesse, mis peavad neist puhtad olema. HTTP 4xx/5xx vastuste korral logib SDK töötlemata veavastuse keha ERROR-tasemel, redigeerimata, ning veakehad võivad sisaldada tellimuse viiteid, summasid ja kliendile mõeldud sõnumeid. See on teadaolev alfa piirang, mitte kavandatud käitumine — maskeerimine on plaanis, kuid seda pole veel rakendatud.
* Ebaõnnestunud tokenipäringute erindisõnumid sisaldavad autentimisserveri vastuse keha. Töötlege ja logige erindeid sama ettevaatlikult.


---

# 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-et/integratsioon/api-kliendi-sdk/juhendid/turvamehhanismid.md?ask=<question>&goal=<user_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.