Rychlý start

Proveďte onboarding obchodníka

Dokončete onboarding obchodníka 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 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.

Uložte klíč na 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í.

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 <key>. 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.

Vytvořte relaci Checkoutu

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 install @tapayadot/checkout

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();

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

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.

// 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

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.

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();

U obou integrací porovnejte výsledek s uloženou objednávkou dříve, než ji vyřídíte:

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í.