Webhooky
Prijímajte podpísané oznámenia o zmenách platieb, refundácií, obchodníkov a onboardingu.
Webhooky oznamujú vášmu serveru zmeny vo vašej organizácii Tapaya. Používajte rovnakú integráciu pre platby v predajni aj online platby bez ohľadu na spracovateľa platieb.
Ako to funguje
TapayaNakonfigurujte jednu HTTPS cieľovú adresu pre každú organizáciu a vyberte požadované udalosti. Tapaya odošle HTTP POST so snímkou vo formáte JSON a podpisom. Overte podpis, uložte udalosť a vráťte úspešnú odpoveď ešte pred spracovaním vlastnej obchodnej logiky.
Môžete sa prihlásiť na odber jednotlivých typov alebo všetkých podporovaných typov. Odber všetkých typov bude v budúcnosti prijímať aj novo podporované typy, preto ignorujte typy, ktoré vaša aplikácia nepozná.
Rýchla integrácia
Uložte cieľovú adresu
V Platform otvorte API Keys a potom Webhooks. Zadajte svoju HTTPS URL, vyberte požadované udalosti a uložte. Signing secret (podpisový kľúč) si skopírujte hneď; zobrazí sa iba raz. Pozrite si Konfigurácia.
Overte každú požiadavku
Vypočítajte HMAC-SHA256 z časovej pečiatky, bodky a pôvodného tela pomocou svojho signing secret a porovnajte ho s X-Tapaya-Signature. Pozrite si Skontrolujte podpis.
Uložte udalosť a potom vráťte 2xx
Uložte udalosť s jedinečným id, do 10 sekúnd odpovedzte 2xx a spracujte ju až potom. Pozrite si Uložte a potvrďte.
Odošlite testovací webhook
Na tej istej stránke použite testovaciu akciu na odoslanie podpísaného webhook.test. Pozrite si Odošlite testovací webhook.
Obálka udalosti
Každá udalosť používa túto spoločnú štruktúru. Snímka zdroja v poli data závisí od typu udalosti.
{
"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
}
}
}| Pole | Význam |
|---|---|
id | Jedinečné ID udalosti. Použite ho na deduplikáciu doručení. Opakované pokusy zachovávajú rovnaké ID. |
type | Názov udalosti z katalógu udalostí. |
apiVersion | Identifikátor schémy payloadu, momentálne reťazec "1". |
organizationId | Organizácia, ktorej udalosť patrí. Skontrolujte, či zodpovedá vašej integrácii. |
merchantId | Obchodník, ktorému zdroj patrí. Pri starších platbách s neurčeným vlastníctvom alebo pri diagnostickom teste môže byť null. |
createdAt | Čas UTC zachytenia udalosti, nie čas jej doručenia. |
data | Nemenná snímka zdroja v čase zachytenia. |
Sumy sú celé čísla v najmenších jednotkách meny daného poľa. Napríklad 10000 s číselným ID meny ISO 4217 203 znamená 100,00 CZK. Požadované a zúčtovacie sumy môžu byť v rôznych menách.
Každý typ udalosti vkladá do data vlastnú snímku. Všetky štruktúry payloadu a hodnoty stavov nájdete v časti Typy udalostí.
Pravidlá doručovania
Tapaya odošle udalosť hneď po uložení jej zmeny a posiela ju dovtedy, kým váš server neodpovie 2xx.
| Pravidlo | Správanie |
|---|---|
| Potvrdenie | Akákoľvek odpoveď 2xx do 10 sekúnd. Presmerovania sa nesledujú. |
| Opakované pokusy | Najviac 12 pokusov počas približne 20 hodín s čakaním 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 a 360 minút. |
| Poradie | Nie je zaručené. Doručenie prebehne aspoň raz, preto počítajte s duplicitami a staršími snímkami. |
| Súbeh | 2 požiadavky naraz na organizáciu, spoločne s ručnými testami. Ostatné udalosti čakajú vo fronte. |
Neúspešné doručenie nikdy nezmení samotnú platbu a minulé doručenia nie je možné odoslať znova. Ak potrebujete po výpadku dobehnúť zmeny, načítajte aktuálny stav cez API pre platby a obchodníkov.