API для онбордингу мерчантів

Створюйте мерчантів і надсилайте їхні дані на онбординг або запрошуйте їх пройти онбординг через Tapaya Platform API.

Усі запити на цій сторінці використовують ваш Server Secret Token. Див. розділ Автентифікація.

Один онбординг для торгової точки та онлайну

Мерчант може в одній заявці на онбординг подати запит на прийом платежів у торговій точці, онлайн-платежі або на обидва. Ця сторінка стосується всіх інтеграцій: Accept SDK, застосунку Tapaya Terminal і Checkout. Використовуйте її, щоб створювати мерчантів і керувати ними через API замість Tapaya Platform UI. Запитуйте ті платіжні можливості, які потрібні мерчанту. Схвалення для торгової точки саме по собі не вмикає онлайн-платежі.

Створення мерчанта за допомогою POST /integrator/merchant або POST /merchant/auth/register в інтеграції Accept SDK створює його обліковий запис, але мерчант не може обробляти реальні платежі ні в торговій точці, ні онлайн, доки не завершить онбординг. Для онлайн-платежів запитайте можливість Checkout і дочекайтеся схвалення процесором онлайн-платежів і налаштування шлюзу. Мерчанти автоматично з'являються в налаштуваннях Checkout, де можна перевірити їхню готовність і налаштувати ключі та гаманці. Tapaya підтримує кілька варіантів онбордингу; усіма можна керувати з Tapaya Platform UI і, де доречно, автоматизувати.

Сценарій	Коли використовувати	Точка входу в API
Tapaya Platform UI	Ваша операційна команда завершує онбординг від імені мерчанта.	Створіть або виберіть мерчанта в Tapaya Platform UI і відкрийте там хостований онбординг.
Власний інтерфейс	Ви збираєте та валідуєте інформацію для онбордингу у своєму продукті.	Валідуйте розділи за допомогою `POST /integrator/merchant/onboarding/validate/*`, а потім надішліть дані за допомогою `POST /integrator/merchant/onboarding`. Докладніше нижче.
Запрошення електронною поштою	Відомий мерчант отримує одноразове запрошення пройти онбординг самостійно.	Надішліть запрошення за допомогою `POST /integrator/merchant/send-registration-invite`; додайте `merchantToken`, щоб прив'язати запрошення до наявного базового запису мерчанта, а потім переглядайте або відкликайте його через `/integrator/merchant/invites`.
Посилання кампанії	Кілька мерчантів або мерчанти, ще не відомі заздалегідь, використовують багаторазове посилання для самостійної реєстрації.	Створіть посилання за допомогою `POST /integrator/merchant/reusable-registration-invites`; переглядайте або відкликайте посилання через той самий ресурс.

Докладне порівняння цих сценаріїв наведено в посібнику з онбордингу мерчантів.

Запит можливостей онлайн-платежів

POST /integrator/merchant/onboarding вимагає capability. Використовуйте те саме значення можливості під час валідації бізнес-профілю:

Значення	Можливість	Дані каналу
`1`	Both (обидва)	Надайте `terminal` і `online`. Кожен канал потребує окремого схвалення.
`2`	Terminals (термінали)	Надайте `terminal` для платежів у торговій точці.
`3`	Checkout	Надайте `online` для онлайн-платежів. Термінал не потрібен.

Для Checkout додайте такі поля верхнього рівня разом з ідентифікаційними даними мерчанта, адресою, спільним business і даними KYB. Ті самі поля каналу застосовуються до POST /integrator/merchant/onboarding/validate/business:

{
	"capability": 3,
	"online": {
		"mcc": "5411",
		"statementDescriptor": "ACME CORP",
		"productDescription": "Groceries sold online",
		"averageItemValue": 2500,
		"expectedMonthlyTurnover": 500000,
		"url": "https://www.acme.example.com",
		"purchaseChargeTiming": 1,
		"averageDeliveryDays": 2,
		"topCountries": [{ "countryId": 1, "percentage": 100 }]
	}
}

Суми вказуються в найменших одиницях валюти. Вебсайт онлайн-каналу має використовувати HTTP або HTTPS, а його ім'я хоста має містити www. statementDescriptor має довжину від 5 до 22 символів. purchaseChargeTiming має значення 1, якщо оплата стягується під час оформлення замовлення, 2 під час відправлення або 3 після отримання. averageDeliveryDays становить від 0 до 999. Надайте від однієї до чотирьох унікальних topCountries, відсотки яких у сумі дають 100.

