# Інтеграція через API (/uk/online/integration/api_integration) Ваш бекенд створює сесію Checkout для кожного замовлення та отримує її, щоб перевірити платіж. Для Node.js [SDK `@tapayadot/checkout`](/online/integration/node_sdk) надає типізовані методи `create()` і `get()` для цих ендпоінтів. Типово він зчитує `TAPAYA_SECRET_KEY`. HTTP-приклади на цій сторінці явно передають `TAPAYA_CHECKOUT_API_KEY`. ## Автентифікація [#authentication] Кожен виклик Checkout відбувається між серверами й надсилає ключ як bearer-токен: ```http Authorization: Bearer ``` Виберіть режим залежно від того, хто керує бекендом. Будь-який із ключів зберігайте на своєму сервері; див. [Безпека Checkout](/online/security/checkout_security). ### Режим мерчанта [#merchant-mode] Використовуйте цей режим, коли бекенд обслуговує один магазин. Створіть **checkout-ключ мерчанта** в [налаштуваннях Checkout](/online/integration/checkout_settings#create-merchant-checkout-keys): відкрийте мерчанта та виберіть **Create merchant key**. Ключ починається з `tapaya_test_` у пісочниці (sandbox) або з `tapaya_live_` у робочому середовищі й відповідає саме цьому мерчанту. ```http Authorization: Bearer ``` У цьому режимі `X-Tapaya-Merchant-Token` необов'язковий. Якщо ви його надсилаєте, він має вказувати на того самого мерчанта. Platform показує ключ один раз і зберігає лише його хеш. Щоб виконати ротацію ключа, створіть заміну, перш ніж відкликати старий ключ. Відкликання ключа не впливає на інші ключі мерчанта, ключі організації чи client secret, уже видані браузерам. ### Режим платформи [#platform-mode] Використовуйте цей режим, коли один бекенд діє від імені багатьох мерчантів, наприклад маркетплейс або платформа доставки їжі. Надсилайте Secret key організації зі [сторінки API Keys](https://platform.tapaya.com/api-keys/) і токен мерчанта в **кожному** запиті: ```http Authorization: Bearer X-Tapaya-Merchant-Token: ``` Типового мерчанта немає. Запит без цього заголовка повертає HTTP 401. Мерчант має належати до організації ключа. Скопіюйте токени мерчантів із таблиці мерчантів у [налаштуваннях Checkout](/online/integration/checkout_settings). Токен ідентифікує мерчанта; він не є секретом. Secret key організації є тими самими обліковими даними, які в [документації Platform API](/platform-api#authentication) називаються Server Secret Token. Checkout вимагає префікс `Bearer`. Інші ендпоінти Platform API приймають токен напряму. Онбординг мерчантів і керування організацією використовують [Platform API](/platform-api). Тіла запитів не приймають `merchantId`. ## Середовища [#environments] | Середовище | Origin API | Origin Hosted Checkout | Облікові дані | | ----------------- | -------------------------------- | ------------------------------------- | ----------------------------------------------------------------------- | | Пісочниця | `https://api.sandbox.tapaya.com` | `https://checkout.sandbox.tapaya.com` | Ключі пісочниці з [тестовими картками](/online/getting-started/testing) | | Робоче середовище | `https://api.tapaya.com` | `https://checkout.tapaya.com` | Ключі робочого режиму з реальними способами оплати | Задайте для `TAPAYA_CHECKOUT_API_URL` origin API свого середовища. У робочому середовищі доступні як Hosted Checkout, так і вбудовані платежі. Кожен мерчант має пройти [онбординг](/merchants/onboarding), отримати схвалення платіжного процесора для онлайн-платежів і мати налаштований платіжний шлюз. Перевірте готовність мерчанта в [налаштуваннях Checkout](/online/integration/checkout_settings). Використовуйте повернений URL сесії Hosted Checkout без змін. ## Сесії Checkout [#checkout-sessions]
### Створення сесії Checkout [#create-a-checkout-session] Створіть сесію, коли клієнт натискає **Checkout** у вашому магазині, а потім переспрямуйте його на повернений `url`. Спочатку обчисліть остаточну суму на своєму сервері та збережіть замовлення з унікальним idempotency key. **Ендпоінт:** `POST /merchant/checkout-sessions` cURL ```bash 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" }' ``` **Заголовки:** | Заголовок | Обов'язковий | Опис | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | | `Authorization` | ✓ | `Bearer `: checkout-ключ мерчанта або Secret key організації. | | `X-Tapaya-Merchant-Token` | Режим платформи | Токен мерчанта, що належить до організації ключа. Необов'язковий із checkout-ключем мерчанта. | | `Idempotency-Key` | ✓ | Непорожній, щонайбільше 250 символів. Див. [Ідемпотентність і помилки](#idempotency-and-errors). | **Параметри:** | Поле | Тип | Обов'язкове | Опис | | ----------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `merchantOrderId` | `string` | ✓ | Ваш референс замовлення, від 1 до 200 символів. Див. [Один платіж на замовлення](#one-payment-per-order). | | `amount` | `integer` | ✓ | Остаточна сума до стягнення в мінімальних одиницях валюти, включно з податком і доставкою. Від 1 до 2 147 483 647. | | `currency` | `string` | ✓ | Тризначний код ISO 4217, який підтримує бекенд, у верхньому регістрі, наприклад `EUR`. | | `locale` | `string` | | Типово `en`. | | `successUrl` | `string` | | Перевизначає типовий URL успіху для цієї сесії. Має відповідати дозволеному вебсайту облікових даних, якими здійснюється виклик. | | `cancelUrl` | `string` | | Перевизначає типовий URL скасування для цієї сесії. Має відповідати дозволеному вебсайту облікових даних, якими здійснюється виклик. | | `tax` | `integer` | | ПДВ, уже включений в `amount`, від нуля до `amount`. Типово `0`. | | `shipping` | `integer` | | Доставка, уже включена в `amount`, від нуля до `amount`. Типово `0`. | | `taxRate` | `number` | | Ставка ПДВ у відсотках для всього замовлення, наприклад `21` або `5.5`. Невід'ємна. | | `taxBreakdown` | `array` | | ПДВ, згрупований за ставками. Непорожній масив не можна передавати разом із `taxRate`. | | `items` | `array` | | Позиції замовлення лише для відображення. Не визначають суму до стягнення. | | `customer` | `object` | | Email клієнта, адреса для рахунку та адреса доставки. | Сесія стягує оплату у валюті `currency`, яку ви задали. [Підтримувані валюти](/merchants/supported_currencies) містять усі валюти, які підтримує Tapaya, але для мерчанта зазвичай увімкнено лише деякі з них. Створення сесії у валюті, яку не підтримує мерчант або бекенд, відхиляється, тож сторінка Hosted Checkout не створюється. API стягує `amount` у тому вигляді, у якому його передано. Він не додає доставку чи податок, не обчислює ПДВ за ставкою і не обчислює суму з позицій. Кожен запис містить числовий `taxRate` і цілочисельний `tax`, обидва невід'ємні. Ставки унікальні, а суми податку в записах разом дають `tax` верхнього рівня. ```json { "amount": 22650, "currency": "EUR", "tax": 2650, "shipping": 605, "taxBreakdown": [ { "taxRate": 21, "tax": 2100 }, { "taxRate": 5.5, "tax": 550 } ] } ``` Кожна позиція потребує `reference`, `name`, `description`, `imageUrl`, `quantity` і `unitAmount`. Текстові поля непорожні, `imageUrl` є URL, `quantity` є додатним цілим числом, а `unitAmount` є невід'ємним цілим числом у мінімальних одиницях валюти. Об'єкт `customer` приймає `email`, `billingAddress` і `shippingAddress`. Кожне поле необов'язкове, як і кожне поле адреси, тож адреса для рахунку може містити лише поштовий індекс і країну. | Поле | Обмеження або формат | | ------------------------ | ---------------------------------------------------------------- | | `email` | Адреса email, до 254 символів. | | `name`, `line1`, `line2` | До 200 символів кожне. | | `phone` | До 30 символів. | | `city`, `state` | До 100 символів кожне. | | `postalCode` | До 20 символів. | | `country` | Дволітерний код країни ISO у верхньому регістрі, наприклад `CZ`. | Передані текстові поля адреси мають бути непорожніми. Невідомі поля можна пропустити. Бекенд зберігає знімок переданих даних клієнта, щоб передати шлюзу інформацію для оцінки ризиків. Дані клієнта не включаються у відповіді щодо сесії. **Відповіді:** | Код | Опис | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Сесію створено або для повторених ключа, тіла та режиму облікових даних повернуто ту саму сесію з її поточним статусом | | `409` | Конфлікт: ключ повторно використано зі зміненим тілом або режимом облікових даних (`API-0025`) або замовлення вже оплачено чи платіж за ним триває | **Тіло відповіді:** ```json { "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" } ``` `taxRate` включається лише тоді, коли його передано. Збережіть `id` разом із замовленням, а потім переспрямуйте браузер на `url` за допомогою HTTP 303. Сесія приймає нові платежі протягом 30 хвилин після створення; уже надісланий платіж завершується і після цього. URL повернення вибираються та валідуються під час створення з використанням або значень із запиту, або типових значень облікових даних, якими здійснюється виклик: [адрес повернення](/online/integration/checkout_settings#configure-return-destinations) організації для Secret key організації з `X-Tapaya-Merchant-Token`, адрес мерчанта для checkout-ключа мерчанта. Ці два набори ніколи не поєднуються. ### Отримання сесії [#retrieve-a-session] Коли клієнт повертається на ваш URL успіху чи скасування, а також у завданні звірки отримайте сесію та порівняйте її зі збереженим замовленням перед його виконанням. **Ендпоінт:** `GET /merchant/checkout-sessions/{id}` cURL ```bash 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" ``` Суфікса `/status` немає. Відповідь містить ідентифікатор сесії, URL, суми, податкові поля, стани та позначки часу, а також `paymentReference` і `completedAt`, які можуть мати значення null. `paymentReference` ідентифікує останню спробу підтвердження й має значення null, доки спроби немає. Референс, відмінний від null, не доводить успіх. Позначки часу є рядками ISO 8601. **Статус сесії:** | `status` | Значення | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `open` | Сесія доступна для оплати або результат надісланого платежу ще підтверджується. | | `completed` | Сесію завершено. Результат платежу дивіться в `paymentStatus`. | | `expired` | Сесія більше не доступна для нового платежу: термін її дії минув або її замінила новіша сесія для того самого замовлення. | **Статус платежу:** | `paymentStatus` | Значення для замовлення | | --------------- | ---------------------------------------------------------------------------------------- | | `unpaid` | Немає підтвердженого успішного платежу. Результат ще може підтверджуватися. | | `successful` | Платіж успішний. Перед виконанням замовлення звірте референс замовлення, суму та валюту. | | `failed` | Платіж відхилено. Поки сесія відкрита, клієнт може спробувати іншу картку чи гаманець. | | `cancelled` | Платіж скасовано. | | `action_needed` | Потрібна додаткова дія. Не виконуйте замовлення як оплачене. | Відхилена картка залишає `status` зі значенням `open`, а `paymentStatus` зі значенням `failed`. Поки Tapaya у фоновому режимі підтверджує невизначений результат, сесія залишається `open` і `unpaid`; отримайте її знову пізніше. Перехід за посиланням для скасування на сторінці Hosted Checkout є навігацією на `cancelUrl`; сам по собі він не доводить стан платежу `cancelled`. Виконуйте замовлення лише тоді, коли отримана сесія відповідає референсу, сумі та валюті вашого збереженого замовлення, а `paymentStatus` має значення `successful`. Саме лише переспрямування браузера ніколи не доводить оплату.
## Відповідальність за замовлення та платіж [#order-and-payment-ownership] | Відповідає ваш сервер | Відповідає Tapaya | | -------------------------------------------------------------- | -------------------------------------------- | | Референс замовлення, ціни, валюта та стан виконання замовлення | Сесія Checkout і результат платежу від шлюзу | ID сесії Checkout ідентифікує сесію Hosted Checkout. Її `merchantOrderId` пов'язує її з вашим замовленням, а `paymentReference` ідентифікує останню спробу підтвердження. Зберігайте ID сесії разом із замовленням, щоб отримати результат, навіть якщо клієнт закриє браузер. Сторінка Hosted Checkout використовує окремі публічні ендпоінти для завантаження та підтвердження сесії. ID сесії є обліковими даними доступу до цих ендпоінтів. Інтеграція мерчанта перевіряє платіж через автентифікований ендпоінт мерчанта. ### Один платіж на замовлення [#one-payment-per-order] Hosted Checkout і [Embedded Checkout](/online/integration/embedded_checkout) використовують один спільний платіжний рушій. Мерчант може мати щонайбільше один успішний платіж на кожен `merchantOrderId`. ID замовлень діють у межах мерчанта, тож різні мерчанти, навіть в одній організації, можуть використовувати однакові ID. * Створення сесії для неоплаченого замовлення замінює попередню неоплачену сесію. Старий URL повідомляє `expired` і більше не може прийняти оплату. * Створення сесії для замовлення, яке вже оплачено або платіж за яким триває, повертає HTTP 409. * Після відмови клієнт може спробувати іншу картку чи гаманець у тій самій сесії. Повторне надсилання того самого токена картки ніколи не призводить до подвійного стягнення коштів. * Tapaya задає політику 3-D Secure і завжди намагається виконати автентифікацію. ## Ідемпотентність і помилки [#idempotency-and-errors] Для створення потрібен непорожній `Idempotency-Key` довжиною щонайбільше 250 символів. Для того самого мерчанта: | Ви надсилаєте | Tapaya повертає | | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Той самий ключ, тіло та режим облікових даних | Ту саму сесію з її поточними `status` і `paymentStatus` | | Той самий ключ зі зміненим тілом | HTTP 409 з кодом `API-0025` | | Той самий ключ і тіло з іншим режимом облікових даних | HTTP 409 з кодом `API-0025`, оскільки кожен режим використовує власні налаштування переспрямування | | Недійсні суми, непідтримувану валюту, недійсні адреси переспрямування, відсутню конфігурацію шлюзу або мерчанта, не доданого до Checkout | Відмову у створенні сесії | Відмова в оплаті карткою є результатом платежу, а не доказом того, що HTTP-запит не вдався. Мережева помилка чи тайм-аут залишають результат платежу невідомим. Вебхуків Checkout поки немає: проводьте звірку, отримуючи сесію на своєму сервері, і повторюйте створення лише з тим самим ключем і тілом.