Швидкий старт

Проведіть онбординг мерчанта

Пройдіть онбординг мерчанта з можливістю онлайн-платежів або одночасно онлайн-платежів і платежів у торговій точці. Мерчанту, який використовує лише Checkout, термінал не потрібен. Надайте адресу вебсайту магазину та відомості про онлайн-бізнес і дочекайтеся схвалення платіжного процесора. Саме лише створення запису мерчанта чи API-ключа не вмикає платежі.

Відкрийте Checkout у Tapaya Platform. Мерчанти, які запитують онлайн-платежі, з'являються автоматично, зокрема ті, що очікують схвалення. Продовжуйте, коли мерчант матиме статус Ready.

Відкрийте Settings мерчанта. У розділі Merchant API key redirects додайте свій магазин до Allowed websites і задайте типові URL успіху та скасування. Платформа, яка використовує Secret key організації, натомість задає їх в Organization defaults. У прикладах використовується https://shop.example. Про гаманці та брендинг див. Налаштування Checkout.

Збережіть ключ на сервері

У Settings мерчанта виберіть Create merchant key і скопіюйте ключ tapaya_test_…. Він показується лише один раз. Зберігайте його тільки в серверній конфігурації. Йому ніколи не місце в коді браузера чи системі контролю версій.

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

SDK автоматично зчитує TAPAYA_SECRET_KEY і TAPAYA_ENVIRONMENT. Наведені нижче HTTP-приклади використовують TAPAYA_CHECKOUT_API_URL. Завантажте змінні в процес свого сервера; SDK не завантажує файли .env.

Надсилайте ключ як Authorization: Bearer <key>. Ключ мерчанта сам визначає свого мерчанта, тому інші заголовки не потрібні. Платформа, яка обслуговує багато мерчантів, натомість використовує Secret key організації та надсилає X-Tapaya-Merchant-Token у кожному запиті. Див. автентифікацію Checkout.

Створіть сесію Checkout

Коли клієнт натискає Checkout у вашому магазині, обчисліть остаточну суму на своєму сервері, збережіть замовлення з унікальним ключем спроби та створіть сесію. Поле merchantOrderId обов'язкове, а замовлення можна оплатити лише один раз. Суми вказуються в мінімальних одиницях валюти, тож 12100 означає 121,00 EUR.

Для Node.js 22.13.0 або новішої версії встановіть ESM SDK, перш ніж використовувати приклад 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();

Якщо запит завершився тайм-аутом, повторіть його з тим самим ключем і тілом. API повертає початкову сесію замість того, щоб створювати другу.

Переспрямуйте клієнта

Збережіть session.id разом із замовленням, а потім переспрямуйте браузер на session.url за допомогою HTTP 303. Використовуйте URL точно в тому вигляді, у якому його повернуто.

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

Tapaya показує підсумок замовлення та захищену платіжну форму, а також виконує токенізацію, 3-D Secure і стягнення оплати. Після відмови клієнт може спробувати іншу картку на тій самій сторінці. Сесії приймають нові платежі протягом 30 хвилин.

Перевірте платіж на своєму сервері

Коли клієнт потрапляє на ваш URL успіху або скасування, отримайте сесію за допомогою свого Secret key і порівняйте її зі збереженим замовленням. Саме лише переспрямування ніколи не доводить оплату.

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

Для обох інтеграцій порівняйте результат зі збереженим замовленням, перш ніж його виконувати:

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
}

Якщо статус усе ще unpaid або отримати сесію не вдається, збережіть ID сесії та перевірте знову. Вебхуків поки немає, тому запускайте завдання звірки для клієнтів, які закривають вкладку до повернення.