Спільні дані підтримки та фінансові дані зберігайте в business. У режимі розділів каналів розміщуйте MCC, опис у банківській виписці (statement descriptor), опис продукту та оцінки транзакцій у відповідному об'єкті terminal або online. Валідуйте payload перед надсиланням онбордингу та виправте повернені помилки полів, специфічні для каналу.

Запрошення мерчанта пройти хостований онбординг

Використовуйте цей сценарій, коли форму KYB має розміщувати Tapaya, але ви все одно хочете керувати створенням мерчанта зі свого бекенда.

Рекомендовано, якщо merchantToken визначаєте ви

Якщо ідентифікатор мерчанта, який згодом використовує SDK або ваш бек-офіс, визначає ваша система, спочатку створіть базовий запис мерчанта за допомогою POST /merchant/auth/register або POST /integrator/merchant, а потім викличте POST /integrator/merchant/send-registration-invite з тим самим merchantToken. Так хостований онбординг залишиться прив'язаним до цього мерчанта, а не створить другого.

Рекомендована послідовність:

Створіть базовий запис мерчанта:
- POST /merchant/auth/register або
- POST /integrator/merchant
Надішліть запрошення на хостований онбординг за допомогою POST /integrator/merchant/send-registration-invite
За потреби поділіться поверненим registrationUrl з мерчантом і дайте йому заповнити форму, розміщену Tapaya
Періодично перевіряйте готовність мерчанта через GET /integrator/merchant/{merchantId}/status

Ендпоінт: POST /integrator/merchant/send-registration-invite

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/send-registration-invite' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "email": "admin@acme.com",
        "merchantToken": "unique_merchant_id_from_your_db"
    }'

Параметри:

Поле	Тип	Обов'язкове	Опис
`email`	`string`	✓	Адреса електронної пошти, на яку слід надіслати посилання на хостований онбординг.
`merchantToken`	`string`		Токен наявного мерчанта, до якого слід прив'язати запрошення. Використовуйте його, якщо ви вже створили базовий запис мерчанта й хочете, щоб хостований онбординг заповнив саме цього мерчанта. Якщо його не вказано, завершення запрошення створює нового мерчанта.

Відповіді:

Код	Опис
`200`	Запрошення створено. Відповідь містить `registrationUrl`
`400`	Помилка валідації запиту
`401`	Не авторизовано
`404`	Організацію або мерчанта не знайдено
`409`	Конфлікт

Тіло відповіді:

{
    "registrationUrl": "https://platform.tapaya.com/invite-merchant?token=...&merchantToken=unique_merchant_id_from_your_db"
}

Tapaya також намагається надіслати це посилання електронною поштою. Доставка електронної пошти не гарантується, тому завжди вважайте повернений registrationUrl джерелом істини для свого інтерфейсу та інструментів підтримки.

Не плутайте із запрошенням користувача мерчанта

POST /integrator/merchant/{merchantId}/invite є іншим сценарієм. Він запрошує користувача платформи отримати доступ до вже наявного облікового запису мерчанта. Він не запускає онбординг KYB і не створює та не оновлює профіль мерчанта.

Надсилання онбордингу через API

