Представляємо Tapaya Checkout, Tapaya

Картки, Apple Pay і Google Pay через один API. Перенаправляйте клієнтів на хостинговану платіжну сторінку або вбудуйте захищені поля для картки у власну сторінку оформлення замовлення. Ось як працює кожен варіант і як обрати.

Tapaya Checkout додає до Tapaya онлайн-платежі. Ваші мерчанти можуть приймати картки, Apple Pay і Google Pay на будь-якому сайті, а ви обираєте, яку частину оформлення оплати контролюєте самі.

Hosted Checkout. Ваш сервер створює сесію й перенаправляє клієнта на захищену платіжну сторінку, яку хостить Tapaya. Роботи на фронтенді майже не потрібно.
Embedded Checkout. Захищені поля для картки та кнопки гаманців розміщені прямо на вашій сторінці оформлення замовлення, поруч із вашою власною кнопкою «Оплатити».

Обидва варіанти працюють за однією серверною моделлю: створити, перенаправити або вбудувати, а потім перевірити на сервері, перш ніж виконувати замовлення. Почати можна вже сьогодні в sandbox на docs.tapaya.com.

Introducing Tapaya Checkout: New way to payments online · Відео завантажується з YouTube лише після натискання кнопки відтворення.

Що таке Tapaya Checkout

Tapaya Checkout — це онлайн-частина Tapaya. Він приймає для ваших мерчантів платежі картками, Apple Pay і Google Pay через один API та один Node.js SDK. Ідея та сама, що й для платежів у точці продажу: ви інтегруєтеся один раз, досвід мерчанта залишається у вашому продукті, а всю складність платежів під капотом бере на себе Tapaya.

Hosted Checkout дає вам готову платіжну сторінку на домені Tapaya, для комп'ютера й мобільних пристроїв.
Embedded Checkout дає вам захищені поля, які ви вбудовуєте у власну сторінку. Дані картки залишаються у фреймі (iframe) Tapaya й ніколи не потрапляють на вашу сторінку.

Обидва варіанти побудовані на тих самих основах: серверний ключ, суми в найменших одиницях валюти (тобто 1880 означає 18,80 EUR), ідемпотентні запити й перевірка на сервері. Коли ви побудуєте один, більшість іншого вже знатимете.

Hosted чи Embedded: що обрати

	Hosted Checkout	Embedded Checkout
Де платить клієнт	На сторінці, яку хостить Tapaya, а потім повертається до вашого магазину	Прямо на вашій сторінці оформлення замовлення
Робота на фронтенді	Перенаправлення	Вбудувати поля, обробити `submit()` і стан
Кнопка «Оплатити»	На сторінці Tapaya	Ваша власна кнопка
Apple Pay і Google Pay	На хостингованій сторінці	Відображаються у фреймі Tapaya поруч із полями картки
3-D Secure	Обробляється на хостингованій сторінці	Обробляється всередині `submit()`, у фреймі Tapaya
Найкраще підходить для	Швидкого запуску, простих магазинів, платформ із багатьма мерчантами	Команд, які хочуть повністю контролювати оформлення оплати

Якщо не впевнені, почніть із Hosted Checkout. Пізніший перехід на Embedded використовує ті самі ключі, ту саму модель замовлень і ту саму логіку перевірки.

Hosted Checkout за п'ять кроків

Створіть сесію на сервері. Викличте POST /merchant/checkout-sessions з merchantOrderId, amount (у найменших одиницях), currency, customer, successUrl і cancelUrl. Надішліть заголовок Idempotency-Key.
Збережіть ID сесії у замовленні.
Перенаправте браузер на session.url з HTTP 303. Використовуйте URL точно в тому вигляді, у якому його повернуто.
Клієнт платить на хостингованій сторінці. Якщо картку відхилено, можна спробувати ще раз на тій самій сторінці. Сесії приймають платежі протягом 30 хвилин.
Перевірте на сервері. Коли клієнт повертається на будь-яку з URL повернення, викличте GET /merchant/checkout-sessions/{id}. Переконайтеся, що ID, ID замовлення, сума й валюта збігаються з вашим замовленням, і виконуйте замовлення лише тоді, коли paymentStatus дорівнює successful.

З Node.js SDK (npm install @tapayadot/checkout, Node.js 22.13.0 або новіший) основа виглядає так:

TypeScript

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)

Усі параметри описано в типі CreateHostedCheckoutSessionParams і в посібнику з Hosted Checkout.

Embedded Checkout: захищені поля на вашій сторінці

Embedded Checkout розподіляє роботу між вашою сторінкою та невеликим ендпоінтом prepare на вашому сервері. У браузері ви завантажуєте Tapaya з @tapayadot/checkout/client і вбудовуєте поля:

