Rýchly štart

Vykonajte onboarding obchodníka

Dokončite onboarding obchodníka s funkciou online platieb, prípadne s online platbami aj platbami v predajni. Obchodník, ktorý používa iba Checkout, nepotrebuje terminál. Uveďte web obchodu a údaje o online podnikaní a počkajte na schválenie spracovateľom. Samotné vytvorenie záznamu obchodníka alebo API kľúča platby nesprístupní.

V Tapaya Platform otvorte Checkout. Obchodníci, ktorí žiadajú o online platby, sa zobrazujú automaticky, vrátane tých, ktorí čakajú na schválenie. Pokračujte, keď bude obchodník v stave Ready.

Otvorte Settings obchodníka. V časti Merchant API key redirects pridajte svoj obchod do Allowed websites a nastavte predvolené URL úspechu a zrušenia. Platforma, ktorá používa Secret key organizácie, ich namiesto toho nastavuje v Organization defaults. Príklady používajú https://shop.example. Peňaženky a branding opisuje stránka Nastavenia Checkoutu.

Uložte kľúč na server

V Settings obchodníka zvoľte Create merchant key a skopírujte kľúč tapaya_test_…. Zobrazí sa iba raz. Uchovávajte ho výhradne v konfigurácii na strane servera. Nikdy nepatrí do kódu v prehliadači ani do systému na správu verzií.

TAPAYA_ENVIRONMENT=sandbox
TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com
TAPAYA_SECRET_KEY=tapaya_test_...

SDK načítava TAPAYA_SECRET_KEY a TAPAYA_ENVIRONMENT automaticky. Nižšie uvedené príklady HTTP používajú TAPAYA_CHECKOUT_API_URL. Premenné načítajte do procesu svojho servera; SDK súbory .env nenačítava.

Kľúč posielajte ako Authorization: Bearer <key>. Kľúč obchodníka určuje svojho obchodníka, takže nie je potrebná žiadna ďalšia hlavička. Platforma, ktorá obsluhuje mnoho obchodníkov, namiesto toho používa Secret key organizácie a v každej požiadavke posiela X-Tapaya-Merchant-Token. Pozrite si autentifikáciu Checkoutu.

Vytvorte reláciu Checkoutu

Keď zákazník vo vašom obchode klikne na Checkout, vypočítajte konečnú celkovú sumu na svojom serveri, uložte objednávku s jedinečným kľúčom pokusu a vytvorte reláciu. Pole merchantOrderId je povinné a objednávku možno zaplatiť iba raz. Sumy sú v najmenších jednotkách meny, takže 12100 znamená 121,00 EUR.

Pre Node.js 22.13.0 alebo novší nainštalujte ESM SDK skôr, ako použijete prí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();

Ak vyprší časový limit požiadavky, zopakujte ju s rovnakým kľúčom a telom. API vráti pôvodnú reláciu namiesto toho, aby vytvorilo druhú.

Presmerujte zákazníka

Uložte session.id k objednávke a potom pošlite prehliadač na session.url pomocou HTTP 303. URL použite presne tak, ako bola vrátená.

// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);

Tapaya zobrazí súhrn objednávky a zabezpečený platobný formulár a zabezpečí tokenizáciu, 3-D Secure aj samotné zaťaženie karty. Po zamietnutí môže zákazník na tej istej stránke skúsiť inú kartu. Relácie prijímajú nové platby počas 30 minút.

Overte platbu na svojom serveri

Keď zákazník príde na vašu URL úspechu alebo zrušenia, načítajte reláciu pomocou svojho Secret key a porovnajte ju s uloženou objednávkou. Samotné presmerovanie 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();

Pri oboch integráciách porovnajte výsledok s uloženou objednávkou skôr, ako ju vybaví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
}

Ak je stav stále unpaid alebo načítanie zlyhá, ponechajte si ID relácie a stav skontrolujte znova. Webhooky zatiaľ nie sú k dispozícii, preto spúšťajte úlohu na odsúhlasenie platieb pre zákazníkov, ktorí zatvoria kartu prehliadača skôr, ako sa vrátia.