# Typy udalostí (/sk/webhooks/events)



Vyberte si z týchto 23 typov udalostí alebo zapnite odber všetkých typov. Každé oznámenie používa [spoločnú obálku udalosti](/webhooks#event-envelope); táto stránka ukazuje, čo jednotlivé skupiny udalostí vkladajú do `data`.

## Skupiny udalostí [#event-families]

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

Väčšina integrácií začína udalosťami `payment.succeeded`, `payment.failed` a `payment.refund.succeeded`. Platformy, ktoré zabezpečujú onboarding obchodníkov, pridávajú `merchant.onboarding.approved` a `merchant.onboarding.action_required`.

## Platby [#payments]

Tieto udalosti opisujú celú platbu naprieč podporovanými spracovateľmi platieb a kanálmi. Obsahujú `data.payment` vrátane polí `status` a `statusId` platby.

| Udalosť                                                              | Kedy sa odosiela                                                                                                        |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.created`</span>         | Platba sa uloží.                                                                                                        |
| <span className="whitespace-nowrap">`payment.updated`</span>         | Jej stav sa zmení na `pending` alebo iný stav bez vyhradeného názvu udalosti. Nejde o oznámenie pri každej úprave poľa. |
| <span className="whitespace-nowrap">`payment.succeeded`</span>       | Jej stav sa zmení na `success`.                                                                                         |
| <span className="whitespace-nowrap">`payment.failed`</span>          | Celá platba prejde do stavu `failed`, nejde o zlyhanie jednotlivého pokusu o platbu.                                    |
| <span className="whitespace-nowrap">`payment.canceled`</span>        | Jej stav sa zmení na `cancelled`.                                                                                       |
| <span className="whitespace-nowrap">`payment.refunded`</span>        | Tapaya označí platbu ako `refunded`.                                                                                    |
| <span className="whitespace-nowrap">`payment.action_required`</span> | Jej stav sa zmení na `actionNeeded`.                                                                                    |

Vytvorenie platby v inom než čakajúcom stave odošle `payment.created` aj zodpovedajúcu udalosť stavu, ak odoberáte obe. Opätovné uloženie rovnakého stavu neodošle novú udalosť stavu ani `payment.updated`.

Polia `status` a `statusId` nadobúdajú v snímkach platieb a refundácií tieto hodnoty:

| `statusId` | `status`       | Význam                                        |
| ---------- | -------------- | --------------------------------------------- |
| `1`        | `pending`      | Spracovanie ešte nedosiahlo konečný výsledok. |
| `2`        | `success`      | Platba alebo refundácia bola úspešná.         |
| `3`        | `cancelled`    | Platba alebo refundácia bola zrušená.         |
| `4`        | `refunded`     | Tapaya označila platbu ako refundovanú.       |
| `5`        | `failed`       | Platba alebo refundácia zlyhala.              |
| `6`        | `actionNeeded` | Je potrebný ďalší krok.                       |

Neznáme budúce ID stavov používajú `status: "unknown"` a zachovávajú svoje číselné `statusId`. Názvy udalostí používajú `succeeded` a `canceled`; hodnoty stavov používajú `success` a `cancelled`.

## Refundácie [#refunds]

Udalosti refundácií obsahujú `data.payment` aj `data.refund`. Refundácia má vlastné ID, token, stav a požadované a zúčtovacie sumy a meny. Pomocou ID refundácie ju sledujte nezávisle od nadradenej platby.

| Udalosť                                                                     | Kedy sa odosiela                                                              |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.refund.created`</span>         | Refundácia sa uloží.                                                          |
| <span className="whitespace-nowrap">`payment.refund.updated`</span>         | Jej stav sa zmení na `pending` alebo iný stav bez vyhradeného názvu udalosti. |
| <span className="whitespace-nowrap">`payment.refund.succeeded`</span>       | Jej stav sa zmení na `success`.                                               |
| <span className="whitespace-nowrap">`payment.refund.failed`</span>          | Jej stav sa zmení na `failed`.                                                |
| <span className="whitespace-nowrap">`payment.refund.canceled`</span>        | Jej stav sa zmení na `cancelled`.                                             |
| <span className="whitespace-nowrap">`payment.refund.action_required`</span> | Jej stav sa zmení na `actionNeeded`.                                          |

Vytvorenie refundácie v inom než čakajúcom stave môže odoslať aj zodpovedajúcu udalosť stavu. Úspešná refundácia sama osebe neopisuje konečný stav celej platby: skontrolujte `data.payment.status` a prípadné samostatné oznámenie `payment.refunded`.

## Obchodníci [#merchants]

Udalosti obchodníkov obsahujú `data.merchant` s poľami `id`, `token` a snímkou uloženého stavu obchodníka.

| Udalosť                                                              | Kedy sa odosiela                                                                                                                          |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.created`</span>        | Vo vašej organizácii sa vytvorí obchodník.                                                                                                |
| <span className="whitespace-nowrap">`merchant.status_changed`</span> | Zmení sa aktivácia, stav základného záznamu obchodníka, prítomnosť profilu alebo účet, podanie, schválenie či zamietnutie u spracovateľa. |

```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á to, že spracovateľ obchodníka schválil alebo že sú pripravené všetky platobné metódy.
* Identifikátory účtov u spracovateľov ani ich súkromné správy o zamietnutí nie sú zahrnuté. ID spracovateľa vyššie je ilustračné.
* Uloženie nezmenených hodnôt alebo úprava nesúvisiacich údajov obchodníka neodošle žiadnu udalosť. Udalosť `merchant.updated` ani udalosť odstránenia obchodníka neexistuje.

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

Udalosti onboardingu obsahujú `data.onboarding`. Jeho `status` zodpovedá poslednej časti názvu udalosti a niektoré udalosti pridávajú polia uvedené nižšie.

| Udalosť                                                                                | Kedy sa odosiela                                                                                                                         |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.onboarding.started`</span>               | Uloží sa prvý profil obchodníka a údaje onboardingu.                                                                                     |
| <span className="whitespace-nowrap">`merchant.onboarding.profile_completed`</span>     | Uloží sa prvý úplný profil obchodníka.                                                                                                   |
| <span className="whitespace-nowrap">`merchant.onboarding.document_added`</span>        | Uloží sa nový dokument. Pridáva `documentId`, `documentTypeId`, `paymentProcessorId` a pri dočasne uloženom dokumente `source: "cache"`. |
| <span className="whitespace-nowrap">`merchant.onboarding.stakeholder_completed`</span> | Údaje onboardingu zainteresovanej osoby sa dokončia. Pridáva `stakeholderId`.                                                            |
| <span className="whitespace-nowrap">`merchant.onboarding.submitted`</span>             | Onboarding je pripravený na podanie spracovateľovi. Pridáva `paymentProcessorId`.                                                        |
| <span className="whitespace-nowrap">`merchant.onboarding.approved`</span>              | Účet u spracovateľa je prvýkrát schválený. Pridáva `paymentProcessorId`.                                                                 |
| <span className="whitespace-nowrap">`merchant.onboarding.rejected`</span>              | Tapaya po manuálnej kontrole zamietne onboarding. Pridáva `reason`, pričom `requiredAction` má hodnotu `null`.                           |
| <span className="whitespace-nowrap">`merchant.onboarding.action_required`</span>       | Tapaya si po manuálnej kontrole vyžiada ďalšie informácie. Pridáva `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é prípady pre jednotlivé udalosti" id="onboarding-edge-cases">
    * `profile_completed` momentálne prichádza spolu so `started`. Ani jedna z nich neznamená schválenie spracovateľom.
    * `document_added` obsahuje metadáta, nie samotný súbor. Presunutie dočasne uloženého dokumentu k spracovateľovi udalosť znova neodošle.
    * `stakeholder_completed` zahŕňa aj dokončenie prostredníctvom pozvánky. Opätovné uloženie rovnakého dokončenia udalosť znova neodošle.
    * `submitted` je oznámenie o pripravenosti; nepotvrdzuje, že požiadavka dorazila k spracovateľovi. Samostatná udalosť `merchant.onboarding.ready` neexistuje.
    * `approved` platí pre každého spracovateľa zvlášť. Schválenie jedným spracovateľom neznamená schválenie všetkými.
    * `rejected` a `action_required` pochádzajú iba z manuálnej kontroly Tapaya, nikdy priamo od spracovateľa platieb. Zopakovanie rozhodnutia neodošle novú udalosť, identity kontrolórov nie sú zahrnuté a rozhodnutie nemení príznaky schválenia spracovateľom.
  </Accordion>
</Accordions>

Udalosti onboardingu a stavu obchodníka opisujú rôzne aspekty zmeny. Rovnaký uložený profil alebo schválenie spracovateľom môže vytvoriť oba druhy udalostí, ak odoberáte oba; nepredpokladajte ich poradie. Udalosti pre historickú aktivitu onboardingu sa spätne nedopĺňajú.

## Diagnostické testy [#diagnostic-tests]

Pomocou testovacej akcie v Platform odošlite `webhook.test`. Obsahuje `test: true`, `merchantId: null` a `data.message`, bez stavu platby alebo obchodníka. Nemožno ho vybrať ako odber udalostí.

V časti [Overenie a testovanie](/webhooks/receiving#send-a-test-webhook) nájdete postup, ako skontrolovať doručovanie bez vytvorenia platby.