# Типи подій (/uk/webhooks/events)



Виберіть із цих 23 типів подій або ввімкніть підписку на всі типи. Кожне сповіщення використовує [спільну оболонку події](/webhooks#event-envelope); на цій сторінці показано, що кожна група подій розміщує всередині `data`.

## Групи подій [#event-families]

| Група                                      | Події | `data` містить       |
| ------------------------------------------ | ----- | -------------------- |
| [Платежі](#payments)                       | 7     | `payment`            |
| [Повернення коштів](#refunds)              | 6     | `payment` і `refund` |
| [Мерчанти](#merchants)                     | 2     | `merchant`           |
| [Онбординг мерчанта](#merchant-onboarding) | 8     | `onboarding`         |

Більшість інтеграцій починає з `payment.succeeded`, `payment.failed` і `payment.refund.succeeded`. Платформи, які проводять онбординг мерчантів, додають `merchant.onboarding.approved` і `merchant.onboarding.action_required`.

## Платежі [#payments]

Ці події описують увесь платіж у межах підтримуваних платіжних процесорів і каналів. Вони містять `data.payment`, зокрема поля `status` і `statusId` платежу.

| Подія                                                                | Коли надсилається                                                                                                          |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.created`</span>         | Платіж зберігається.                                                                                                       |
| <span className="whitespace-nowrap">`payment.updated`</span>         | Його статус змінюється на `pending` або інший статус без окремої назви події. Це не сповіщення про кожне редагування поля. |
| <span className="whitespace-nowrap">`payment.succeeded`</span>       | Його статус змінюється на `success`.                                                                                       |
| <span className="whitespace-nowrap">`payment.failed`</span>          | Увесь платіж переходить у статус `failed`, а не окрема спроба платежу завершується невдало.                                |
| <span className="whitespace-nowrap">`payment.canceled`</span>        | Його статус змінюється на `cancelled`.                                                                                     |
| <span className="whitespace-nowrap">`payment.refunded`</span>        | Tapaya позначає платіж як `refunded`.                                                                                      |
| <span className="whitespace-nowrap">`payment.action_required`</span> | Його статус змінюється на `actionNeeded`.                                                                                  |

Створення платежу в стані, відмінному від очікування, надсилає і `payment.created`, і відповідну подію статусу, якщо ви підписані на обидві. Повторне збереження того самого статусу не надсилає ані нової події статусу, ані `payment.updated`.

Поля `status` і `statusId` у знімках платежів і повернень коштів набувають таких значень:

| `statusId` | `status`       | Значення                                          |
| ---------- | -------------- | ------------------------------------------------- |
| `1`        | `pending`      | Обробка ще не досягла остаточного результату.     |
| `2`        | `success`      | Платіж або повернення коштів завершено успішно.   |
| `3`        | `cancelled`    | Платіж або повернення коштів скасовано.           |
| `4`        | `refunded`     | Tapaya позначила платіж як повернений.            |
| `5`        | `failed`       | Платіж або повернення коштів завершилося невдало. |
| `6`        | `actionNeeded` | Потрібна подальша дія.                            |

Невідомі майбутні ID статусів використовують `status: "unknown"` і зберігають числове значення `statusId`. Назви подій використовують `succeeded` і `canceled`; значення статусів використовують `success` і `cancelled`.

## Повернення коштів [#refunds]

Події повернення коштів містять і `data.payment`, і `data.refund`. Повернення коштів має власні ID, токен, статус, запитані суми й суми розрахунку та їхні валюти. Використовуйте ID повернення коштів, щоб відстежувати його незалежно від батьківського платежу.

| Подія                                                                       | Коли надсилається                                                             |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.refund.created`</span>         | Повернення коштів зберігається.                                               |
| <span className="whitespace-nowrap">`payment.refund.updated`</span>         | Його статус змінюється на `pending` або інший статус без окремої назви події. |
| <span className="whitespace-nowrap">`payment.refund.succeeded`</span>       | Його статус змінюється на `success`.                                          |
| <span className="whitespace-nowrap">`payment.refund.failed`</span>          | Його статус змінюється на `failed`.                                           |
| <span className="whitespace-nowrap">`payment.refund.canceled`</span>        | Його статус змінюється на `cancelled`.                                        |
| <span className="whitespace-nowrap">`payment.refund.action_required`</span> | Його статус змінюється на `actionNeeded`.                                     |

Створення повернення коштів у стані, відмінному від очікування, також може надіслати відповідну подію статусу. Успішне повернення коштів саме собою не описує остаточний статус усього платежу: перевірте `data.payment.status` і будь-яке окреме сповіщення `payment.refunded`.

## Мерчанти [#merchants]

Події мерчантів містять `data.merchant` із полями `id`, `token` і знімком збереженого статусу мерчанта.

| Подія                                                                | Коли надсилається                                                                                                                        |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.created`</span>        | У вашій організації створюється мерчант.                                                                                                 |
| <span className="whitespace-nowrap">`merchant.status_changed`</span> | Змінюється активація, статус базового запису мерчанта, наявність профілю або обліковий запис, подання, схвалення чи відмова у процесора. |

```json title="data"
{
  "merchant": {
    "id": "019a0000-0000-7000-8000-000000000005",
    "token": "example_merchant_token",
    "status": {
      "isActive": true,
      "isShellMerchant": false,
      "profileOnboarded": true,
      "processors": [
        {
          "paymentProcessorId": 2,
          "hasAccount": true,
          "submitted": true,
          "approved": true,
          "rejected": false,
          "submittedAt": "2026-10-29T10:00:00+00:00",
          "approvedAt": "2026-10-30T12:00:00+00:00",
          "rejectedAt": null
        }
      ]
    }
  }
}
```

* `profileOnboarded` означає, що профіль існує. Це не означає, що процесор схвалив мерчанта або що всі способи оплати готові.
* Ідентифікатори облікових записів у процесорів та їхні приватні повідомлення про відмову не включаються. ID процесора вище наведено для ілюстрації.
* Збереження незмінених значень або редагування непов'язаних даних мерчанта не надсилає жодної події. Події `merchant.updated` та події видалення мерчанта немає.

## Онбординг мерчанта [#merchant-onboarding]

Події онбордингу містять `data.onboarding`. Його `status` відповідає останньому сегменту назви події, а деякі події додають поля, наведені нижче.

| Подія                                                                                  | Коли надсилається                                                                                                                             |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.onboarding.started`</span>               | Перший профіль мерчанта та дані онбордингу збережено.                                                                                         |
| <span className="whitespace-nowrap">`merchant.onboarding.profile_completed`</span>     | Перший повний профіль мерчанта збережено.                                                                                                     |
| <span className="whitespace-nowrap">`merchant.onboarding.document_added`</span>        | Новий документ збережено. Додає `documentId`, `documentTypeId`, `paymentProcessorId` і `source: "cache"` для тимчасово збереженого документа. |
| <span className="whitespace-nowrap">`merchant.onboarding.stakeholder_completed`</span> | Дані онбордингу зацікавленої особи завершено. Додає `stakeholderId`.                                                                          |
| <span className="whitespace-nowrap">`merchant.onboarding.submitted`</span>             | Онбординг готовий до подання процесору. Додає `paymentProcessorId`.                                                                           |
| <span className="whitespace-nowrap">`merchant.onboarding.approved`</span>              | Обліковий запис у процесора вперше схвалено. Додає `paymentProcessorId`.                                                                      |
| <span className="whitespace-nowrap">`merchant.onboarding.rejected`</span>              | Tapaya відхиляє онбординг після ручної перевірки. Додає `reason`, а `requiredAction` має значення `null`.                                     |
| <span className="whitespace-nowrap">`merchant.onboarding.action_required`</span>       | Tapaya запитує додаткову інформацію після ручної перевірки. Додає `reason` і `requiredAction`.                                                |

```json title="data"
{
  "onboarding": {
    "status": "action_required",
    "reason": "The submitted company document is no longer valid.",
    "requiredAction": "Upload a current company registration document."
  }
}
```

<Accordions>
  <Accordion title="Граничні випадки для кожної події" id="onboarding-edge-cases">
    * `profile_completed` наразі надходить разом зі `started`. Жодна з цих подій не означає схвалення процесором.
    * `document_added` містить метадані, а не файл. Переміщення тимчасово збереженого документа до процесора не надсилає подію повторно.
    * `stakeholder_completed` охоплює й завершення через запрошення. Повторне збереження того самого завершення не надсилає подію повторно.
    * `submitted` є сповіщенням про готовність; воно не підтверджує, що запит надійшов до процесора. Окремої події `merchant.onboarding.ready` немає.
    * `approved` надсилається для кожного процесора окремо. Схвалення одним процесором не означає схвалення всіма.
    * `rejected` і `action_required` надходять лише з ручної перевірки Tapaya, ніколи безпосередньо від платіжного процесора. Повторення рішення не надсилає нової події, відомості про фахівців, які виконували перевірку, не включаються, і рішення не змінює прапорці схвалення процесором.
  </Accordion>
</Accordions>

Події онбордингу та статусу мерчанта описують різні аспекти зміни. Той самий збережений профіль або схвалення процесором може створити обидві групи подій, якщо ви підписані на обидві; не покладайтеся на певний порядок між ними. Події минулої активності онбордингу не додаються заднім числом.

## Діагностичні тести [#diagnostic-tests]

Використовуйте тестову дію в Platform, щоб надіслати `webhook.test`. Він містить `test: true`, `merchantId: null` і `data.message`, без стану платежу або мерчанта. Його не можна вибрати як підписку на події.

Перегляньте [Перевірку й тестування](/webhooks/receiving#send-a-test-webhook), щоб перевірити доставку без створення платежу.