Якщо ви хочете збирати інформацію для онбордингу у власному продукті, а не направляти мерчантів до Tapaya Platform, надсилайте її безпосередньо. Валідуйте кожен розділ, щойно мерчант його заповнить, за допомогою наведених нижче ендпоінтів validate/*, а потім надішліть усе одним викликом, який одночасно створює мерчанта та його профіль онбордингу й реєструє його в платіжного процесора, якому надає перевагу ваша організація.

Згода мерчанта та повідомлення про конфіденційність

Перш ніж надсилати дані для онбордингу через API, ви повинні отримати згоду мерчанта з Умовами та положеннями Tapaya для інтеграторів і Політикою конфіденційності Tapaya. Додайте до форми онбордингу прапорець із посиланнями на обидва документи або послайтеся на документи Tapaya в тексті умов, з якими погоджується мерчант. Ви також повинні зазначити Tapaya як обробника даних у власній політиці конфіденційності.

У разі помилки мерчанта не створено

POST /integrator/merchant/onboarding створює мерчанта й надсилає онбординг одним викликом. Якщо дані онбордингу невалідні, він повертає 422 з помилками на рівні полів, і мерчанта не створюється; немає мерчанта з частково пройденим онбордингом, якого потрібно було б видаляти чи продовжувати.

Валідація ідентифікаційних даних

Ендпоінт: POST /integrator/merchant/onboarding/validate/identity

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/identity' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "legalName": "Acme Corp s.r.o.",
        "businessTypeId": 2,
        "email": "admin@acme.com",
        "registrationNumber": "12345678",
        "vatNumber": "CZ12345678",
        "incorporationDate": "2018-04-01"
    }'

Параметри:

Поле	Тип	Обов'язкове	Опис
`legalName`	`string`	✓	Юридична назва бізнесу або ім'я фізичної особи, власника облікового запису.
`businessTypeId`	`int`	✓	Тип суб'єкта господарювання (`BusinessTypeEnum`).
`email`	`string`	✓	Контактна адреса електронної пошти.
`registrationNumber`	`string`	✓	Офіційний реєстраційний номер бізнесу. Перевіряється на дублікати в межах вашої
організації.
`vatNumber`	`string`		Номер платника ПДВ, якщо застосовно.
`incorporationDate`	`date`		Дата юридичної реєстрації бізнесу (`YYYY-MM-DD`).

Тіло відповіді:

{
    "valid": true,
    "errors": []
}

registrationNumber, який уже використовує інший мерчант вашої організації, повертається як помилка valid: false з code: "DUPLICATE_REGISTRATION_NUMBER", а не як 409; цей ендпоінт завжди повертає 200.

Валідація адреси

Ендпоінт: POST /integrator/merchant/onboarding/validate/address

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/address' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "line1": "Wenceslas Square 1",
        "city": "Prague",
        "postalCode": "11000",
        "countryId": 1
    }'

Параметри:

Поле	Тип	Обов'язкове	Опис
`line1`	`string`	✓	Перший рядок адреси.
`line2`	`string`		Другий рядок адреси, якщо застосовно.
`city`	`string`	✓	Назва міста.
`postalCode`	`string`	✓	Поштовий індекс.
`state`	`string`		Штат або регіон, якщо застосовно.
`countryId`	`int`	✓	Країна (`CountryEnum`).

Тіло відповіді: та сама структура {valid, errors}, що й у Валідації ідентифікаційних даних.

Валідація бізнес-профілю

Ендпоінт: POST /integrator/merchant/onboarding/validate/business

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/business' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "capability": 2,
        "mcc": "5411",
        "url": "https://acme.example.com",
        "supportPhone": "+420123456789",
        "statementDescriptor": "ACME CORP"
    }'

Параметри:

Поле	Тип	Обов'язкове	Опис
`capability`	`int`	✓	Використовуйте ту можливість, яку ви надішлете для онбордингу. Для Checkout або Both надайте дані каналу.
`mcc`	`string`	✓	Чотиризначний код категорії мерчанта (Merchant Category Code). У режимі розділів каналів використовуйте `terminal.mcc` або `online.mcc`.
`url`	`string`		URL вебсайту бізнесу. Обов'язковим є `url` або `productDescription`.
`productDescription`	`string`		Опис товарів або послуг. Обов'язковим є `url` або
`productDescription`.
`supportPhone`	`string`	✓	Номер телефону служби підтримки клієнтів у форматі E.164.
`statementDescriptor`	`string`	✓	Текст, що відображається в банківських виписках клієнтів (1–22 символи).
`averageItemValue`	`long`		Середня сума транзакції в найменших одиницях валюти.
`expectedMonthlyTurnover`	`long`		Очікуваний місячний дохід у найменших одиницях валюти.
`numberOfEmployees`	`int`		Кількість працівників бізнесу.
`annualTurnover`	`long`		Річний дохід у найменших одиницях валюти.
`balanceSheetTotal`	`long`		Підсумок балансу в найменших одиницях валюти.

Тіло відповіді: та сама структура {valid, errors}, що й у Валідації ідентифікаційних даних.

Валідація KYB

Ендпоінт: POST /integrator/merchant/onboarding/validate/kyb

Надайте рівно одне з двох: individual (фізична особа-підприємець / самозайнята особа) або company. Для company перелічіть у people кожного власника, директора та уповноважену особу з правом підпису.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/kyb' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "businessTypeId": 2,
        "bankAccount": {
            "iban": "CZ6508000000192000145399",
            "bic": "GIBACZPX",
            "currencyId": 1,
            "beneficiaryName": "Acme Corp s.r.o."
        },
        "company": {
            "name": "Acme Corp s.r.o.",
            "registrationNumber": "12345678",
            "people": [
                {
                    "email": "jane@acme.com",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "role": {
                        "isOwner": true,
                        "isAuthorizedSignatory": true
                    }
                }
            ]
        }
    }'

Параметри:

Поле	Тип	Опис
`businessTypeId`	`int`	Тип суб'єкта господарювання (`BusinessTypeEnum`); визначає, чи обов'язкові поля `individual`, чи
`company`.
`bankAccount`	`object`	Банківський рахунок для виплат (номер рахунку/IBAN + BIC, валюта, отримувач і
адреса банку).
`individual`	`object`	Дані власника-фізичної особи для ФОП. Взаємовиключне з `company`.
`company`	`object`	Дані компанії, зокрема масив `people` із власниками, директорами та уповноваженими особами
з правом підпису, а також необов'язковий `verificationDocument`. Взаємовиключне з `individual`.

Кожна особа в people (і individual) має прапорці role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory, а також необов'язкові ідентифікаційні поля (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). Запис про особу має бути або лише запрошенням, або повністю заповненим; частково заповнені записи відхиляються. Дані особи можна надіслати двома способами:

Лише запрошення: надішліть тільки email і role. Особа отримує електронний лист з інструкціями, як самостійно заповнити свої персональні дані та пройти верифікацію особи, зокрема завантажити власний документ, що посвідчує особу; вам не потрібно збирати для неї нічого іншого, і завантажувати документи з вашого боку не потрібно.
Повністю заповнений запис: самостійно надішліть усі персональні дані особи (ім'я, дату народження, офіційний документ, адресу тощо). У такому разі ви також повинні завантажити документ, що посвідчує особу, для цієї особи; це обов'язково, а не за бажанням, для кожної особи з повністю заповненим записом.

Документи завантажуються після того, як мерчант уже існує, оскільки ендпоінту завантаження документів потрібен merchantId, повернений створенням мерчанта з онбордингом. Завантаження кожної особи зіставляється з нею за relatedOfficialIdNumber. Необов'язкові поля verificationDocuments.identityDocument, verificationDocuments.additionalDocument і company.verificationDocument приймають об'єкт {frontFileId, backFileId} і можуть посилатися лише на вже завантажені файли, тому не вказуйте їх під час створення нового мерчанта.

Незалежно від того, скільки осіб надіслано лише як запрошення, а скільки з повністю заповненими записами, ви завжди повинні завантажити реєстраційний документ компанії, перш ніж мерчанта можна буде подати на перевірку KYC.

Тіло відповіді: та сама структура {valid, errors}, що й у Валідації ідентифікаційних даних.

Створення мерчанта з онбордингом

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

Ендпоінт: POST /integrator/merchant/onboarding

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "name": "Acme Corp",
        "capability": 2,
        "merchantToken": "unique_merchant_id_from_your_db",
        "identity": {
            "legalName": "Acme Corp s.r.o.",
            "businessTypeId": 2,
            "email": "admin@acme.com",
            "registrationNumber": "12345678",
            "vatNumber": "CZ12345678"
        },
        "address": {
            "line1": "Wenceslas Square 1",
            "city": "Prague",
            "postalCode": "11000",
            "countryId": 1
        },
        "business": {
            "mcc": "5411",
            "url": "https://acme.example.com",
            "supportPhone": "+420123456789",
            "statementDescriptor": "ACME CORP"
        },
        "kyb": {
            "bankAccount": {
                "iban": "CZ6508000000192000145399",
                "bic": "GIBACZPX",
                "currencyId": 1,
                "beneficiaryName": "Acme Corp s.r.o."
            },
            "company": {
                "people": [
                    {
                        "email": "jane@acme.com",
                        "firstName": "Jane",
                        "lastName": "Doe",
                        "role": {
                            "isOwner": true,
                            "isAuthorizedSignatory": true
                        }
                    }
                ]
            }
        }
    }'

Параметри:

Поле	Тип	Обов'язкове	Опис
`capability`	`int`	✓	`1` для Both, `2` для Terminals або `3` для Checkout. Див. можливості онлайн-платежів.
`terminal`	`object`	Залежно від можливості	Дані термінального каналу для Terminals або Both.
`online`	`object`	Залежно від можливості	Дані онлайн-каналу для Checkout або Both.
`name`	`string`	✓	Назва мерчанта.
`merchantToken`	`string`		Унікальний стабільний ідентифікатор із вашої системи. Якщо його не надано, генерується
випадковий токен.
`identity`	`object`	✓	Та сама структура, що й у Валідації ідентифікаційних даних.
`address`	`object`	✓	Та сама структура, що й у Валідації адреси.
`business`	`object`	✓	Та сама структура, що й у Валідації бізнес-профілю.
`kyb`	`object`	✓	Та сама структура, що й у Валідації KYB.

Відповіді:

Код	Опис
`201`	Мерчанта створено, онбординг надіслано
`422`	Дані онбордингу невалідні, див. `errors`; мерчанта не створено

Тіло відповіді (201):

{
    "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
    "merchantToken": "unique_merchant_id_from_your_db",
    "name": "Acme Corp",
    "email": "admin@acme.com",
    "processors": [
        {
            "processorId": 5,
            "registered": true,
            "onboardingUrl": null
        }
    ]
}

onboardingUrl заповнюється, коли процесор вимагає, щоб мерчант пройшов додатковий хостований сценарій онбордингу (наприклад, верифікацію особи), перш ніж він зможе обробляти реальні платежі.

Тіло відповіді (422):

{
    "errors": [
        {
            "step": "identity",
            "field": "registrationNumber",
            "message": "A merchant with this registration number is already onboarded under this integrator (merchantId: 018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e).",
            "code": "DUPLICATE_REGISTRATION_NUMBER"
        }
    ]
}

Завантаження документа, що посвідчує особу

Обов'язково для кожної особи з повністю заповненим записом у kyb.company.people / kyb.individual (див. Валідація KYB); особи, надіслані лише як запрошення, натомість завантажують власні документи за посиланням з електронного листа.

Ендпоінт: POST /integrator/merchant/{merchantId}/document

Тіло запиту має формат multipart/form-data, а не JSON.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=2' \
-F 'relatedOfficialIdNumber=123456789' \
-F 'frontFile=@./jane-doe-id-front.jpg' \
-F 'backFile=@./jane-doe-id-back.jpg'

Параметри:

Поле	Тип	Обов'язкове	Опис
`paymentProcessorId`	`int`	✓	Завжди `5`.
`documentType`	`int`	✓	Тип документа (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company,
`5` BankStatement, `6` Passport, `7` RecentFinancials).
`frontFile`	`file`	✓	Зображення лицьового боку документа.
`backFile`	`file`		Зображення зворотного боку документа, якщо застосовно.
`relatedOfficialIdNumber`	`string`		`officialIdNumber` особи з Валідації KYB.
Обов'язкове лише тоді, коли `documentType` прив'язаний до фізичної особи (наприклад, Id, Passport, Address); в інших випадках ігнорується.
`submitMerchant`	`boolean`		Тут залиште незаданим/`false`: документ особи не є останнім завантаженням у пакеті.
Установлюйте `true` лише під час завантаження документа компанії, коли документи всіх осіб уже
завантажено.

Тіло відповіді (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Завантаження документа компанії

Обов'язково рівно один раз для кожного мерчанта. Якщо дані осіб не було заповнено, уповноважена особа з правом підпису зможе завантажити його за посиланням з електронного листа про онбординг, і викликати цей ендпоінт не потрібно.

Ендпоінт: POST /integrator/merchant/{merchantId}/document

Тіло запиту має формат multipart/form-data, а не JSON.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=4' \
-F 'frontFile=@./acme-corp-register-extract.pdf' \
-F 'submitMerchant=true'

Параметри:

Поле	Тип	Обов'язкове	Опис
`paymentProcessorId`	`int`	✓	Завжди `5`.
`documentType`	`int`	✓	Для цього кроку завжди `4` (`Company`).
`frontFile`	`file`	✓	Реєстраційний документ компанії.
`submitMerchant`	`boolean`		Установіть `true`, щоб запустити перевірку KYC процесором, оскільки всі потрібні
документи вже завантажено. Типове значення `false`.

Тіло відповіді (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": null,
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Чогось бракує на цій сторінці?Надішліть запит на функцію. Ми додамо цю сторінку, щоб команда бачила контекст.

API для онбордингу мерчантів

На цій сторінці