Představujeme Tapaya Checkout

Tapaya Checkout přináší do Tapaye online platby. Vaši obchodníci mohou přijímat karty, Apple Pay a Google Pay na jakémkoli webu a vy si vyberete, jak velkou část pokladny budete mít ve vlastních rukou.

• Hosted Checkout. Váš server vytvoří relaci a přesměruje zákazníka na zabezpečenou platební stránku, kterou hostuje Tapaya. Na front-endu nevyžaduje téměř žádnou práci.
• Embedded Checkout. Zabezpečená pole pro kartu a tlačítka peněženek jsou přímo ve vaší pokladně, vedle vašeho vlastního tlačítka Zaplatit.

Obě varianty stojí na stejném modelu na straně serveru: vytvořit, přesměrovat nebo vložit, a před vyřízením objednávky ověřit na serveru. Začít můžete ještě dnes v sandboxu na docs.tapaya.com.

Co je Tapaya Checkout

Tapaya Checkout je online část Tapaye. Přijímá pro vaše obchodníky platby kartou, Apple Pay a Google Pay přes jedno API a jedno Node.js SDK. Myšlenka je stejná jako u plateb na místě: integrujete jednou, zážitek obchodníka zůstává ve vašem produktu a veškerou složitost plateb pod tím řeší Tapaya.

• Hosted Checkout vám dává hotovou platební stránku na doméně Tapaye, na počítači i na mobilu.
• Embedded Checkout vám dává zabezpečená pole, která vložíte do vlastní stránky. Údaje o kartě zůstávají v rámci (iframe) Tapaye a na vaši stránku se nikdy nedostanou.

Obě varianty stojí na stejných základech: serverový klíč, částky v nejmenších jednotkách měny (1880 tedy znamená 18,80 EUR), idempotentní požadavky a ověření na serveru. Když postavíte jednu, většinu té druhé už znáte.

Hosted, nebo Embedded: kterou variantu zvolit

Pokud si nejste jistí, začněte s Hosted Checkout. Přechod na Embedded později využije stejné klíče, stejný model objednávek i stejnou logiku ověřování.

Hosted Checkout v pěti krocích

1. Vytvořte relaci na serveru. Zavolejte POST /merchant/checkout-sessions s merchantOrderId, amount (v nejmenších jednotkách), currency, customer, successUrl a cancelUrl. Pošlete hlavičku Idempotency-Key.
2. Uložte ID relace k objednávce.
3. Přesměrujte prohlížeč na session.url s HTTP 303. Použijte URL přesně tak, jak ji dostanete.
4. Zákazník zaplatí na hostované stránce. Zamítnutou kartu může zkusit znovu na stejné stránce. Relace přijímají platby 30 minut.
5. Ověřte na serveru. Když se zákazník vrátí na kteroukoli z návratových URL, zavolejte GET /merchant/checkout-sessions/{id}. Zkontrolujte, že ID, ID objednávky, částka a měna odpovídají vaší objednávce, a objednávku vyřiďte, jen když je paymentStatus rovno successful.

S Node.js SDK (npm install @tapayadot/checkout, Node.js 22.13.0 nebo novější) vypadá jádro takto:

import { Tapaya } from '@tapayadot/checkout'

// Reads TAPAYA_SECRET_KEY from the server environment.
const tapaya = new Tapaya()

// 1–3. Create the session and redirect the customer
const session = await tapaya.checkout.sessions.create(params, { idempotencyKey })
return Response.redirect(session.url, 303)

// 5. Later, on the return URL: verify before you fulfil
const current = await tapaya.checkout.sessions.get(sessionId)

Všechny parametry najdete v typu CreateHostedCheckoutSessionParams a v návodu k Hosted Checkout.

Embedded Checkout: zabezpečená pole ve vaší stránce

Embedded Checkout dělí práci mezi vaši stránku a malý endpoint prepare na vašem serveru. V prohlížeči načtete Tapayu z @tapayadot/checkout/client a vložíte pole:

import { loadTapaya } from '@tapayadot/checkout/client'

const tapaya = await loadTapaya(publishableKey, { apiOrigin })
const payment = tapaya.createPayment({
  prepare: '/api/payments', // your server endpoint
  wallets: { amount: 1880, currency: 'EUR' },
  onChange: (snapshot) => { /* enable Pay when snapshot.canSubmit */ },
})
payment.mount('#card-fields')

// In your form handler:
await payment.submit() // validates, runs 3-D Secure, confirms

Endpoint prepare na vašem serveru načte objednávku a pokud už k ní platba existuje, použije ji znovu. Jinak ji vytvoří přes POST /merchant/payments s idempotentním klíčem. Pak vrátí { clientSecret, status }. Aplikace v Reactu mohou použít usePayment() z @tapayadot/checkout/react.

