### Proveďte onboarding obchodníka [#onboard-your-merchant] Dokončete [onboarding obchodníka](/merchants/onboarding) s funkcí online plateb, případně s online platbami i platbami v prodejně. Obchodník, který používá pouze Checkout, nepotřebuje terminál. Uveďte web obchodu a údaje o online podnikání a počkejte na schválení zpracovatelem. Samotné vytvoření záznamu obchodníka nebo API klíče platby nezpřístupní. V [Tapaya Platform](https://platform.tapaya.com/checkout-settings) otevřete **Checkout**. Obchodníci, kteří žádají o online platby, se zobrazují automaticky, včetně těch, kteří čekají na schválení. Pokračujte, jakmile bude obchodník ve stavu **Ready**. Otevřete **Settings** obchodníka. V části **Merchant API key redirects** přidejte svůj obchod do **Allowed websites** a nastavte výchozí URL pro úspěch a zrušení. Platforma, která používá Secret key organizace, je místo toho nastavuje v **Organization defaults**. Příklady používají `https://shop.example`. Peněženky a branding popisuje stránka [Nastavení Checkoutu](/online/integration/checkout_settings). ### Uložte klíč na server [#store-your-key-on-the-server] V **Settings** obchodníka zvolte **Create merchant key** a zkopírujte klíč `tapaya_test_…`. Zobrazí se pouze jednou. Uchovávejte jej výhradně v konfiguraci na straně serveru. Nikdy nepatří do kódu v prohlížeči ani do systému správy verzí. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` SDK načítá `TAPAYA_SECRET_KEY` a `TAPAYA_ENVIRONMENT` automaticky. Níže uvedené příklady HTTP používají `TAPAYA_CHECKOUT_API_URL`. Proměnné načtěte do procesu svého serveru; SDK soubory `.env` nenačítá. Klíč posílejte jako `Authorization: Bearer `. Klíč obchodníka určuje svého obchodníka, takže není potřeba žádná další hlavička. Platforma, která obsluhuje mnoho obchodníků, místo toho používá Secret key organizace a v každém požadavku posílá `X-Tapaya-Merchant-Token`. Viz [autentizace Checkoutu](/online/integration/api_integration#authentication). ### Vytvořte relaci Checkoutu [#create-a-checkout-session] Když zákazník ve vašem obchodě klikne na **Checkout**, vypočítejte konečnou celkovou částku na svém serveru, uložte objednávku s jedinečným klíčem pokusu a vytvořte relaci. Pole `merchantOrderId` je povinné a objednávku lze zaplatit pouze jednou. Částky jsou v nejmenších jednotkách měny, takže `12100` znamená 121,00 EUR. Pro Node.js 22.13.0 nebo novější nainstalujte ESM SDK, než použijete příklad **Node.js SDK**: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, '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', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); 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 }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Pokud vyprší časový limit požadavku, zopakujte jej se **stejným** klíčem a tělem. API vrátí původní relaci, místo aby vytvořilo druhou. ### Přesměrujte zákazníka [#redirect-the-customer] Uložte `session.id` k objednávce a poté pošlete prohlížeč na `session.url` pomocí HTTP 303. URL použijte přesně tak, jak byla vrácena. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya zobrazí souhrn objednávky a zabezpečený platební formulář a zajistí tokenizaci, 3-D Secure i zatížení karty. Po zamítnutí může zákazník na stejné stránce zkusit jinou kartu. Relace přijímají nové platby po dobu 30 minut. ### Ověřte platbu na svém serveru [#verify-the-payment-on-your-server] Když zákazník dorazí na vaši URL pro úspěch nebo zrušení, načtěte relaci pomocí svého Secret key a porovnejte ji s uloženou objednávkou. Samotné přesměrování platbu nikdy nedokazuje. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` U obou integrací porovnejte výsledek s uloženou objednávkou dříve, než ji vyřídíte: ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Pokud je stav stále `unpaid` nebo načtení selže, ponechte si ID relace a stav zkontrolujte znovu. Webhooky zatím nejsou k dispozici, proto spouštějte úlohu pro odsouhlasení plateb pro zákazníky, kteří zavřou kartu prohlížeče dříve, než se vrátí.