# Integrácia API (/sk/online/integration/api_integration) Váš backend vytvorí pre každú objednávku reláciu Checkoutu a načíta ju, aby overil platbu. Pre Node.js poskytuje [SDK `@tapayadot/checkout`](/online/integration/node_sdk) pre tieto endpointy typované metódy `create()` a `get()`. Predvolene načítava `TAPAYA_SECRET_KEY`. Príklady HTTP na tejto stránke odovzdávajú `TAPAYA_CHECKOUT_API_KEY` explicitne. ## Autentifikácia [#authentication] Každé volanie Checkoutu prebieha medzi servermi a posiela kľúč ako bearer token: ```http Authorization: Bearer ``` Zvoľte režim podľa toho, kto backend prevádzkuje. Oba typy kľúčov uchovávajte na svojom serveri; pozrite si [Zabezpečenie Checkoutu](/online/security/checkout_security). ### Režim obchodníka [#merchant-mode] Tento režim použite, keď backend obsluhuje jeden obchod. V [nastaveniach Checkoutu](/online/integration/checkout_settings#create-merchant-checkout-keys) vytvorte **checkout kľúč obchodníka**: otvorte obchodníka a zvoľte **Create merchant key**. Kľúč začína na `tapaya_test_` v sandboxe alebo `tapaya_live_` v produkcii a zodpovedá práve tomuto obchodníkovi. ```http Authorization: Bearer ``` `X-Tapaya-Merchant-Token` je v tomto režime voliteľný. Ak ho pošlete, musí označovať toho istého obchodníka. Tapaya Platform zobrazí kľúč iba raz a ukladá len jeho hash. Pri rotácii kľúča najprv vytvorte náhradný kľúč a až potom zneplatnite starý. Zneplatnenie kľúča neovplyvní ostatné kľúče obchodníkov, kľúče organizácie ani client secrets, ktoré už boli vydané prehliadačom. ### Režim platformy [#platform-mode] Tento režim použite, keď jeden backend koná za mnoho obchodníkov, napríklad marketplace alebo platforma na rozvoz jedla. V **každej** požiadavke pošlite Secret key organizácie zo [stránky API Keys](https://platform.tapaya.com/api-keys/) a token obchodníka: ```http Authorization: Bearer X-Tapaya-Merchant-Token: ``` Neexistuje žiadny predvolený obchodník. Požiadavka bez tejto hlavičky vráti HTTP 401. Obchodník musí patriť do organizácie daného kľúča. Tokeny obchodníkov skopírujte z tabuľky obchodníkov v [nastaveniach Checkoutu](/online/integration/checkout_settings). Token identifikuje obchodníka; nie je tajný. Secret key organizácie je ten istý prihlasovací údaj, ktorý [dokumentácia Platform API](/platform-api#authentication) nazýva Server Secret Token. Checkout vyžaduje predponu `Bearer`. Ostatné endpointy Platform API prijímajú token priamo. Onboarding obchodníkov a správa organizácie prebiehajú cez [Platform API](/platform-api). Telá požiadaviek neprijímajú `merchantId`. ## Prostredia [#environments] | Prostredie | Origin API | Origin Hosted Checkoutu | Prihlasovacie údaje | | ---------- | -------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- | | Sandbox | `https://api.sandbox.tapaya.com` | `https://checkout.sandbox.tapaya.com` | Sandboxové kľúče s [testovacími kartami](/online/getting-started/testing) | | Produkcia | `https://api.tapaya.com` | `https://checkout.tapaya.com` | Ostré kľúče so skutočnými platobnými metódami | Nastavte `TAPAYA_CHECKOUT_API_URL` na origin API pre vaše prostredie. V produkcii sú k dispozícii hostované aj vložené platby. Každý obchodník musí prejsť [onboardingom](/merchants/onboarding), získať od spracovateľa schválenie pre online platby a mať nakonfigurovanú platobnú bránu. Pripravenosť obchodníka skontrolujete v [nastaveniach Checkoutu](/online/integration/checkout_settings). Vrátenú URL hostovanej relácie používajte bez zmeny. ## Relácie Checkoutu [#checkout-sessions]
### Vytvorenie relácie Checkoutu [#create-a-checkout-session] Reláciu vytvorte, keď zákazník vo vašom obchode klikne na **Checkout**, a potom ho presmerujte na vrátenú `url`. Najprv na svojom serveri vypočítajte konečnú celkovú sumu a uložte objednávku s jedinečným idempotency key (kľúčom idempotencie). **Endpoint:** `POST /merchant/checkout-sessions` cURL ```bash curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ -H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \ -H 'Idempotency-Key: order-1001-checkout-1' \ -d '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "tax": 2100, "shipping": 605, "taxRate": 21, "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` **Hlavičky:** | Hlavička | Povinné | Popis | | ------------------------- | --------------- | --------------------------------------------------------------------------------------------------- | | `Authorization` | ✓ | `Bearer `: checkout kľúč obchodníka alebo Secret key organizácie. | | `X-Tapaya-Merchant-Token` | Režim platformy | Token obchodníka patriaceho do organizácie daného kľúča. S checkout kľúčom obchodníka je voliteľný. | | `Idempotency-Key` | ✓ | Neprázdny, najviac 250 znakov. Pozrite si [Idempotencia a chyby](#idempotency-and-errors). | **Parametre:** | Pole | Typ | Povinné | Popis | | ----------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | `merchantOrderId` | `string` | ✓ | Vaša referencia objednávky, 1 až 200 znakov. Pozrite si [Jedna platba na objednávku](#one-payment-per-order). | | `amount` | `integer` | ✓ | Konečná účtovaná suma v najmenších jednotkách meny vrátane dane a dopravy. 1 až 2 147 483 647. | | `currency` | `string` | ✓ | Trojpísmenový kód podľa ISO 4217 podporovaný backendom, veľkými písmenami, napríklad `EUR`. | | `locale` | `string` | | Predvolená hodnota je `en`. | | `successUrl` | `string` | | Prepíše predvolenú URL úspechu pre túto reláciu. Musí zodpovedať povolenému webu volajúceho prihlasovacieho údaja. | | `cancelUrl` | `string` | | Prepíše predvolenú URL zrušenia pre túto reláciu. Musí zodpovedať povolenému webu volajúceho prihlasovacieho údaja. | | `tax` | `integer` | | DPH už zahrnutá v `amount`, v rozsahu od nuly do `amount`. Predvolená hodnota je `0`. | | `shipping` | `integer` | | Doprava už zahrnutá v `amount`, v rozsahu od nuly do `amount`. Predvolená hodnota je `0`. | | `taxRate` | `number` | | Sadzba DPH v percentách pre celú objednávku, napríklad `21` alebo `5.5`. Nezáporná. | | `taxBreakdown` | `array` | | DPH zoskupená podľa sadzieb. Neprázdne pole nemožno použiť spolu s `taxRate`. | | `items` | `array` | | Položky objednávky len na zobrazenie. Neurčujú účtovanú sumu. | | `customer` | `object` | | E-mail, fakturačná adresa a doručovacia adresa zákazníka. | Relácia účtuje v mene `currency`, ktorú nastavíte. Stránka [Podporované meny](/merchants/supported_currencies) uvádza všetky meny, ktoré Tapaya podporuje, obchodník však má zvyčajne povolené len niektoré z nich. Vytvorenie relácie v mene, ktorú obchodník alebo backend nepodporuje, sa odmietne, takže sa nevytvorí žiadna hostovaná stránka. API účtuje sumu `amount` presne tak, ako je zadaná. Nepripočítava dopravu ani daň, nevypočítava DPH zo sadzby ani nevypočítava celkovú sumu z položiek. Každá položka obsahuje číselnú `taxRate` a celočíselnú `tax`, obe nezáporné. Sadzby sú jedinečné a sumy dane jednotlivých položiek dávajú v súčte `tax` na najvyššej úrovni. ```json { "amount": 22650, "currency": "EUR", "tax": 2650, "shipping": 605, "taxBreakdown": [ { "taxRate": 21, "tax": 2100 }, { "taxRate": 5.5, "tax": 550 } ] } ``` Každá položka vyžaduje `reference`, `name`, `description`, `imageUrl`, `quantity` a `unitAmount`. Textové polia sú neprázdne, `imageUrl` je URL, `quantity` je kladné celé číslo a `unitAmount` je nezáporné celé číslo v najmenších jednotkách meny. Objekt `customer` prijíma `email`, `billingAddress` a `shippingAddress`. Každé pole je voliteľné, rovnako ako každé pole adresy, takže fakturačná adresa môže obsahovať len PSČ a krajinu. | Pole | Limit alebo formát | | ------------------------ | ---------------------------------------------------------------------- | | `email` | E-mailová adresa, najviac 254 znakov. | | `name`, `line1`, `line2` | Každé najviac 200 znakov. | | `phone` | Najviac 30 znakov. | | `city`, `state` | Každé najviac 100 znakov. | | `postalCode` | Najviac 20 znakov. | | `country` | Dvojpísmenový kód krajiny podľa ISO veľkými písmenami, napríklad `CZ`. | Zadaný text adresy musí byť neprázdny. Neznáme polia môžete vynechať. Backend si zadané údaje o zákazníkovi ukladá ako snímku pre rizikové informácie platobnej brány. Údaje o zákazníkovi nie sú súčasťou odpovedí s reláciou. **Odpovede:** | Kód | Popis | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Relácia bola vytvorená, alebo bola pri opakovaní s rovnakým kľúčom, telom a režimom prihlasovacích údajov vrátená tá istá relácia s aktuálnym stavom | | `409` | Konflikt: kľúč bol znova použitý so zmeneným telom alebo režimom prihlasovacích údajov (`API-0025`), alebo je objednávka už zaplatená či pri nej prebieha platba | **Telo odpovede:** ```json { "id": "cs_7Hq2x9LmR4", "merchantOrderId": "order-1001", "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4", "status": "open", "paymentStatus": "unpaid", "amount": 12100, "currency": "EUR", "tax": 2100, "shipping": 605, "taxRate": 21, "taxBreakdown": [], "items": [], "expiresAt": "2026-07-15T12:30:00Z", "createdAt": "2026-07-15T12:00:00Z" } ``` `taxRate` je uvedená len vtedy, keď bola zadaná. Uložte `id` k objednávke a potom pošlite prehliadač na `url` s HTTP 303. Relácia prijíma nové platby počas 30 minút od vytvorenia; platba, ktorá už bola odoslaná, sa dokončí aj po tomto čase. Návratové URL sa vyberajú a overujú pri vytvorení, a to buď z hodnôt v požiadavke, alebo z predvolených hodnôt volajúceho prihlasovacieho údaja: [návratové ciele](/online/integration/checkout_settings#configure-return-destinations) organizácie pre Secret key organizácie s `X-Tapaya-Merchant-Token`, návratové ciele obchodníka pre checkout kľúč obchodníka. Tieto dve sady sa nikdy nekombinujú. ### Načítanie relácie [#retrieve-a-session] Keď sa zákazník vráti na vašu URL úspechu alebo zrušenia, alebo v rámci úlohy na odsúhlasenie, načítajte reláciu a pred vybavením objednávky ju porovnajte s uloženou objednávkou. **Endpoint:** `GET /merchant/checkout-sessions/{id}` cURL ```bash curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \ -H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ -H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" ``` Prípona `/status` neexistuje. Odpoveď obsahuje identitu relácie, URL, súčty, daňové polia, stavy a časové pečiatky a navyše `paymentReference` a `completedAt`, ktoré môžu byť null. `paymentReference` identifikuje posledný pokus o potvrdenie a je null, kým žiadny pokus neexistuje. Referencia, ktorá nie je null, nedokazuje úspech. Časové pečiatky sú reťazce vo formáte ISO 8601. **Stav relácie:** | `status` | Význam | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `open` | Relácia je k dispozícii na platbu, alebo sa výsledok odoslanej platby ešte potvrdzuje. | | `completed` | Relácia bola dokončená. Výsledok platby zistíte v `paymentStatus`. | | `expired` | Relácia už nie je k dispozícii na novú platbu: vypršala, alebo ju nahradila novšia relácia pre tú istú objednávku. | **Stav platby:** | `paymentStatus` | Význam pre objednávku | | --------------- | ------------------------------------------------------------------------------------------------- | | `unpaid` | Žiadna potvrdená úspešná platba. Výsledok sa ešte môže potvrdzovať. | | `successful` | Platba prebehla úspešne. Pred vybavením objednávky odsúhlaste referenciu objednávky, sumu a menu. | | `failed` | Platba bola zamietnutá. Kým je relácia otvorená, zákazník môže skúsiť inú kartu alebo peňaženku. | | `cancelled` | Platba bola zrušená. | | `action_needed` | Vyžaduje sa ďalšia akcia. Objednávku nevybavujte ako zaplatenú. | Zamietnutá karta ponechá `status` ako `open` a `paymentStatus` ako `failed`. Kým Tapaya na pozadí potvrdzuje neistý výsledok, relácia zostáva `open` a `unpaid`; načítajte ju znova neskôr. Kliknutie na odkaz na zrušenie na hostovanej stránke je len navigácia na `cancelUrl`; samo osebe nedokazuje stav platby `cancelled`. Objednávku vybavte, len keď načítaná relácia zodpovedá referencii, sume a mene vašej uloženej objednávky a `paymentStatus` je `successful`. Samotné presmerovanie prehliadača platbu nikdy nedokazuje.
## Vlastníctvo objednávky a platby [#order-and-payment-ownership] | Váš server vlastní | Tapaya vlastní | | -------------------------------------------------- | ----------------------------------------------------- | | Referenciu objednávky, ceny, menu a stav vybavenia | Reláciu Checkoutu a výsledok platby z platobnej brány | ID relácie Checkoutu identifikuje hostovaný Checkout. Pole `merchantOrderId` relácie ju prepája s vašou objednávkou, zatiaľ čo `paymentReference` identifikuje posledný pokus o potvrdenie. Ukladajte ID relácie k objednávke, aby ste mohli výsledok načítať, aj keď zákazník zatvorí prehliadač. Hostovaná stránka používa na načítanie a potvrdenie relácie samostatné verejné endpointy. ID relácie slúži pre tieto endpointy ako prístupový údaj. Integrácia obchodníka overuje platbu cez autentifikovaný endpoint pre obchodníkov. ### Jedna platba na objednávku [#one-payment-per-order] Hosted a [Embedded Checkout](/online/integration/embedded_checkout) zdieľajú jeden platobný systém. Obchodník môže mať na jedno `merchantOrderId` najviac jednu úspešnú platbu. ID objednávok platia v rámci obchodníka, takže rôzni obchodníci, aj v rámci jednej organizácie, môžu používať rovnaké ID. * Vytvorenie relácie pre nezaplatenú objednávku nahradí predchádzajúcu nezaplatenú reláciu. Stará URL hlási `expired` a už nemôže prijať platbu. * Vytvorenie relácie pre objednávku, ktorá je už zaplatená alebo pri ktorej prebieha platba, vráti HTTP 409. * Po zamietnutí môže zákazník v tej istej relácii skúsiť inú kartu alebo peňaženku. Opätovné odoslanie toho istého tokenu karty nikdy nezaťaží kartu dvakrát. * Tapaya určuje pravidlá pre 3-D Secure a vždy sa pokúsi o autentifikáciu. ## Idempotencia a chyby [#idempotency-and-errors] Vytvorenie vyžaduje neprázdny `Idempotency-Key` s dĺžkou najviac 250 znakov. Pre toho istého obchodníka platí: | Pošlete | Tapaya vráti | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | Rovnaký kľúč, telo a režim prihlasovacích údajov | Tú istú reláciu s jej aktuálnymi hodnotami `status` a `paymentStatus` | | Rovnaký kľúč so zmeneným telom | HTTP 409 s kódom `API-0025` | | Rovnaký kľúč a telo s druhým režimom prihlasovacích údajov | HTTP 409 s kódom `API-0025`, pretože každý režim používa vlastné nastavenia presmerovania | | Neplatné súčty, nepodporovanú menu, neplatné ciele presmerovania, chýbajúcu konfiguráciu platobnej brány alebo obchodníka, ktorý nie je pridaný do Checkoutu | Odmietnutie vytvorenia relácie | Zamietnutie karty je výsledok platby, nie dôkaz, že požiadavka HTTP zlyhala. Chyba siete alebo vypršanie časového limitu ponechá výsledok platby neznámy. Webhooky pre Checkout zatiaľ nie sú k dispozícii: odsúhlasujte načítaním relácie zo svojho servera a vytvorenie opakujte iba s rovnakým kľúčom a telom.