# Node.js SDK (/sk/online/integration/node_sdk) `@tapayadot/checkout` je serverové TypeScript SDK pre Tapaya Checkout. Táto referencia opisuje verziu **0.3.0**. | Údaj | Hodnota | | ------------------------- | ------------------------------------------------------------------------------------------ | | **Balík** | `@tapayadot/checkout` | | **Verzia** | 0.3.0 | | **Behové prostredie** | Node.js 22.13.0 alebo novší, ES moduly, vrátane deklarácií TypeScriptu | | **Skript pre prehliadač** | Tapaya.js 0.2.0, načítavaný pre [Embedded Checkout](/online/integration/embedded_checkout) | | **Zdrojový kód** | [tapayadot/checkout-node](https://github.com/tapayadot/checkout-node) | npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` ```ts import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); ``` Klient načítava `TAPAYA_SECRET_KEY` z prostredia servera. Balík obsahuje aj loader pre prehliadač a React hook pre [Embedded Checkout](/online/integration/embedded_checkout). Loader sťahuje Tapaya.js **0.2.0** z `https://js.tapaya.com/checkout/0.2.0/checkout.js`; verzia skriptu pre prehliadač je od verzie tohto balíka nezávislá. Súbory `.env` nenačítava. Kľúč aj klienta držte iba v kóde, ktorý beží na serveri. [Sprievodca Hosted Checkout](/online/integration/hosted_checkout) opisuje vytvorenie objednávky, presmerovanie zákazníka a overenie platby. ## Konfigurácia [#configuration] ```ts const tapaya = new Tapaya(apiKey, { environment: 'sandbox', timeoutMs: 30_000, maxRetries: 2, }) ``` | Možnosť | Predvolená hodnota | Popis | | ------------------------ | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` (prvý argument) | `TAPAYA_SECRET_KEY` | Checkout kľúč obchodníka, alebo v režime platformy Secret key organizácie. | | `environment` | `TAPAYA_ENVIRONMENT`, inak `production` pre kľúč `tapaya_live_` a v ostatných prípadoch `sandbox` | `sandbox` (`https://api.sandbox.tapaya.com`) alebo `production` (`https://api.tapaya.com`). Ostrý kľúč mimo produkcie alebo testovací kľúč v produkcii vyvolá chybu už pri vytvorení klienta. | | `baseUrl` | `TAPAYA_BASE_URL`, inak URL zvolená podľa `environment` | Prepíše URL API pre hostované aj vložené volania. | | `timeoutMs` | `30000` | Časový limit každého pokusu v milisekundách. | | `merchantToken` | Žiadna | Token obchodníka, posielaný ako `X-Tapaya-Merchant-Token`. V režime platformy je povinný. | | `maxRetries` | `2` | Počet opakovaní po chybe siete, vypršaní časového limitu, HTTP 429, 502, 503 alebo 504 alebo po vytvorení, ktoré ešte prebieha. | | `fetch` | Globálny `fetch` | Vlastná implementácia `fetch`, napríklad na pridanie proxy alebo inštrumentácie. | Ak chcete použiť vlastný API endpoint, nastavte na svojom serveri `TAPAYA_BASE_URL=https://api.example.com`. Explicitne zadaná `baseUrl` má prednosť pred `TAPAYA_BASE_URL`; obe prepisujú voľbu podľa prostredia. Klient určí API kľúč a URL API raz, pri svojom vytvorení. Použite kľúč, ktorý zodpovedá zvolenému prostrediu. URL API, návratové URL a URL hostovaného Checkoutu musia používať HTTPS, s výnimkou HTTP pre `localhost`, `127.0.0.1` a `[::1]` mimo `NODE_ENV=production`. SDK kontroluje aktuálne `NODE_ENV` pri každom overení lokálnej URL s HTTP. `timeoutMs` musí byť celé číslo od 1 do 2 147 483 647. `maxRetries` musí byť nezáporné bezpečné celé číslo. Predvolený počet opakovaní umožňuje až tri pokusy na jedno volanie, každý s vlastným časovým limitom. Každá metóda prijíma aj `signal`, `timeoutMs` a `maxRetries` pre jednotlivú požiadavku: ```ts const current = await tapaya.checkout.sessions.get(sessionId, { signal: request.signal, timeoutMs: 5_000, }) ``` Keď sa signál preruší, metóda okamžite skončí bez opakovania a jej promise sa odmietne s dôvodom (reason) signálu. ## Relácie Checkoutu [#checkout-sessions] ### Výber obchodníka [#select-a-merchant] V režime obchodníka určuje obchodníka jeho checkout kľúč. Použite `new Tapaya()` bez `merchantToken`. V režime platformy obsluhuje jeden Secret key organizácie mnoho obchodníkov. Každá požiadavka potrebuje token obchodníka; neexistuje žiadny predvolený obchodník a požiadavka bez tokenu zlyhá s chybou `TapayaAuthenticationError`. Tokeny skopírujte z tabuľky obchodníkov v [nastaveniach Checkoutu](/online/integration/checkout_settings) a token danej objednávky odovzdávajte pri vytvorení aj pri načítaní: ```ts const tapaya = new Tapaya(process.env.TAPAYA_SECRET_KEY) const session = await tapaya.checkout.sessions.create(params, { merchantToken: order.merchantToken, idempotencyKey: order.checkoutAttemptKey, }) const current = await tapaya.checkout.sessions.get(session.id, { merchantToken: order.merchantToken, }) ``` Predvolený token môžete nastaviť aj pomocou `new Tapaya(key, { merchantToken })`. Token platí pre hostované aj vložené volania. Tapaya odmieta tokeny mimo organizácie daného kľúča. S kľúčom obchodníka je token voliteľný a musí označovať obchodníka, ktorému kľúč patrí. Pozrite si [Autentifikácia Checkoutu](/online/integration/api_integration#authentication). ### Vytvorenie relácie [#create-a-session] `tapaya.checkout.sessions.create(params, options?)` vyžaduje `merchantOrderId`, `amount` a `currency`. `merchantOrderId` je vaša referencia objednávky s dĺžkou 1 až 200 znakov. Objednávku možno zaplatiť iba raz; nová relácia pre nezaplatenú objednávku nahradí tú predchádzajúcu. Pozrite si [Jedna platba na objednávku](/online/integration/api_integration#one-payment-per-order). `amount` je konečná celková suma vrátane dane a dopravy, celé číslo od 1 do 2 147 483 647 v najmenších jednotkách meny. `currency` je trojpísmenový kód podľa ISO 4217. Tapaya ho ukladá a vracia veľkými písmenami. Voliteľné polia: | Pole | Popis | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `locale` | Jazyk hostovanej stránky, napríklad `en`. Predvolená hodnota je `en`. | | `successUrl`, `cancelUrl` | Návratové URL. Predvolene sa použijú URL z vašich nastavení Checkoutu. | | `tax`, `shipping` | Daň a doprava zahrnuté v `amount`, v najmenších jednotkách meny. | | `taxRate` | Jediná daňová sadzba v percentuálnych bodoch, napríklad `21`. | | `taxBreakdown` | Daň podľa sadzieb, `[{ taxRate, tax }]`, pre objednávky so zmiešanými sadzbami. Použite namiesto `taxRate`: typy nepripúšťajú obe naraz. | | `items` | Produkty zobrazené na hostovanej stránke: `reference`, `name`, `description`, `imageUrl`, `quantity` a `unitAmount`. Položky slúžia len na zobrazenie a nemenia účtovanú sumu. | | `customer` | Voliteľné údaje `email`, `billingAddress` a `shippingAddress`. Posielajte len údaje, ktoré zbierate. | Pred odoslaním SDK kontroluje typy, povinné polia, celočíselné sumy, formát meny a maximálnu dĺžku e-mailu 254 znakov. Návratové URL musia byť absolútne URL s HTTPS, s výnimkou pre lokálne HTTP opísanou v časti [Konfigurácia](#configuration). Tapaya overuje obchodné pravidlá, ako je formát e-mailu, limity adresy a kódy krajín, a problémy hlási ako `TapayaInvalidRequestError`. Pravidlá polí, súčty daní a limity adresy zákazníka nájdete v časti [Relácie Checkoutu](/online/integration/api_integration#checkout-sessions). ### Načítanie relácie [#get-a-session] `tapaya.checkout.sessions.get(id, options?)` vracia aktuálny stav relácie. ID musí byť neprázdny reťazec s dĺžkou najviac 200 znakov; `.` a `..` sú neplatné. SDK ID zakóduje do URL. Vytvorenie a načítanie hostovanej relácie vracia `HostedCheckoutSession`. Metódy pre vložené platby `prepare()`, `verify()` a `configuration()` opisuje stránka [Embedded Checkout](/online/integration/embedded_checkout). Polia hostovanej relácie: | Pole | Popis | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `id` | ID relácie, napríklad `cs_Y7u2d`. | | `url` | Hostovaná platobná stránka. Presmerujte na ňu bez zmeny. | | `merchantOrderId`, `amount`, `currency` | Údaje objednávky na porovnanie s vašou uloženou objednávkou. | | `status` | `open`, `completed` alebo `expired`. Relácie prijímajú nové platby počas 30 minút. Môžu pribudnúť nové hodnoty. | | `paymentStatus` | `unpaid`, `successful`, `failed`, `cancelled` alebo `action_needed`. Môžu pribudnúť nové hodnoty. | | `paymentReference` | Token posledného pokusu o platbu, alebo `null` pred prvým pokusom. | | `tax`, `shipping`, `taxRate`, `taxBreakdown` | Súčty odoslané pri vytvorení relácie. Predvolené hodnoty sú `0`, `0`, `null` a `[]`. | | `items` | Položky odoslané pri vytvorení relácie, alebo prázdne pole. | | `createdAt`, `expiresAt`, `completedAt` | Časové pečiatky vo formáte ISO 8601. `completedAt` je `null`, kým platba neprebehne úspešne. | Ošetrite neznáme hodnoty `status` a `paymentStatus`, napríklad tak, že s nimi budete zaobchádzať ako s ešte nezaplatenými. Platbu dokazuje iba `paymentStatus: 'successful'`. Zamietnutá karta je výsledok platby, nie chyba. Relácia zostane `open` s `paymentStatus: 'failed'` a zákazník to môže skúsiť znova. Kým Tapaya potvrdzuje neistý výsledok, relácia zostáva `open` a `unpaid`. Webhooky zatiaľ nie sú k dispozícii; z úlohy na odsúhlasenie pravidelne volajte `get()`. ## Idempotencia a opakovanie požiadaviek [#idempotency-and-retries] Každá požiadavka na vytvorenie posiela `Idempotency-Key`. Explicitne zadaný kľúč musí byť neprázdny reťazec z tlačiteľných znakov ASCII. Tapaya prijíma najviac 250 znakov. Ak `idempotencyKey` vynecháte, SDK pre každé volanie vygeneruje náhodný kľúč. V rámci tohto volania opakovania kľúč znova používajú, takže opakovanie nikdy nevytvorí druhú reláciu. Aby bolo vytváranie bezpečné aj naprieč samostatnými volaniami a reštartmi procesu, uložte kľúč spolu s objednávkou a odovzdávajte ho zakaždým, keď pre daný pokus vytvárate reláciu, s rovnakými parametrami. Tapaya vráti pôvodnú reláciu namiesto toho, aby vytvorila novú. Nový kľúč použite iba pre nový pokus o zaplatenie, nikdy na opakovanie neistého výsledku. Opakované vytvorenie hostovanej relácie vráti tú istú reláciu s jej aktuálnymi hodnotami `status` a `paymentStatus`. Pred vybavením objednávky zavolajte `tapaya.checkout.sessions.get(session.id)` a stav znova overte. Pre toho istého obchodníka musia opakovania hostovaných požiadaviek používať rovnaké telo požiadavky a rovnaký režim prihlasovacích údajov: checkout kľúč obchodníka alebo Secret key organizácie. Zmena ktoréhokoľvek z nich vráti HTTP 409 s kódom `API-0025`. Prepnutie režimu prihlasovacích údajov vedie ku konfliktu aj pri zhodnom tele, pretože každý režim používa vlastné nastavenia presmerovania. SDK opakuje obe metódy po chybách siete, vypršaní časového limitu a HTTP 429, 502, 503 a 504. Opakuje aj vytvorenie, ktoré zlyhá s HTTP 409 `API-0024`. Opakovania posielajú rovnaký kľúč a telo, takže vrátia pôvodnú reláciu. SDK medzi pokusmi čaká s exponenciálne sa predlžujúcim odstupom (exponential backoff) a náhodným rozptylom (jitter) a rešpektuje `Retry-After` až do 10 sekúnd. Keď Tapaya požiada o dlhšie čakanie, SDK prestane opakovať a vyvolá chybu zodpovedajúcu danému stavu HTTP: `TapayaRateLimitError` pre 429, `TapayaServerError` pre 502, 503 alebo 504, alebo `TapayaConflictError` pre 409. Požadované oneskorenie ako `retryAfterMs` sprístupňuje iba `TapayaRateLimitError`; ostatné chyby HTTP uchovávajú hlavičku `Retry-After` v `headers`. Všetky opakovania zdieľajú limit `maxRetries`. Nastavením `maxRetries: 0` opakovanie vypnete. Nikdy neprechádzajte na nový kľúč, aby ste obišli neistý výsledok. Pôvodná požiadavka už mohla vytvoriť reláciu; s novým kľúčom a tou istou nezaplatenou objednávkou ju nová relácia nahradí. ## Chyby [#errors] Triedy chýb SDK rozširujú `TapayaError`. Promise prerušenej požiadavky sa odmietne s dôvodom uvedeným v signáli. | Chyba | Kedy | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TapayaError` | Chýba API kľúč alebo je konfigurácia klienta neplatná; základná trieda chýb SDK. | | `TapayaValidationError` | Parametre neprešli validáciou ešte pred odoslaním požiadavky. | | `TapayaAuthenticationError` | HTTP 401: kľúč chýba alebo je neplatný, v režime platformy chýba token obchodníka, alebo token nezodpovedá aktívnemu obchodníkovi. | | `TapayaInvalidRequestError` | HTTP 400 alebo 422: Tapaya parametre odmietla. | | `TapayaPermissionError` | HTTP 403. | | `TapayaNotFoundError` | HTTP 404: relácia pre tohto obchodníka neexistuje. | | `TapayaConflictError` | HTTP 409. `code` je `API-0025`, ak bol idempotency key už použitý s inými parametrami. Vytvorenie relácie pre objednávku, ktorá je už zaplatená alebo pri ktorej prebieha platba, tiež vráti 409. | | `TapayaRateLimitError` | HTTP 429 po vyčerpaní opakovaní, alebo ihneď, keď je `Retry-After` dlhší ako 10 sekúnd. `retryAfterMs` obsahuje požadované oneskorenie, ak ho Tapaya pošle. | | `TapayaServerError` | HTTP 5xx. Opakujú sa iba 502, 503 a 504, a to len ak opakovania nie sú vypnuté a `Retry-After` nepresahuje 10 sekúnd. Ostatné stavy 5xx zlyhajú okamžite. | | `TapayaApiError` | Základná trieda vyššie uvedených chýb HTTP a akéhokoľvek iného chybového stavu HTTP. | | `TapayaConnectionError` | Požiadavka zlyhala alebo sa odpoveď po vyčerpaní opakovaní stratila. Pôvodná chyba je v `cause`. | | `TapayaTimeoutError` | `TapayaConnectionError` pre pokus, ktorý prekročil `timeoutMs`. | | `TapayaResponseError` | Tapaya vrátila odpoveď, ktorú SDK nedokázalo prečítať. | Chyby HTTP nesú `status`, chybový `code` Tapaya, `fieldErrors` (`{ field, message, code? }[]`), `headers` odpovede a `requestId` z hlavičky `X-Request-Id`, ak je prítomná. Backend túto hlavičku v súčasnosti nenastavuje. Do požiadaviek na podporu uveďte ID relácie alebo referenciu objednávky a čas požiadavky, a tiež `requestId`, ak je k dispozícii. `TapayaResponseError` nesie tiež `status`, `headers` a `requestId`. `TapayaValidationError` nesie tiež `fieldErrors`, kde `field` obsahuje cestu k parametru, napríklad `customer.email`. ```ts import { TapayaConnectionError, TapayaError, TapayaValidationError } from '@tapayadot/checkout' try { const session = await tapaya.checkout.sessions.create(params, { idempotencyKey }) return Response.redirect(session.url, 303) } catch (error) { if (error instanceof TapayaValidationError) { console.error(error.fieldErrors) } else if (error instanceof TapayaConnectionError) { // The outcome is unknown. Retry later with the same idempotency key. } else if (error instanceof TapayaError) { console.error(error.message) } throw error } ``` ## Exportované typy [#exported-types] Balík exportuje `TapayaEnvironment`, `TapayaOptions`, `RequestOptions`, `CreateSessionOptions`, `CreateCheckoutSessionParams`, `CheckoutSessions`, `CheckoutSession`, `CheckoutSessionStatus`, `CheckoutPaymentStatus`, `CheckoutItem`, `TaxBreakdownEntry`, `CheckoutCustomer`, `CheckoutContactAddress` a `TapayaFieldError`. `VERSION` obsahuje verziu SDK. Typy importujte ako pomenované importy pomocou `import type`: ```ts import type { CheckoutSession, CreateCheckoutSessionParams } from '@tapayadot/checkout'; ``` ## Prechod z verzie 0.2.x [#upgrade-from-02x] * Loader pre prehliadač načítava Tapaya.js 0.2.0, ktorý podporuje Apple Pay a Google Pay. Už načítaný skript 0.1.x odmietne. Každú značku script, ktorú spravujete, aktualizujte na `https://js.tapaya.com/checkout/0.2.0/checkout.js`. * `environment: 'production'` podporuje hostované aj vložené platby. `configuration()` vracia `environment: 'production'` s kľúčmi ostrej platobnej brány. * Bez explicitne zadaného prostredia alebo `TAPAYA_ENVIRONMENT` volí kľúč `tapaya_live_` produkciu. Prihlasovacie údaje, ktoré nezodpovedajú zvolenému prostrediu, zlyhajú pri vytváraní klienta. `baseUrl` stále prepisuje URL API.