### Nastavte svůj server [#set-up-your-server] HTTP (fetch) Node.js SDK cURL Nastavte `TAPAYA_CHECKOUT_API_URL` na `https://api.sandbox.tapaya.com` a svůj klíč uložte do `TAPAYA_CHECKOUT_API_KEY`. API volejte pomocí `fetch` v serverovém běhovém prostředí, nikdy z prohlížeče zákazníka. Příklady čtou tyto hodnoty přes `process.env`; pokud vaše běhové prostředí používá jiné rozhraní pro tajné údaje, toto načítání upravte. Vytvořte pomocnou funkci, která před vrácením těla odpovědi zkontroluje chyby HTTP: ```js title="server/checkout.js" const apiUrl = process.env.TAPAYA_CHECKOUT_API_URL; const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY; async function checkoutRequest(path, options = {}) { const response = await fetch(new URL(path, apiUrl), { ...options, headers: { ...options.headers, Authorization: `Bearer ${apiKey}`, }, redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(8000), }); if (!response.ok) { throw new Error(`Checkout request failed (${response.status})`); } return response.json(); } ``` Použijte Node.js 22.13.0 nebo novější a nainstalujte na svůj server balíček ESM: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` Svůj klíč uložte do `TAPAYA_SECRET_KEY` a zvolte prostředí sandbox. SDK samo soubory `.env` nenačítá, proto tyto hodnoty načtěte do prostředí svého serveru ještě před vytvořením klienta. ```sh title=".env" TAPAYA_SECRET_KEY=tapaya_test_... TAPAYA_ENVIRONMENT=sandbox ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); // reads TAPAYA_SECRET_KEY ``` Bez `TAPAYA_ENVIRONMENT` klíč `tapaya_live_` zvolí produkční prostředí a ostatní klíče ve výchozím nastavení použijí sandbox. V režimu platformy předejte token obchodníka: `new Tapaya(key, { merchantToken })`, nebo `merchantToken` u každého volání. Pokud je váš klíč uložen pod jiným názvem, předejte jej jako první argument. [Referenční příručka Node.js SDK](/online/integration/node_sdk) popisuje vlastní URL API, časové limity, opakované pokusy a chyby. Tyto příkazy spouštějte ze svého serveru nebo z důvěryhodného terminálu. Načtěte svůj klíč do `TAPAYA_CHECKOUT_API_KEY`, nedávejte jej do kódu v prohlížeči ani do správy zdrojového kódu a nasměrujte URL API na sandbox: ```bash export TAPAYA_CHECKOUT_API_URL='https://api.sandbox.tapaya.com' ``` ### Vytvořte relaci [#create-a-session] Vypočítejte celkovou částku objednávky na svém serveru, včetně daně a dopravy. Objednávku a jedinečný `checkoutAttemptKey` uložte **před** odesláním požadavku a `order` načtěte z tohoto uloženého stavu. Pole `merchantOrderId` je povinné. HTTP (fetch) Node.js SDK cURL ```js const session = await checkoutRequest('/merchant/checkout-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': order.checkoutAttemptKey, }, body: JSON.stringify({ merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }), }); ``` ```ts const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` Příklad účtuje 121,00 EUR za `order-1001`, včetně 21,00 EUR DPH a 6,05 EUR za dopravu, s uloženým klíčem idempotence `order-1001-checkout-1`. Nahraďte tyto hodnoty údaji své uložené objednávky. ```bash curl --request POST \ "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "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" }' ``` Odpověď obsahuje `id` relace a hostovanou `url`. Souhrny položek, rozpisy daní, údaje o zákazníkovi a všechna pole odpovědi popisuje část [Vytvoření relace Checkoutu](/online/integration/api_integration#create-a-checkout-session). **Pokud požadavek selže nebo vyprší jeho časový limit,** zopakujte jej se stejným klíčem a nezměněným tělem. Při nejistém výsledku nikdy negenerujte nový klíč: změněné tělo se stejným klíčem vrátí HTTP 409. | Možnost | Automatické opakování | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP (fetch), cURL | Ne. Požadavek zopakujte sami. Viz [Idempotence a chyby](/online/integration/api_integration#idempotency-and-errors). | | Node.js SDK | Až dvakrát po chybě připojení, vypršení časového limitu nebo HTTP 429, 502, 503 či 504, se stejným klíčem a tělem. Viz [Idempotence a opakované pokusy](/online/integration/node_sdk#idempotency-and-retries). Mezi samostatnými voláními a po restartech předávejte svůj uložený klíč: pokud jej vynecháte, vygeneruje se pro každé volání nový. | ### Přesměrujte zákazníka [#redirect-the-customer] Uložte `session.id` k objednávce jako její `checkoutSessionId` a poté pošlete prohlížeč na `session.url` pomocí HTTP 303\. URL použijte beze změny, nesestavujte ji sami. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Pokud váš framework používá jiné API pro odpovědi, pošlete HTTP 303 se `session.url` v hlavičce `Location`. S cURL otevřete vrácenou `url` v prohlížeči a platbu otestujte ručně. ### Ověřte platbu [#verify-the-payment] V handleru návratové URL dohledejte objednávku z autentizovaného kontextu platby ve vaší aplikaci a načtěte její uloženou relaci ze svého serveru. Udělejte to i na URL pro zrušení: návštěva kterékoli z obou URL nic nedokazuje. HTTP (fetch) Node.js SDK cURL ```js const current = await checkoutRequest( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, ); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` ```ts const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` ID relace uložené s vaší objednávkou načtěte do `CHECKOUT_SESSION_ID`: ```bash curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/$CHECKOUT_SESSION_ID" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" ``` U ukázkové objednávky ověřte, že `id` odpovídá uloženému ID relace, `merchantOrderId` je `order-1001`, `amount` je `12100`, `currency` je `EUR` a `paymentStatus` je `successful`. Samotná odpověď HTTP 200 platbu nedokazuje. Platbu zaznamenejte a objednávku vyřiďte pouze tehdy, když relace odpovídá vaší uložené objednávce a `paymentStatus` je `successful`, a zaznamenejte ji atomicky, aby k tomu došlo jen jednou. Pokud načtení selže nebo výsledek platby ještě není rozhodnutý, ponechte si ID relace a stav ověřte znovu. Viz [Stav platby](/online/integration/api_integration#payment-status).