# Integrace přes API (/cs/online/integration/api_integration) Váš backend vytvoří pro každou objednávku relaci Checkoutu a načte ji, aby ověřil platbu. Pro Node.js poskytuje [SDK `@tapayadot/checkout`](/online/integration/node_sdk) pro tyto endpointy typované metody `create()` a `get()`. Ve výchozím nastavení načítá `TAPAYA_SECRET_KEY`. Příklady HTTP na této stránce předávají `TAPAYA_CHECKOUT_API_KEY` explicitně. ## Autentizace [#authentication] Každé volání Checkoutu probíhá mezi servery a odesílá klíč jako bearer token: ```http Authorization: Bearer ``` Zvolte režim podle toho, kdo backend provozuje. Oba typy klíčů uchovávejte na svém serveru; viz [Zabezpečení Checkoutu](/online/security/checkout_security). ### Režim obchodníka [#merchant-mode] Tento režim použijte, když backend obsluhuje jeden obchod. V [Nastavení Checkoutu](/online/integration/checkout_settings#create-merchant-checkout-keys) vytvořte **Checkout klíč obchodníka**: otevřete obchodníka a zvolte **Create merchant key**. Klíč začíná na `tapaya_test_` v sandboxu nebo `tapaya_live_` v produkci a odkazuje právě na tohoto obchodníka. ```http Authorization: Bearer ``` `X-Tapaya-Merchant-Token` je v tomto režimu volitelný. Pokud jej odešlete, musí označovat stejného obchodníka. Tapaya Platform zobrazí klíč jen jednou a ukládá pouze jeho hash. Při rotaci klíče nejprve vytvořte náhradní klíč a teprve potom zrušte starý. Zrušení klíče neovlivní ostatní klíče obchodníků, klíče organizace ani client secret, které už byly vydány prohlížečům. ### Režim platformy [#platform-mode] Tento režim použijte, když jeden backend jedná za mnoho obchodníků, například jako tržiště nebo platforma pro rozvoz jídla. V **každém** požadavku odešlete Secret key organizace ze [stránky API Keys](https://platform.tapaya.com/api-keys/) a token obchodníka: ```http Authorization: Bearer X-Tapaya-Merchant-Token: ``` Žádný výchozí obchodník neexistuje. Požadavek bez této hlavičky vrátí HTTP 401. Obchodník musí patřit do organizace daného klíče. Tokeny obchodníků zkopírujte z tabulky obchodníků v [Nastavení Checkoutu](/online/integration/checkout_settings). Token identifikuje obchodníka; není tajný. Secret key organizace je tentýž přihlašovací údaj, který [dokumentace Platform API](/platform-api#authentication) nazývá Server Secret Token. Checkout vyžaduje předponu `Bearer`. Ostatní endpointy Platform API přijímají token přímo. Onboarding obchodníků a správa organizace probíhají přes [Platform API](/platform-api). Těla požadavků nepřijímají `merchantId`. ## Prostředí [#environments] | Prostředí | Origin API | Origin Hosted Checkoutu | Přihlašovací údaje | | --------- | -------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- | | Sandbox | `https://api.sandbox.tapaya.com` | `https://checkout.sandbox.tapaya.com` | Sandboxové klíče s [testovacími kartami](/online/getting-started/testing) | | Produkce | `https://api.tapaya.com` | `https://checkout.tapaya.com` | Ostré klíče se skutečnými platebními metodami | Nastavte `TAPAYA_CHECKOUT_API_URL` na origin API pro vaše prostředí. V produkci jsou k dispozici hostované i embedded platby. Každý obchodník musí projít [onboardingem](/merchants/onboarding), získat od zpracovatele plateb schválení pro online platby a mít nakonfigurovanou platební bránu. Připravenost obchodníka zkontrolujete v [Nastavení Checkoutu](/online/integration/checkout_settings). Vrácenou URL hostované relace používejte beze změny. ## Relace Checkoutu [#checkout-sessions]
### Vytvoření relace Checkoutu [#create-a-checkout-session] Relaci vytvořte, když zákazník ve vašem obchodě klikne na **Checkout**, a pak jej přesměrujte na vrácenou `url`. Nejprve na svém serveru spočítejte konečnou celkovou částku a uložte objednávku s jedinečným idempotency key (klíčem idempotence). **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 klíč obchodníka nebo Secret key organizace. | | `X-Tapaya-Merchant-Token` | Režim platformy | Token obchodníka patřícího do organizace daného klíče. S Checkout klíčem obchodníka je volitelný. | | `Idempotency-Key` | ✓ | Neprázdný, nejvýše 250 znaků. Viz [Idempotence a chyby](#idempotency-and-errors). | **Parametry:** | Pole | Typ | Povinné | Popis | | ----------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `merchantOrderId` | `string` | ✓ | Vaše označení objednávky, 1 až 200 znaků. Viz [Jedna platba na objednávku](#one-payment-per-order). | | `amount` | `integer` | ✓ | Konečná účtovaná částka v nejmenších jednotkách měny, včetně daně a dopravy. 1 až 2 147 483 647. | | `currency` | `string` | ✓ | Třípísmenný kód podle ISO 4217 podporovaný backendem, velkými písmeny, například `EUR`. | | `locale` | `string` | | Výchozí hodnota je `en`. | | `successUrl` | `string` | | Přepíše výchozí URL pro úspěch pro tuto relaci. Musí odpovídat povolenému webu volajícího přihlašovacího údaje. | | `cancelUrl` | `string` | | Přepíše výchozí URL pro zrušení pro tuto relaci. Musí odpovídat povolenému webu volajícího přihlašovacího údaje. | | `tax` | `integer` | | DPH již zahrnutá v `amount`, v rozmezí od nuly do `amount`. Výchozí hodnota je `0`. | | `shipping` | `integer` | | Doprava již zahrnutá v `amount`, v rozmezí od nuly do `amount`. Výchozí hodnota je `0`. | | `taxRate` | `number` | | Sazba DPH v procentech pro celou objednávku, například `21` nebo `5.5`. Nezáporná. | | `taxBreakdown` | `array` | | DPH seskupená podle sazeb. Neprázdné pole nelze použít současně s `taxRate`. | | `items` | `array` | | Položky objednávky jen pro zobrazení. Neurčují účtovanou částku. | | `customer` | `object` | | E-mail, fakturační adresa a doručovací adresa zákazníka. | Relace účtuje v měně `currency`, kterou nastavíte. Stránka [Podporované měny](/merchants/supported_currencies) uvádí všechny měny, které Tapaya podporuje, obchodník však má obvykle povolené jen některé z nich. Vytvoření relace v měně, kterou obchodník nebo backend nepodporuje, je odmítnuto, takže se nevytvoří žádná hostovaná stránka. API účtuje částku `amount` přesně tak, jak je zadána. Nepřičítá dopravu ani daň, nepočítá DPH ze sazby ani nepočítá celkovou částku z položek. Každá položka obsahuje číselnou `taxRate` a celočíselnou `tax`, obě nezáporné. Sazby jsou jedinečné a částky daně jednotlivých položek dávají v součtu `tax` na nejvyšší ú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á pole jsou neprázdná, `imageUrl` je URL, `quantity` je kladné celé číslo a `unitAmount` je nezáporné celé číslo v nejmenších jednotkách měny. Objekt `customer` přijímá `email`, `billingAddress` a `shippingAddress`. Každé pole je volitelné, stejně jako každé pole adresy, takže fakturační adresa může obsahovat jen PSČ a zemi. | Pole | Limit nebo formát | | ------------------------ | ---------------------------------------------------------------- | | `email` | E-mailová adresa, nejvýše 254 znaků. | | `name`, `line1`, `line2` | Každé nejvýše 200 znaků. | | `phone` | Nejvýše 30 znaků. | | `city`, `state` | Každé nejvýše 100 znaků. | | `postalCode` | Nejvýše 20 znaků. | | `country` | Dvoupísmenný kód země podle ISO velkými písmeny, například `CZ`. | Zadaný text adresy musí být neprázdný. Pole, jejichž hodnoty neznáte, můžete vynechat. Backend si zadané údaje o zákazníkovi ukládá jako snímek pro rizikové informace platební brány. Údaje o zákazníkovi nejsou součástí odpovědí s relací. **Odpovědi:** | Kód | Popis | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Relace byla vytvořena, nebo byla při opakování se stejným klíčem, tělem a režimem přihlašovacích údajů vrácena stejná relace s aktuálním stavem | | `409` | Konflikt: klíč byl znovu použit se změněným tělem nebo režimem přihlašovacích údajů (`API-0025`), nebo je objednávka již zaplacená či u ní probíhá platba | **Tělo odpovědi:** ```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 uvedena jen tehdy, když byla zadána. Uložte `id` k objednávce a pak prohlížeč pošlete na `url` s HTTP 303. Relace přijímá nové platby po dobu 30 minut od vytvoření; platba, která už byla odeslána, se dokončí i po této době. Návratové URL se vybírají a ověřují při vytvoření, a to buď z hodnot v požadavku, nebo z výchozích hodnot volajícího přihlašovacího údaje: [návratové cíle](/online/integration/checkout_settings#configure-return-destinations) organizace pro Secret key organizace s `X-Tapaya-Merchant-Token`, návratové cíle obchodníka pro Checkout klíč obchodníka. Tyto dvě sady se nikdy nekombinují. ### Načtení relace [#retrieve-a-session] Když se zákazník vrátí na vaši URL pro úspěch nebo zrušení, nebo v rámci úlohy pro odsouhlasení, načtěte relaci a před vyřízením objednávky ji porovnejte 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" ``` Přípona `/status` neexistuje. Odpověď obsahuje identitu relace, URL, součty, daňová pole, stavy a časová razítka a navíc `paymentReference` a `completedAt`, které mohou být null. `paymentReference` identifikuje poslední pokus o potvrzení a je null, dokud žádný pokus neexistuje. Reference, která není null, neprokazuje úspěch. Časová razítka jsou řetězce ve formátu ISO 8601. **Stav relace:** | `status` | Význam | | ----------- | --------------------------------------------------------------------------------------------------------------- | | `open` | Relace je k dispozici pro platbu, nebo se výsledek odeslané platby ještě potvrzuje. | | `completed` | Relace byla dokončena. Výsledek platby zjistíte v `paymentStatus`. | | `expired` | Relace už není k dispozici pro novou platbu: vypršela, nebo ji nahradila novější relace pro stejnou objednávku. | **Stav platby:** | `paymentStatus` | Význam pro objednávku | | --------------- | -------------------------------------------------------------------------------------------------- | | `unpaid` | Žádná potvrzená úspěšná platba. Výsledek se může ještě potvrzovat. | | `successful` | Platba proběhla úspěšně. Před vyřízením objednávky odsouhlaste označení objednávky, částku a měnu. | | `failed` | Platba byla zamítnuta. Dokud je relace otevřená, zákazník může zkusit jinou kartu nebo peněženku. | | `cancelled` | Platba byla zrušena. | | `action_needed` | Je vyžadována další akce. Objednávku nevyřizujte jako zaplacenou. | Zamítnutá karta ponechá `status` jako `open` a `paymentStatus` jako `failed`. Zatímco Tapaya na pozadí potvrzuje nejistý výsledek, relace zůstává `open` a `unpaid`; načtěte ji znovu později. Kliknutí na odkaz pro zrušení na hostované stránce je jen navigace na `cancelUrl`; samo o sobě neprokazuje stav platby `cancelled`. Objednávku vyřiďte, jen když načtená relace odpovídá označení, částce a měně vaší uložené objednávky a `paymentStatus` je `successful`. Samotné přesměrování prohlížeče platbu nikdy neprokazuje.
## Vlastnictví objednávky a platby [#order-and-payment-ownership] | Váš server vlastní | Tapaya vlastní | | ----------------------------------------------- | --------------------------------------------------- | | Označení objednávky, ceny, měnu a stav vyřízení | Relaci Checkoutu a výsledek platby z platební brány | ID relace Checkoutu identifikuje hostovaný Checkout. Pole `merchantOrderId` relace ji propojuje s vaší objednávkou, zatímco `paymentReference` identifikuje poslední pokus o potvrzení. Ukládejte ID relace k objednávce, abyste mohli výsledek načíst, i když zákazník zavře prohlížeč. Hostovaná stránka používá k načtení a potvrzení relace samostatné veřejné endpointy. ID relace slouží pro tyto endpointy jako přístupový údaj. Integrace obchodníka ověřuje platbu přes autentizovaný endpoint pro obchodníky. ### Jedna platba na objednávku [#one-payment-per-order] Hosted a [Embedded Checkout](/online/integration/embedded_checkout) sdílejí jeden platební systém. Obchodník může mít na jedno `merchantOrderId` nejvýše jednu úspěšnou platbu. ID objednávek platí v rámci obchodníka, takže různí obchodníci, i v rámci jedné organizace, mohou používat stejná ID. * Vytvoření relace pro nezaplacenou objednávku nahradí předchozí nezaplacenou relaci. Stará URL hlásí `expired` a už nemůže přijmout platbu. * Vytvoření relace pro objednávku, která je už zaplacená nebo u které probíhá platba, vrátí HTTP 409. * Po zamítnutí může zákazník ve stejné relaci zkusit jinou kartu nebo peněženku. Opětovné odeslání stejného tokenu karty nikdy nezaúčtuje platbu dvakrát. * Tapaya určuje pravidla pro 3-D Secure a vždy se pokusí o autentizaci. ## Idempotence a chyby [#idempotency-and-errors] Vytvoření vyžaduje neprázdný `Idempotency-Key` o délce nejvýše 250 znaků. Pro stejného obchodníka platí: | Odešlete | Tapaya vrátí | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | Stejný klíč, tělo a režim přihlašovacích údajů | Stejnou relaci s jejími aktuálními hodnotami `status` a `paymentStatus` | | Stejný klíč se změněným tělem | HTTP 409 s kódem `API-0025` | | Stejný klíč a tělo s druhým režimem přihlašovacích údajů | HTTP 409 s kódem `API-0025`, protože každý režim používá vlastní nastavení přesměrování | | Neplatné součty, nepodporovanou měnu, neplatné cíle přesměrování, chybějící konfiguraci platební brány nebo obchodníka, který není přidán do Checkoutu | Odmítnutí vytvoření relace | Zamítnutí karty je výsledek platby, nikoli důkaz, že požadavek HTTP selhal. Chyba sítě nebo vypršení časového limitu ponechá výsledek platby neznámý. Webhooky pro Checkout zatím nejsou k dispozici: odsouhlasujte načtením relace ze svého serveru a vytvoření opakujte pouze se stejným klíčem a tělem.