Pár věcí, které je dobré vědět:

• Přidejte https://js.tapaya.com do script-src a frame-src ve vaší Content Security Policy.
• @tapayadot/checkout importujte jen na serveru. Prohlížeč používá vstupní bod /client.
• snapshot.outcome vám řekne, co zobrazit: open, pending, completed nebo ended.
• Tlačítka peněženek se zobrazí jen tam, kde jsou podporovaná a zapnutá. Apple Pay potřebuje aktivní doménu obchodu a ostrý Google Pay potřebuje merchant ID.

Celý postup najdete v návodu k Embedded Checkout.

Postaveno pro spolehlivé integrace

Platby selhávají nepořádně: vyprší časový limit, zákazník zavře záložku, opakovaný požadavek dorazí dvakrát. Tapaya Checkout je postavený tak, abyste zvládli každou z těchto situací.

• Idempotentní klíče u každého vytvoření. Zopakujte požadavek se stejným klíčem a stejným tělem a dostanete zpět původní relaci nebo platbu. Změněné tělo vrátí HTTP 409.
• Vestavěné opakování v Node.js SDK. Ve výchozím stavu zkouší požadavek znovu dvakrát při chybách spojení, vypršení časového limitu a HTTP 429, 502, 503 a 504, s náhodně rozloženým odstupem (jitter).
• Jedna platba na objednávku. Nová relace pro stejnou objednávku ukončí tu předchozí. Zaplacenou objednávku nebo objednávku s rozpracovanou platbou systém odmítne.
• Webhooky a k tomu dotazování. Přihlaste se k odběru událostí relací a nevyřešené relace pro jistotu dál průběžně kontrolujte.
• Nejdřív ověřit, pak vyřídit, a to jednou. Návštěva vaší úspěšné URL sama o sobě nic nedokazuje. Stav vždy potvrďte na serveru a vyřízení objednávky zaznamenejte atomicky.

Před spuštěním do ostrého provozu projděte všechny výsledky s testovacími kartami v sandboxu a celý QA checklist.

Rychlejší vývoj s MCP serverem dokumentace Tapaya

Dokumentace Tapaye má vlastní MCP server. Vaše AI nástroje pro programování v něm mohou během vývoje prohledávat návody a dohledávat API endpointy, aniž byste opustili editor. Funguje s Claude Code, Claude Desktop, Cursorem, VS Code, Codexem a jakýmkoli dalším MCP klientem. Je veřejný a nepotřebuje API klíč.

claude mcp add --transport http tapaya-docs https://docs.tapaya.com/mcp

Nikdy nevolá ostré Tapaya API a nikdy nežádá o klíče. Nastavení pro jednotlivé klienty najdete v MCP Setup.

Ze sandboxu do ostrého provozu

1. Zaregistrujte obchodníka se schopností online plateb a počkejte, až se mu v Tapaya Platform v sekci Checkout zobrazí stav Ready.
2. Přidejte svůj obchod mezi Allowed websites a nastavte výchozí úspěšnou a zrušovací URL.
3. Vyvíjejte v sandboxu s klíčem tapaya_test_, který držíte jen na serveru.
4. Přepněte do produkce: produkční klíč, TAPAYA_ENVIRONMENT=production a produkční návratové URL.
5. Nastavte peněženky pro ostrý provoz: doménu obchodu pro Apple Pay a merchant ID pro Google Pay.

Návod Quick Start vás provede od nuly k první platbě v sandboxu na několika voláních serveru.

Časté otázky

Jaké platební metody Tapaya Checkout podporuje?

Karty, Apple Pay a Google Pay, v Hosted i Embedded Checkout.

Projdou údaje o kartě mým serverem nebo stránkou?

Ne. U Hosted Checkout zákazník platí na stránce Tapaye. U Embedded Checkout běží pole pro kartu i 3-D Secure uvnitř rámce Tapaye a data karty se na vaši stránku nikdy nedostanou.

Jak dlouho platí relace Hosted Checkout?

30 minut od vytvoření. Platba odeslaná před tímto limitem se ještě dokončí. Pokud je objednávka i potom nezaplacená, vytvořte novou relaci.

Existuje SDK?

Ano, @tapayadot/checkout pro Node.js 22.13.0 nebo novější. Pokrývá Hosted Checkout na serveru a navíc vstupní body pro prohlížeč a React pro Embedded Checkout. Ostatní technologie mohou volat REST API přímo.

Mohou platformy přijímat platby pro mnoho obchodníků?

Ano. Použijte Secret key organizace a s každým požadavkem pošlete token obchodníka.

Začněte

Přečtěte si přehled Online Payments na docs.tapaya.com, vytvořte si klíč pro sandbox a přijměte ještě dnes první testovací platbu. Máte otázky k integraci? Napište na developers@tapaya.com.