# Керування мерчантами (/uk/platform-api/merchant_management)
Керуйте мерчантами своєї організації зі свого backend. Кожен виклик використовує ваш Server Secret Token, тому зберігайте його на своєму сервері.
| Відомості | Значення |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Базовий URL | `https://api.sandbox.tapaya.com` для пісочниці (sandbox), `https://api.tapaya.com` для робочого середовища |
| Автентифікація | Server Secret Token у заголовку `Authorization`. Див. [Автентифікація](/platform-api#authentication). |
| Суми | У найменших одиницях валюти: `2500` з `EUR` означає 25,00 EUR. Відносні комісії в базисних пунктах: `100` означає 1%. |
| Пов'язаний посібник | [Онбординг мерчантів](/platform-api/merchant_onboarding) |
## Усі операції [#all-operations]
| Операція | Використовуйте, щоб |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| [Прочитати збережений онбординг](#read-a-saved-onboarding) | Продовжити заповнення форми онбордингу мерчанта з місця, де він зупинився. |
| [Зберегти вибір каналів](#save-channel-selections) | Зберегти платіжні канали, які вибрав мерчант, без надсилання заявки. |
| [Отримати список учасників](#list-members) | Дізнатися, хто вже має доступ до мерчанта. |
| [Отримати список терміналів](#list-terminals) | Показати термінали мерчанта та їхні пристрої. |
| [Отримати список запрошень електронною поштою](#list-email-invites) | Відстежувати одноразові запрошення, надіслані відомим одержувачам. |
| [Отримати список багаторазових посилань](#list-reusable-links) | Відстежувати посилання кампаній і те, чи вони призупинені. |
| [Створити багаторазове посилання](#create-a-reusable-link) | Запустити кампанію, через яку можуть зареєструватися багато мерчантів. |
| [Змінити строк дії запрошення](#change-an-invites-expiry) | Продовжити або скоротити строк дії запрошення, зокрема простроченого. |
| [Призупинити або відновити багаторазове посилання](#pause-or-resume-a-reusable-link) | Тимчасово зупинити нові реєстрації, не відкликаючи посилання. |
| [Отримати список наборів тарифів](#list-pricing-sets) | Знайти набори тарифів, з яких ваша організація може створювати профілі. |
| [Отримати список комісійних профілів](#list-commission-profiles) | Вибрати профіль для призначення запрошенню. |
| [Створити комісійний профіль](#create-a-commission-profile) | Запропонувати мерчантам тарифний список, створений із набору тарифів. |
| [Оновити комісійний профіль](#update-a-commission-profile) | Перейменувати профіль або змінити його тарифи. |
| [Видалити комісійний профіль](#delete-a-commission-profile) | Видалити профіль, який ви більше не пропонуєте. |
| [Установити профіль за замовчуванням](#set-the-default-profile) | Вибрати профіль, який використовують запрошення, що не вказують жодного профілю. |
| [Прочитати тарифи мерчанта](#read-merchant-pricing) | Показати тарифи, з якими зареєструвався мерчант. |
## Чернетки онбордингу [#onboarding-drafts]
**Використовуйте, щоб** продовжити заповнення форми онбордингу мерчанта з усім, що він уже зберіг.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Це єдиний виклик, який повертає весь збережений онбординг; виклики профілю та процесора повертають лише його частини.
* `pricingConstraints` перелічує, що може вибрати мерчант, а не тарифні сітки комісій.
**Повертає:**
| Поле | Опис |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `identity` | Ідентифікаційні дані мерчанта. |
| `address` | Адреса мерчанта. |
| `business` | Відомості про бізнес, спільні для обох каналів. |
| `kyb` | Банківські рахунки, основний рахунок, стейкхолдери компанії або фізична особа та їхні документи. |
| `capability` | Вибрана capability. |
| `terminal` | Збережені дані каналу платежів у торговій точці. |
| `online` | Збережені дані каналу онлайн-платежів. |
| `processors` | Статус у кожного платіжного процесора. |
| `commissionProfileIds` | Комісійні профілі, призначені мерчанту. |
| `pricingConstraints` | Дозволені валюти розрахунку та MCC. |
**Використовуйте, щоб** зберегти платіжні канали, які мерчант вибрав у вашій формі, ще до завершення онбордингу.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"capability": 2,
"terminal": {
"mcc": "5411",
"statementDescriptor": "ACME STORE",
"productDescription": "Groceries",
"averageItemValue": 2500,
"expectedMonthlyTurnover": 500000,
"numberOfTerminals": 1
}
}'
```
**Варто знати:**
* Працює лише для мерчанта, у якого вже збережено чернетку онбордингу та профіль.
* Оновлює чернетку й повертає `200`. Не надсилає заявку на онбординг і не реєструє обліковий запис у процесора.
* Передавайте лише ті секції каналів, які вибрав мерчант.
**Параметри:**
| Поле | Опис |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Вибрані канали. Ті самі значення, що й в [онбордингу мерчантів](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | Дані каналу платежів у торговій точці з тими самими полями, що й в онбордингу мерчантів. |
| `online` | Дані каналу онлайн-платежів з тими самими полями, що й в онбордингу мерчантів. |
## Учасники й термінали [#members-and-terminals]
**Використовуйте, щоб** дізнатися, хто вже має доступ до мерчанта.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Повертає масив поточних учасників.
* Запрошення, що очікують прийняття, не включено; вони мають окремий список.
**Повертає:** для кожного учасника:
| Поле | Опис |
| ----------- | ------------------------------------ |
| `userId` | ID користувача учасника. |
| `firstName` | Ім'я. |
| `lastName` | Прізвище. |
| `email` | Адреса електронної пошти. |
| `joinedAt` | Коли учасник приєднався до мерчанта. |
**Використовуйте, щоб** показати термінали мерчанта та призначені їм пристрої.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Повертає термінали, а не активні локації; локації мають власний список.
* Відповідь містить `items` і `totalCount`. Кожен елемент містить ID термінала й локації, назву та відомості про пристрій.
* `terminalType` і `deviceIdentifier` описують поточний призначений пристрій, а не пристрій, яким було прийнято попередній платіж.
**Параметри:**
| Поле | Опис |
| --------------- | ----------------------------- |
| `page` | Номер сторінки. |
| `pageSize` | Кількість рядків на сторінці. |
| `sortBy` | Поле для сортування. |
| `sortDirection` | Напрям сортування. |
## Реєстраційні запрошення [#registration-invites]
Використовуйте [запрошення електронною поштою](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) для відомого одержувача або багаторазове посилання для кампанії. Обидва варіанти можуть обмежувати канали та призначати комісійні профілі.
**Використовуйте, щоб** відстежувати надіслані одноразові запрошення.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Кожне запрошення показує адресу електронної пошти одержувача, URL, `capability` і `commissionProfileIds`.
* Запрошення також містять `commissionProfileId`, форму `commissionProfileIds` для одного профілю.
**Використовуйте, щоб** відстежувати посилання своїх кампаній і бачити, які з них призупинені.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Кожне посилання показує свою `capability`, призначені профілі та `pausedAt`.
* `pausedAt` дорівнює `null`, поки посилання не призупинене.
* Призупинене посилання, яке не прострочене й не відкликане, усе ще відповідає `isActive=true`. Щоб їх розрізнити, перевіряйте `pausedAt`.
**Використовуйте, щоб** запустити кампанію, через яку можуть зареєструватися багато мерчантів.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Partner onboarding",
"expiresAt": "2030-12-31T00:00:00Z",
"capability": 2
}'
```
**Варто знати:**
* `capability` обмежує, які канали можуть вибрати мерчанти. Це не надає схвалення процесора.
* Не передавайте поля профілів, щоб призначити профіль організації за замовчуванням.
* `commissionProfileId` досі приймається для одного профілю. Натомість використовуйте `commissionProfileIds` і ніколи не надсилайте обидва поля.
**Параметри:**
| Поле | Опис |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | Назва кампанії. |
| `expiresAt` | Позначка часу ISO 8601 UTC щонайменше на один день у майбутньому. Максимум не обмежено. |
| `capability` | Необов'язкове. Ті самі значення, що й для [запрошень електронною поштою](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Необов'язкове. Ті самі правила, що й для запрошень електронною поштою. |
**Використовуйте, щоб** продовжити або скоротити строк дії запрошення, зокрема вже простроченого.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2031-01-31T00:00:00Z"}'
```
**Варто знати:**
* Для запрошення електронною поштою викличте `PUT /integrator/merchant/invites/{inviteId}/expires-at` з тим самим тілом.
* Повертає `204`.
* Відкликані запрошення та використані запрошення електронною поштою не можна продовжити.
**Параметри:**
| Поле | Опис |
| ----------- | --------------------------------------------------------------------------------------- |
| `expiresAt` | Позначка часу ISO 8601 UTC щонайменше на один день у майбутньому. Максимум не обмежено. |
**Використовуйте, щоб** тимчасово зупинити нові реєстрації, не відкликаючи посилання.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Викличте `.../resume` для того самого посилання, щоб знову приймати реєстрації. Відновлення не продовжує строк дії.
* Обидва виклики повертають `204` і є ідемпотентними.
* Відкриття призупиненого посилання повертає `410`.
## Комісійні профілі [#commission-profiles]
Комісійний профіль це тарифний список, який ви пропонуєте мерчантам. Створюйте його з набору тарифів, дозволеного вашій організації.
**Використовуйте, щоб** знайти набори тарифів, з яких можна створювати комісійні профілі.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Кожен набір містить договірні тарифи для мерчанта й інтегратора.
* Використовуйте отриманий `pricingSetId` під час створення профілю.
**Параметри:**
| Поле | Опис |
| ------------- | -------------------------------------- |
| `pricingType` | Необов'язкове. `online` або `instore`. |
**Використовуйте, щоб** вибрати профіль для призначення запрошенню.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Повертає лише ввімкнені й повністю налаштовані профілі вашої організації.
* Кожен профіль охоплює один тип тарифів.
* Збережіть `revision` кожного профілю, якщо плануєте його оновлювати.
**Параметри:**
| Поле | Опис |
| ------------- | -------------------------------------- |
| `pricingType` | Необов'язкове. `online` або `instore`. |
**Використовуйте, щоб** запропонувати мерчантам тарифний список, створений із набору тарифів.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"pricings": [
{"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"}
]
}'
```
**Варто знати:**
* Профіль охоплює один тип тарифів, узятий з його наборів тарифів.
* Витрати інтегратора та частки маржі визначає набір тарифів; ви встановлюєте лише тарифи мерчанта.
* `region` має значення `1` (внутрішні) або `2` (міжнародні), `holderType` має значення `1` (споживач) або `2` (компанія), а `scheme` має значення `1` (Visa) або `2` (Mastercard).
**Параметри:**
| Поле | Опис |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Назва профілю. |
| `pricingModel` | `1` для MDR або `2` для IC++. |
| `cardTypes` | Кожна комбінація регіону, типу власника картки та платіжної системи, яку приймає профіль, з її реферальними комісіями. |
| `pricings` | Валюта та `pricingSetId` для кожної валюти, яку ви пропонуєте. |
| `merchantPricingOverrides` | Необов'язкове. Елементи з `holderCategory`, `regionSegment`, `relative` і `absolute`. Для пропущених комбінацій зберігаються тарифи набору. |
**Використовуйте, щоб** перейменувати профіль або змінити його тарифи.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile 2027",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"expectedRevision": 3
}'
```
**Варто знати:**
* Передайте останню прочитану `revision` як `expectedRevision`. Застаріла ревізія повертає `409`.
* Не передавайте `pricings`, щоб зберегти наявні тарифи.
* Профіль, призначений мерчантам або недоступний для редагування, приймає лише нову назву.
**Параметри:**
| Поле | Опис |
| ------------------ | ----------------------------------------------------- |
| `name` | Обов'язкове. Назва профілю. |
| `pricingModel` | Обов'язкове. `1` для MDR або `2` для IC++. |
| `cardTypes` | Обов'язкове. Так само, як під час створення. |
| `pricings` | Необов'язкове. Так само, як під час створення. |
| `expectedRevision` | `revision` профілю на момент, коли ви його прочитали. |
**Використовуйте, щоб** видалити профіль, який ви більше не пропонуєте.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Профіль за замовчуванням не можна видалити. Спочатку зробіть профілем за замовчуванням інший профіль.
* Профіль, призначений мерчантам, не можна видалити. В обох випадках повертається `400`.
**Використовуйте, щоб** вибрати профіль, який використовують запрошення, що не вказують жодного профілю.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Ваша організація має один профіль за замовчуванням.
* Профіль за замовчуванням не можна видалити.
## Тарифи мерчанта [#merchant-pricing]
**Використовуйте, щоб** показати тарифи, з якими зареєструвався мерчант, для платежів у торговій точці та онлайн-платежів.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Варто знати:**
* Канал без збережених тарифів має значення `null`. Мерчант без жодного збереженого тарифного списку повертає `404`.
* Повертає договірні тарифи, а не базові тарифні сітки платіжного провайдера. Читайте тарифи з `cells`; компоненти `commission` не є фактично отриманими комісіями.
* Невідома модель або витрати інтегратора мають значення `null`, а не нуль.
* Частки доходу розподіляють розподілювану маржу, а не всю суму платежу.
**Повертає:**
| Поле | Опис |
| ------------------------------------- | -------------------------------------------------------------------- |
| `instore` | Тарифи для платежів у торговій точці або `null`. |
| `online` | Тарифи для онлайн-платежів або `null`. |
| `currency` | Валюта тарифів. |
| `pricingModel` | Тарифна модель мерчанта. |
| `integratorPricingModel` | Тарифна модель інтегратора, незалежна від моделі мерчанта. |
| `priceListId` | Збережений тарифний список мерчанта, якщо доступний. |
| `pricingSetVersionId` | Версія вихідного набору тарифів, якщо доступна. |
| `pricingSetName` | Назва вихідного набору тарифів, якщо доступна. |
| `cells` | Тарифи за категорією власника картки та регіоном. |
| `cells[].discountBps` | Кінцева відносна ставка мерчанта в базисних пунктах. |
| `cells[].transactionFeeMinor` | Кінцева фіксована комісія мерчанта в найменших одиницях валюти. |
| `cells[].integratorCostRelativeBps` | Договірні відносні витрати інтегратора в базисних пунктах. |
| `cells[].integratorCostAbsoluteMinor` | Договірні фіксовані витрати інтегратора в найменших одиницях валюти. |
| `cells[].revenueShareTapayaBps` | Частка Tapaya в розподілюваній маржі в базисних пунктах. |
| `cells[].revenueShareIntegratorBps` | Ваша частка в розподілюваній маржі в базисних пунктах. |
## Помилки [#errors]
Кожна операція відповідає цими кодами статусу, коли запит не вдається.
| Код | Опис |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Некоректні дані каналів, вибір профілів, фільтри або строк дії; чи спроба видалити профіль за замовчуванням або призначений профіль. |
| `401` | Server Secret Token відсутній або недійсний. |
| `404` | Ресурс недоступний вашій організації або збережений онбординг чи тарифи не існують. |
| `409` | Застаріла ревізія профілю, конфліктний стан онбордингу або використане чи відкликане запрошення. |