Вебхуки
Отримуйте підписані сповіщення про зміни платежів, повернень коштів, мерчантів та онбордингу.
Вебхуки сповіщають ваш сервер про зміни у вашій організації Tapaya. Використовуйте ту саму інтеграцію для платежів у торговій точці та онлайн-платежів незалежно від платіжного процесора.
Як це працює
TapayaНалаштуйте одну цільову HTTPS-адресу для кожної організації та виберіть потрібні події. Tapaya надсилає HTTP POST зі знімком у форматі JSON і підписом. Перевірте підпис, збережіть подію та поверніть успішну відповідь перед виконанням власної бізнес-логіки.
Ви можете підписатися на окремі типи або на всі підтримувані типи. Підписка на всі типи також отримуватиме нові підтримувані типи в майбутньому, тому ігноруйте типи, які ваш застосунок не розпізнає.
Швидка інтеграція
Збережіть цільову адресу
У Platform відкрийте API Keys, потім Webhooks. Введіть свою HTTPS URL-адресу, виберіть потрібні події та збережіть. Одразу скопіюйте signing secret (ключ підпису); він показується лише один раз. Див. Налаштування.
Перевіряйте кожен запит
Обчисліть HMAC-SHA256 від часової мітки, крапки та початкового тіла за допомогою свого signing secret і порівняйте результат із X-Tapaya-Signature. Див. Перевірте підпис.
Збережіть подію, потім поверніть 2xx
Збережіть подію з унікальним id, дайте відповідь 2xx протягом 10 секунд і обробіть її після цього. Див. Збережіть і підтвердьте.
Надішліть тестовий вебхук
На тій самій сторінці скористайтеся тестовою дією, щоб надіслати підписаний webhook.test. Див. Надішліть тестовий вебхук.
Оболонка події
Кожна подія використовує цю спільну структуру. Знімок ресурсу всередині data залежить від типу події.
{
"id": "019a0000-0000-7000-8000-000000000001",
"type": "payment.succeeded",
"apiVersion": "1",
"organizationId": "019a0000-0000-7000-8000-000000000002",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"createdAt": "2026-10-30T12:00:00.000000Z",
"data": {
"payment": {
"id": "019a0000-0000-7000-8000-000000000003",
"token": "example_payment_token",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"status": "success",
"statusId": 2,
"requestedAmount": 10000,
"requestedCurrencyId": 203,
"settlementAmount": 10000,
"settlementCurrencyId": 203
}
}
}| Поле | Значення |
|---|---|
id | Унікальний ID події. Використовуйте його для дедуплікації доставок. Повторні спроби зберігають той самий ID. |
type | Назва події з каталогу подій. |
apiVersion | Ідентифікатор схеми payload, наразі рядок "1". |
organizationId | Організація, якій належить подія. Перевірте, чи вона відповідає вашій інтеграції. |
merchantId | Мерчант, якому належить ресурс. Може бути null для старіших платежів із невизначеним власником або діагностичного тесту. |
createdAt | Час UTC, коли подію зафіксовано, а не час її доставки. |
data | Незмінний знімок ресурсу на момент фіксації. |
Суми є цілими числами в найменших одиницях валюти відповідного поля. Наприклад, 10000 із числовим ID валюти ISO 4217 203 означає 100,00 CZK. Запитані суми та суми розрахунку можуть бути в різних валютах.
Кожен тип події містить у data власний знімок. Усі структури payload і значення статусів наведено в розділі Типи подій.
Правила доставки
Tapaya надсилає подію, щойно її зміну збережено, і надсилає її повторно, доки ваш сервер не відповість 2xx.
| Правило | Поведінка |
|---|---|
| Підтвердження | Будь-яка відповідь 2xx протягом 10 секунд. Переспрямування не виконуються. |
| Повторні спроби | Щонайбільше 12 спроб протягом приблизно 20 годин з очікуванням 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 і 360 хвилин. |
| Порядок | Не гарантовано. Доставка відбувається принаймні один раз, тому очікуйте дублікати та старіші знімки. |
| Одночасність | 2 запити одночасно на організацію, спільно з ручними тестами. Інші події очікують у черзі. |
Невдала доставка ніколи не змінює сам платіж, а минулі доставки неможливо надіслати повторно. Щоб надолужити пропущене після збою, зчитайте поточний стан через API платежів і мерчантів.