# Typy událostí (/cs/webhooks/events)



Vyberte si z těchto 23 typů událostí nebo zapněte odběr všech typů. Každé oznámení používá [společnou obálku události](/webhooks#event-envelope); tato stránka ukazuje, co každá skupina událostí vkládá do `data`.

## Skupiny událostí [#event-families]

| Skupina                                       | Události | `data` obsahuje      |
| --------------------------------------------- | -------- | -------------------- |
| [Platby](#payments)                           | 7        | `payment`            |
| [Vratky](#refunds)                            | 6        | `payment` a `refund` |
| [Obchodníci](#merchants)                      | 2        | `merchant`           |
| [Onboarding obchodníka](#merchant-onboarding) | 8        | `onboarding`         |

Většina integrací začíná událostmi `payment.succeeded`, `payment.failed` a `payment.refund.succeeded`. Platformy, které onboardují obchodníky, přidávají `merchant.onboarding.approved` a `merchant.onboarding.action_required`.

## Platby [#payments]

Tyto události popisují celou platbu napříč podporovanými zpracovateli a platebními kanály. Obsahují `data.payment`, včetně stavu platby `status` a `statusId`.

| Událost                                                              | Kdy se odesílá                                                                                                |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.created`</span>         | Při uložení platby.                                                                                           |
| <span className="whitespace-nowrap">`payment.updated`</span>         | Při změně stavu na `pending` nebo jiný stav bez vlastního názvu události. Nejde o oznámení každé úpravy pole. |
| <span className="whitespace-nowrap">`payment.succeeded`</span>       | Při změně stavu na `success`.                                                                                 |
| <span className="whitespace-nowrap">`payment.failed`</span>          | Při změně celé platby na `failed`, nikoli při selhání jednotlivého pokusu o platbu.                           |
| <span className="whitespace-nowrap">`payment.canceled`</span>        | Při změně stavu na `cancelled`.                                                                               |
| <span className="whitespace-nowrap">`payment.refunded`</span>        | Když Tapaya označí platbu jako `refunded`.                                                                    |
| <span className="whitespace-nowrap">`payment.action_required`</span> | Při změně stavu na `actionNeeded`.                                                                            |

Vytvoření platby v jiném než čekajícím stavu odešle `payment.created` i odpovídající stavovou událost, pokud odebíráte obě. Opětovné uložení stejného stavu neodešle novou stavovou událost ani `payment.updated`.

`status` a `statusId` nabývají ve snímcích plateb a vratek těchto hodnot:

| `statusId` | `status`       | Význam                                  |
| ---------- | -------------- | --------------------------------------- |
| `1`        | `pending`      | Zpracování zatím nemá konečný výsledek. |
| `2`        | `success`      | Platba nebo vratka byla úspěšná.        |
| `3`        | `cancelled`    | Platba nebo vratka byla zrušena.        |
| `4`        | `refunded`     | Tapaya označila platbu jako vrácenou.   |
| `5`        | `failed`       | Platba nebo vratka selhala.             |
| `6`        | `actionNeeded` | Je potřeba další akce.                  |

Neznámá budoucí ID stavů používají `status: "unknown"` a zachovávají číselné `statusId`. Názvy událostí používají `succeeded` a `canceled`; hodnoty stavu používají `success` a `cancelled`.

## Vratky [#refunds]

Události vratek obsahují `data.payment` i `data.refund`. Vratka má vlastní ID, token, stav a požadované i zúčtované částky a měny. Pomocí ID vratky ji sledujte nezávisle na původní platbě.

| Událost                                                                     | Kdy se odesílá                                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.refund.created`</span>         | Při uložení vratky.                                                       |
| <span className="whitespace-nowrap">`payment.refund.updated`</span>         | Při změně stavu na `pending` nebo jiný stav bez vlastního názvu události. |
| <span className="whitespace-nowrap">`payment.refund.succeeded`</span>       | Při změně stavu na `success`.                                             |
| <span className="whitespace-nowrap">`payment.refund.failed`</span>          | Při změně stavu na `failed`.                                              |
| <span className="whitespace-nowrap">`payment.refund.canceled`</span>        | Při změně stavu na `cancelled`.                                           |
| <span className="whitespace-nowrap">`payment.refund.action_required`</span> | Při změně stavu na `actionNeeded`.                                        |

Vytvoření vratky v jiném než čekajícím stavu může také odeslat odpovídající stavovou událost. Úspěšná vratka sama o sobě neurčuje konečný stav celé platby: zkontrolujte `data.payment.status` a případné samostatné oznámení `payment.refunded`.

## Obchodníci [#merchants]

Události obchodníků obsahují `data.merchant` s `id`, `token` a snímkem uloženého stavu obchodníka.

| Událost                                                              | Kdy se odesílá                                                                                                                            |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.created`</span>        | Při vytvoření obchodníka ve vaší organizaci.                                                                                              |
| <span className="whitespace-nowrap">`merchant.status_changed`</span> | Při změně aktivace, příznaku základního záznamu obchodníka, existence profilu nebo účtu, odeslání, schválení či zamítnutí u zpracovatele. |

```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` znamená, že existuje profil. Neznamená schválení obchodníka zpracovatelem ani připravenost všech platebních metod.
* Identifikátory účtů u zpracovatele a neveřejné zprávy zpracovatele o zamítnutí nejsou zahrnuty. ID zpracovatele výše je ilustrativní.
* Uložení nezměněných hodnot nebo úprava nesouvisejících údajů obchodníka žádnou událost neodešle. Událost `merchant.updated` ani událost smazání obchodníka neexistuje.

## Onboarding obchodníka [#merchant-onboarding]

Události onboardingu obsahují `data.onboarding`. Jeho `status` odpovídá poslední části názvu události a některé události přidávají pole uvedená níže.

| Událost                                                                                | Kdy se odesílá                                                                                                                                |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.onboarding.started`</span>               | Při uložení prvního profilu obchodníka a dat onboardingu.                                                                                     |
| <span className="whitespace-nowrap">`merchant.onboarding.profile_completed`</span>     | Při uložení prvního kompletního profilu obchodníka.                                                                                           |
| <span className="whitespace-nowrap">`merchant.onboarding.document_added`</span>        | Při uložení nového dokumentu. Přidává `documentId`, `documentTypeId`, `paymentProcessorId` a u dočasně uloženého dokumentu `source: "cache"`. |
| <span className="whitespace-nowrap">`merchant.onboarding.stakeholder_completed`</span> | Při dokončení onboardingových údajů účastníka. Přidává `stakeholderId`.                                                                       |
| <span className="whitespace-nowrap">`merchant.onboarding.submitted`</span>             | Když je onboarding připraven k odeslání zpracovateli. Přidává `paymentProcessorId`.                                                           |
| <span className="whitespace-nowrap">`merchant.onboarding.approved`</span>              | Při prvním schválení účtu u zpracovatele. Přidává `paymentProcessorId`.                                                                       |
| <span className="whitespace-nowrap">`merchant.onboarding.rejected`</span>              | Tapaya po ručním posouzení onboarding zamítne. Přidává `reason` a `requiredAction` s hodnotou `null`.                                         |
| <span className="whitespace-nowrap">`merchant.onboarding.action_required`</span>       | Tapaya po ručním posouzení požádá o doplnění informací. Přidává `reason` a `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="Okrajové případy jednotlivých událostí" id="onboarding-edge-cases">
    * `profile_completed` aktuálně přichází společně se `started`. Ani jedna z nich neznamená schválení zpracovatelem.
    * `document_added` obsahuje metadata, nikoli soubor. Přesun dočasně uloženého dokumentu ke zpracovateli ji znovu neodešle.
    * `stakeholder_completed` zahrnuje i dokončení přes pozvánku. Opakované uložení stejného dokončení ji znovu neodešle.
    * `submitted` je oznámení o připravenosti; nepotvrzuje, že požadavek ke zpracovateli skutečně dorazil. Samostatná událost `merchant.onboarding.ready` neexistuje.
    * `approved` platí pro jednotlivého zpracovatele. Schválení jedním zpracovatelem neznamená schválení všemi.
    * `rejected` a `action_required` vznikají výhradně při ručním posouzení ze strany Tapaya, nikdy přímo od zpracovatele plateb. Opakování stejného rozhodnutí neodešle novou událost, identity posuzovatelů nejsou zahrnuty a rozhodnutí nemění příznaky schválení zpracovatelem.
  </Accordion>
</Accordions>

Události onboardingu a stavu obchodníka popisují různé aspekty změny. Stejné uložení profilu nebo schválení zpracovatelem může vytvořit obě skupiny událostí, pokud odebíráte obě; nepředpokládejte jejich pořadí. Historické onboardingové aktivity se zpětně nedoplňují.

## Diagnostické testy [#diagnostic-tests]

Pomocí testovací akce v Platform odešlete `webhook.test`. Obsahuje `test: true`, `merchantId: null` a `data.message`, bez stavu platby či obchodníka. Nelze ho vybrat jako odběr událostí.

Doručení bez vytvoření platby ověřte podle stránky [Ověření a testování](/webhooks/receiving#send-a-test-webhook).