TypeScript

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

На вашому сервері ендпоінт prepare завантажує замовлення й повторно використовує наявний платіж, якщо він є. Інакше створює новий через POST /merchant/payments з ключем ідемпотентності. Потім повертає { clientSecret, status }. React-застосунки можуть використовувати usePayment() з @tapayadot/checkout/react.

Кілька речей, які варто знати:

Додайте https://js.tapaya.com до script-src і frame-src у вашій Content Security Policy.
Імпортуйте @tapayadot/checkout лише на сервері. Браузер використовує точку входу /client.
snapshot.outcome підказує, що показати: open, pending, completed або ended.
Кнопки гаманців з'являються лише там, де вони підтримуються й увімкнені. Для Apple Pay потрібен активний домен магазину, а для Google Pay у робочому режимі потрібен merchant ID.

Повний процес описано в посібнику з Embedded Checkout.

Створено для надійних інтеграцій

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

Ключі ідемпотентності для кожного створення. Повторіть запит із тим самим ключем і тим самим тілом, і ви отримаєте початкову сесію чи платіж. Змінене тіло повертає HTTP 409.
Вбудовані повторні спроби в Node.js SDK. За замовчуванням він двічі повторює запит у разі помилок з'єднання, тайм-аутів і HTTP 429, 502, 503 та 504, з випадковою затримкою між спробами (jitter).
Один платіж на замовлення. Нова сесія для того самого замовлення завершує попередню. Оплачене замовлення або замовлення з платежем у процесі буде відхилено.
Вебхуки плюс опитування. Підпишіться на події сесій і як запасний варіант продовжуйте перевіряти невирішені сесії.
Спершу перевірити, потім виконати, і лише один раз. Сам по собі візит на вашу URL успіху нічого не доводить. Завжди підтверджуйте статус на сервері й записуйте виконання замовлення атомарно.

Перед запуском у робочий режим перевірте кожен результат за допомогою тестових карток sandbox і пройдіть QA-чекліст.

Розробляйте швидше з MCP-сервером документації Tapaya

Документація Tapaya має власний MCP-сервер. Ваші AI-інструменти для програмування можуть шукати в посібниках і переглядати API-ендпоінти, поки ви розробляєте, не виходячи з редактора. Він працює з Claude Code, Claude Desktop, Cursor, VS Code, Codex і будь-яким іншим MCP-клієнтом. Він публічний і не потребує API-ключа.

Terminal

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

Він ніколи не викликає робочий API Tapaya й ніколи не запитує ключі. Налаштування для кожного клієнта описано в MCP Setup.

Від sandbox до робочого режиму

Підключіть мерчанта з можливістю онлайн-платежів і зачекайте, доки в Tapaya Platform у розділі Checkout з'явиться статус Ready.
Додайте свій магазин до Allowed websites і задайте типові URL для успіху та скасування.
Розробляйте в sandbox з ключем tapaya_test_, який зберігається лише на вашому сервері.
Перейдіть у продакшн: продакшн-ключ, TAPAYA_ENVIRONMENT=production і продакшн-URL повернення.
Налаштуйте гаманці для робочого режиму: домен магазину для Apple Pay і merchant ID для Google Pay.

Посібник Quick Start проведе вас від нуля до першого платежу в sandbox за кілька серверних викликів.

Часті запитання

Які способи оплати підтримує Tapaya Checkout?

Картки, Apple Pay і Google Pay, як у Hosted, так і в Embedded Checkout.

Чи проходять дані картки через мій сервер або сторінку?

Ні. У Hosted Checkout клієнт платить на сторінці Tapaya. В Embedded Checkout поля картки та 3-D Secure працюють усередині фрейму Tapaya, і дані картки ніколи не потрапляють на вашу сторінку.

Скільки діє сесія Hosted Checkout?

30 хвилин від створення. Платіж, надісланий до цього часу, усе одно буде завершено. Якщо після цього замовлення досі не оплачене, створіть нову сесію.

Чи є SDK?

Так, @tapayadot/checkout для Node.js 22.13.0 або новішого. Він покриває Hosted Checkout на сервері, а також точки входу для браузера й React для Embedded Checkout. Інші стеки можуть викликати REST API напряму.

Чи можуть платформи приймати платежі для багатьох мерчантів?

Так. Використовуйте Secret key організації й надсилайте токен мерчанта з кожним запитом.

Почніть зараз

Прочитайте огляд Online Payments на docs.tapaya.com, створіть ключ для sandbox і прийміть свій перший тестовий платіж уже сьогодні. Маєте запитання щодо інтеграції? Пишіть на developers@tapaya.com.