Інтеграція через API

Ваш бекенд створює сесію Checkout для кожного замовлення та отримує її, щоб перевірити платіж.

Для Node.js SDK @tapayadot/checkout надає типізовані методи create() і get() для цих ендпоінтів. Типово він зчитує TAPAYA_SECRET_KEY. HTTP-приклади на цій сторінці явно передають TAPAYA_CHECKOUT_API_KEY.

Автентифікація

Кожен виклик Checkout відбувається між серверами й надсилає ключ як bearer-токен:

Authorization: Bearer <key>

Виберіть режим залежно від того, хто керує бекендом. Будь-який із ключів зберігайте на своєму сервері; див. Безпека Checkout.

Режим мерчанта

Використовуйте цей режим, коли бекенд обслуговує один магазин. Створіть checkout-ключ мерчанта в налаштуваннях Checkout: відкрийте мерчанта та виберіть Create merchant key. Ключ починається з tapaya_test_ у пісочниці (sandbox) або з tapaya_live_ у робочому середовищі й відповідає саме цьому мерчанту.

Authorization: Bearer <merchant-checkout-key>

У цьому режимі X-Tapaya-Merchant-Token необов'язковий. Якщо ви його надсилаєте, він має вказувати на того самого мерчанта.

Platform показує ключ один раз і зберігає лише його хеш. Щоб виконати ротацію ключа, створіть заміну, перш ніж відкликати старий ключ. Відкликання ключа не впливає на інші ключі мерчанта, ключі організації чи client secret, уже видані браузерам.

Режим платформи

Використовуйте цей режим, коли один бекенд діє від імені багатьох мерчантів, наприклад маркетплейс або платформа доставки їжі. Надсилайте Secret key організації зі сторінки API Keys і токен мерчанта в кожному запиті:

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

Типового мерчанта немає. Запит без цього заголовка повертає HTTP 401. Мерчант має належати до організації ключа. Скопіюйте токени мерчантів із таблиці мерчантів у налаштуваннях Checkout. Токен ідентифікує мерчанта; він не є секретом.

Secret key організації є тими самими обліковими даними, які в документації Platform API називаються Server Secret Token. Checkout вимагає префікс Bearer. Інші ендпоінти Platform API приймають токен напряму. Онбординг мерчантів і керування організацією використовують Platform API.

Тіла запитів не приймають merchantId.

Середовища

Задайте для TAPAYA_CHECKOUT_API_URL origin API свого середовища. У робочому середовищі доступні як Hosted Checkout, так і вбудовані платежі. Кожен мерчант має пройти онбординг, отримати схвалення платіжного процесора для онлайн-платежів і мати налаштований платіжний шлюз. Перевірте готовність мерчанта в налаштуваннях Checkout. Використовуйте повернений URL сесії Hosted Checkout без змін.

Сесії Checkout

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Відповідальність за замовлення та платіж

ID сесії Checkout ідентифікує сесію Hosted Checkout. Її merchantOrderId пов'язує її з вашим замовленням, а paymentReference ідентифікує останню спробу підтвердження. Зберігайте ID сесії разом із замовленням, щоб отримати результат, навіть якщо клієнт закриє браузер.

Сторінка Hosted Checkout використовує окремі публічні ендпоінти для завантаження та підтвердження сесії. ID сесії є обліковими даними доступу до цих ендпоінтів. Інтеграція мерчанта перевіряє платіж через автентифікований ендпоінт мерчанта.

Один платіж на замовлення

Hosted Checkout і Embedded Checkout використовують один спільний платіжний рушій. Мерчант може мати щонайбільше один успішний платіж на кожен merchantOrderId. ID замовлень діють у межах мерчанта, тож різні мерчанти, навіть в одній організації, можуть використовувати однакові ID.

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

Ідемпотентність і помилки

Для створення потрібен непорожній Idempotency-Key довжиною щонайбільше 250 символів. Для того самого мерчанта:

Відмова в оплаті карткою є результатом платежу, а не доказом того, що HTTP-запит не вдався.