Predstavujeme Tapaya Checkout

Tapaya Checkout prináša do Tapaye online platby. Vaši obchodníci môžu prijímať karty, Apple Pay a Google Pay na akomkoľvek webe a vy si vyberiete, akú veľkú časť pokladne budete mať vo vlastných rukách.

• Hosted Checkout. Váš server vytvorí reláciu a presmeruje zákazníka na zabezpečenú platobnú stránku, ktorú hostuje Tapaya. Na front-ende nevyžaduje takmer žiadnu prácu.
• Embedded Checkout. Zabezpečené polia pre kartu a tlačidlá peňaženiek sú priamo vo vašej pokladni, vedľa vášho vlastného tlačidla Zaplatiť.

Obe varianty stoja na rovnakom modeli na strane servera: vytvoriť, presmerovať alebo vložiť, a pred vybavením objednávky overiť na serveri. Začať môžete ešte dnes v sandboxe na docs.tapaya.com.

Čo je Tapaya Checkout

Tapaya Checkout je online časť Tapaye. Prijíma pre vašich obchodníkov platby kartou, Apple Pay a Google Pay cez jedno API a jedno Node.js SDK. Myšlienka je rovnaká ako pri platbách na mieste: integrujete raz, zážitok obchodníka zostáva vo vašom produkte a všetku zložitosť platieb pod tým rieši Tapaya.

• Hosted Checkout vám dáva hotovú platobnú stránku na doméne Tapaye, na počítači aj na mobile.
• Embedded Checkout vám dáva zabezpečené polia, ktoré vložíte do vlastnej stránky. Údaje o karte zostávajú v rámci (iframe) Tapaye a na vašu stránku sa nikdy nedostanú.

Obe varianty stoja na rovnakých základoch: serverový kľúč, sumy v najmenších jednotkách meny (1880 teda znamená 18,80 EUR), idempotentné požiadavky a overenie na serveri. Keď postavíte jednu, väčšinu tej druhej už poznáte.

Hosted, alebo Embedded: ktorú variantu zvoliť

Ak si nie ste istí, začnite s Hosted Checkout. Prechod na Embedded neskôr využije rovnaké kľúče, rovnaký model objednávok aj rovnakú logiku overovania.

Hosted Checkout v piatich krokoch

1. Vytvorte reláciu na serveri. Zavolajte POST /merchant/checkout-sessions s merchantOrderId, amount (v najmenších jednotkách), currency, customer, successUrl a cancelUrl. Pošlite hlavičku Idempotency-Key.
2. Uložte ID relácie k objednávke.
3. Presmerujte prehliadač na session.url s HTTP 303. Použite URL presne tak, ako ju dostanete.
4. Zákazník zaplatí na hostovanej stránke. Zamietnutú kartu môže skúsiť znova na tej istej stránke. Relácie prijímajú platby 30 minút.
5. Overte na serveri. Keď sa zákazník vráti na ktorúkoľvek z návratových URL, zavolajte GET /merchant/checkout-sessions/{id}. Skontrolujte, že ID, ID objednávky, suma a mena zodpovedajú vašej objednávke, a objednávku vybavte, len keď je paymentStatus rovné successful.

S Node.js SDK (npm install @tapayadot/checkout, Node.js 22.13.0 alebo novší) vyzerá jadro 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šetky parametre nájdete v type CreateHostedCheckoutSessionParams a v návode k Hosted Checkout.

Embedded Checkout: zabezpečené polia vo vašej stránke

Embedded Checkout delí prácu medzi vašu stránku a malý endpoint prepare na vašom serveri. V prehliadači načítate Tapayu z @tapayadot/checkout/client a vložíte polia:

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šom serveri načíta objednávku a ak k nej už platba existuje, použije ju znova. Inak ju vytvorí cez POST /merchant/payments s idempotentným kľúčom. Potom vráti { clientSecret, status }. Aplikácie v Reacte môžu použiť usePayment() z @tapayadot/checkout/react.

Pár vecí, ktoré je dobré vedieť:

• Pridajte https://js.tapaya.com do script-src a frame-src vo vašej Content Security Policy.
• @tapayadot/checkout importujte len na serveri. Prehliadač používa vstupný bod /client.
• snapshot.outcome vám povie, čo zobraziť: open, pending, completed alebo ended.
• Tlačidlá peňaženiek sa zobrazia len tam, kde sú podporované a zapnuté. Apple Pay potrebuje aktívnu doménu obchodu a ostrý Google Pay potrebuje merchant ID.

