# Platform API (/uk/platform-api)





Tapaya Platform API дає змогу керувати мерчантами, платежами та налаштуваннями організації з вашого сервера. Які
ендпоінти вам потрібні, залежить від того, як ваш застосунок приймає платежі; не кожному інтегратору потрібні всі розділи.

<SwaggerBanner href="https://api.tapaya.com/openapi/index.html" />

<Callout title="Переліки (enum) є числовими" type="info">
  Такі поля, як `businessTypeId`, `countryId`, `currencyId`, `documentType` і `refundReasonId`, є числовими
  переліками (enum). Можливі значення для кожного з них наведено в
  [документації Swagger](https://api.tapaya.com/openapi/index.html), а не в цьому посібнику.
</Callout>

## Які розділи стосуються вас [#which-sections-apply-to-you]

| Ваша інтеграція                                                                                                                 | [Автентифікація мерчантів](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations) | [Онбординг мерчантів](/platform-api/merchant_onboarding) | [Звітність і платежі](/platform-api/reporting) |
| ------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------: | :--------------------------------------------: |
| **Accept SDK** (вбудований у ваш застосунок)                                                                                    |                                                     🟢 Обов'язково                                                    |                     🟡 Необов'язково                     |                🟡 Необов'язково                |
| **Лише застосунок Tapaya Terminal** ([intent/deeplink](/in-store/integration/card_terminal#integrate-without-the-sdk), без SDK) |                                                     ⚪ Не потрібно                                                     |                     🟡 Необов'язково                     |                🟡 Необов'язково                |
| **Лише звітність / бек-офіс**                                                                                                   |                                                     ⚪ Не потрібно                                                     |                       ⚪ Не потрібно                      |                 🟢 Обов'язково                 |

* **Автентифікація мерчантів**: SDK автентифікується як мерчант за допомогою токена входу, який запитує ваш бекенд. Для
  інтеграцій із Tapaya Terminal не потрібна: мерчант входить безпосередньо в застосунок Tapaya Terminal, тож немає
  сесії SDK, яку мав би автентифікувати ваш бекенд.
* **Онбординг мерчантів**: необов'язковий для будь-якої платіжної інтеграції, у торговій точці чи онлайн. Мерчант проходить онбординг один раз, і
  цей онбординг охоплює обидва канали. Онбординг відбувається через Tapaya Platform UI, хостоване запрошення або API, залежно від того,
  хто має збирати дані мерчанта.
* **Звітність і платежі**: необов'язкові для будь-якої з платіжних інтеграцій, якщо ви створюєте власні панелі керування;
  обов'язкові (і самі по собі достатні), якщо ви лише отримуєте дані для звітності без власної платіжної інтеграції.

Усі рядки однаково потребують [автентифікації](#authentication) за допомогою Server Secret Token.

<Callout title="Використання Secret key для Checkout" type="info">
  [Онлайн-Checkout](/online/integration/api_integration#authentication) приймає той самий **Secret key** зі
  [сторінки API Keys](https://platform.tapaya.com/api-keys/), який тут називається Server Secret Token.
  Checkout вимагає `Authorization: Bearer <secret-key>` і зіставляє організацію з мерчантом.
  Вимоги до зіставлення мерчанта див. у розділі [Автентифікація Checkout](/online/integration/api_integration#authentication).
</Callout>

## Середовища [#environments]

Tapaya Platform API підтримує такі середовища:

* **Робоче середовище (production):** Розміщене за адресою `https://api.tapaya.com`. Це середовище використовує реальні облікові записи й працює з реальними коштами. &#x2A;*Не використовуйте робоче середовище для тестування.**
* **Пісочниця (sandbox):** Розміщена за адресою `https://api.sandbox.tapaya.com`. Це середовище дає змогу тестувати інтеграцію без жодного руху реальних коштів. Докладніше про тестування читайте в нашому [посібнику з тестування / пісочниці](/in-store/getting-started/testing).

## Автентифікація [#authentication]

Запити до Platform API використовують ваш Server Secret Token, який на сторінці API Keys позначено як **Secret key**. Передавайте його без змін у заголовку `Authorization` ваших HTTP-запитів.

```http
Authorization: REPLACE_ME
```

Щоб автентифікувати свою платформу в API, ви повинні згенерувати **Secret key**, який тут називається Server Secret Token, на [сторінці API Keys](https://platform.tapaya.com/api-keys/) і замінити ним *REPLACE\_ME* вище.

<Callout title="Попередження щодо безпеки" type="warn">
  Ваш Server Secret Token має високі привілеї. **Ніколи** не розкривайте його в клієнтському коді (мобільні застосунки, браузери). Його можна використовувати лише з ваших захищених бекенд-серверів.
</Callout>

Якщо токен скомпрометовано, відкличте його на [сторінці API Keys](https://platform.tapaya.com/api-keys/); відкликання
набуває чинності негайно, і його не можна скасувати. Згенеруйте токен на заміну до або після відкликання, як вам потрібно;
дії «ротації» на місці не існує, тож щойно новий токен створено, оновіть ним конфігурацію свого бекенда.

<Callout title="Без обмеження області дії ключів" type="info">
  Кожен Server Secret Token має однакові привілеї в межах усієї організації; наразі токени не можна обмежити
  конкретними ендпоінтами чи мерчантами. Вважайте будь-який токен рівнозначним повному доступу до API для вашої організації.
</Callout>

Сервер доступний лише через протокол HTTPS, а на рівні інфраструктури примусово застосовується TLS 1.2 або новіший. Діє обмеження частоти запитів (100 запитів на хвилину з однієї IP-адреси); запити, що перевантажують сервер, повертатимуть помилку `429 Too Many Requests`.