Celý postup nájdete v návode k Embedded Checkout.

Postavené pre spoľahlivé integrácie

Platby zlyhávajú neporiadne: vyprší časový limit, zákazník zavrie záložku, opakovaná požiadavka príde dvakrát. Tapaya Checkout je postavený tak, aby ste zvládli každú z týchto situácií.

• Idempotentné kľúče pri každom vytvorení. Zopakujte požiadavku s rovnakým kľúčom a rovnakým telom a dostanete späť pôvodnú reláciu alebo platbu. Zmenené telo vráti HTTP 409.
• Vstavané opakovanie v Node.js SDK. V predvolenom stave skúša požiadavku znova dvakrát pri chybách spojenia, vypršaní časového limitu a HTTP 429, 502, 503 a 504, s náhodne rozloženým odstupom (jitter).
• Jedna platba na objednávku. Nová relácia pre tú istú objednávku ukončí tú predchádzajúcu. Zaplatenú objednávku alebo objednávku s rozpracovanou platbou systém odmietne.
• Webhooky a k tomu dopytovanie. Prihláste sa na odber udalostí relácií a nevyriešené relácie pre istotu ďalej priebežne kontrolujte.
• Najprv overiť, potom vybaviť, a to raz. Návšteva vašej úspešnej URL sama osebe nič nedokazuje. Stav vždy potvrďte na serveri a vybavenie objednávky zaznamenajte atomicky.

Pred spustením do ostrej prevádzky prejdite všetky výsledky s testovacími kartami v sandboxe a celý QA checklist.

Rýchlejší vývoj s MCP serverom dokumentácie Tapaya

Dokumentácia Tapaye má vlastný MCP server. Vaše AI nástroje na programovanie v ňom môžu počas vývoja prehľadávať návody a dohľadávať API endpointy bez toho, aby ste opustili editor. Funguje s Claude Code, Claude Desktop, Cursorom, VS Code, Codexom a akýmkoľvek ďalším MCP klientom. Je verejný a nepotrebuje API kľúč.

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

Nikdy nevolá ostré Tapaya API a nikdy nežiada o kľúče. Nastavenie pre jednotlivých klientov nájdete v MCP Setup.

Zo sandboxu do ostrej prevádzky

1. Zaregistrujte obchodníka so schopnosťou online platieb a počkajte, kým sa mu v Tapaya Platform v sekcii Checkout zobrazí stav Ready.
2. Pridajte svoj obchod medzi Allowed websites a nastavte predvolenú úspešnú a zrušovaciu URL.
3. Vyvíjajte v sandboxe s kľúčom tapaya_test_, ktorý držíte len na serveri.
4. Prepnite do produkcie: produkčný kľúč, TAPAYA_ENVIRONMENT=production a produkčné návratové URL.
5. Nastavte peňaženky pre ostrú prevádzku: doménu obchodu pre Apple Pay a merchant ID pre Google Pay.

Návod Quick Start vás prevedie od nuly k prvej platbe v sandboxe na niekoľkých volaniach servera.

Časté otázky

Aké platobné metódy Tapaya Checkout podporuje?

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

Prejdú údaje o karte mojím serverom alebo stránkou?

Nie. Pri Hosted Checkout zákazník platí na stránke Tapaye. Pri Embedded Checkout bežia polia pre kartu aj 3-D Secure vnútri rámca Tapaye a dáta karty sa na vašu stránku nikdy nedostanú.

Ako dlho platí relácia Hosted Checkout?

30 minút od vytvorenia. Platba odoslaná pred týmto limitom sa ešte dokončí. Ak je objednávka aj potom nezaplatená, vytvorte novú reláciu.

Existuje SDK?

Áno, @tapayadot/checkout pre Node.js 22.13.0 alebo novší. Pokrýva Hosted Checkout na serveri a navyše vstupné body pre prehliadač a React pre Embedded Checkout. Ostatné technológie môžu volať REST API priamo.

Môžu platformy prijímať platby pre mnohých obchodníkov?

Áno. Použite Secret key organizácie a s každou požiadavkou pošlite token obchodníka.

Začnite

Prečítajte si prehľad Online Payments na docs.tapaya.com, vytvorte si kľúč pre sandbox a prijmite ešte dnes prvú testovaciu platbu. Máte otázky k integrácii? Napíšte na developers@tapaya.com.