Webhooky
Přijímejte podepsaná oznámení o změnách plateb, vratek, obchodníků a onboardingu.
Webhooky oznamují vašemu serveru změny v organizaci Tapaya. Stejnou integraci použijete pro platby v prodejně i online bez ohledu na zpracovatele plateb.
Jak to funguje
TapayaPro každou organizaci nastavte jednu cílovou HTTPS adresu a vyberte požadované události. Tapaya odešle HTTP POST se snímkem dat v JSON a podpisem. Ověřte podpis, uložte událost a vraťte úspěšnou odpověď ještě před spuštěním vlastní aplikační logiky.
Můžete odebírat jednotlivé typy nebo všechny podporované typy. Odběr všech typů zahrnuje i typy přidané v budoucnu, proto ignorujte typy, které vaše aplikace nezná.
Rychlá integrace
Uložte cílovou adresu
V Platform otevřete API Keys a poté Webhooks. Zadejte HTTPS URL, vyberte požadované události a uložte. Hned zkopírujte podpisový klíč; zobrazí se jen jednou. Viz Nastavení.
Ověřte každý požadavek
Vypočítejte HMAC-SHA256 z časového razítka, tečky a původního těla pomocí podpisového klíče a porovnejte ho s X-Tapaya-Signature. Viz Ověřte podpis.
Uložte událost a vraťte 2xx
Uložte událost s jedinečným id, odpovězte 2xx do 10 sekund a zpracujte ji až poté. Viz Uložte a potvrďte.
Odešlete testovací webhook
Na stejné stránce odešlete testovací akcí podepsaný webhook.test. Viz Odešlete testovací webhook.
Obálka události
Každá událost používá tuto společnou strukturu. Snímek objektu uvnitř data závisí na typu události.
{
"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 události. Použijte ho k odstranění duplicitních doručení. Při opakování zůstává stejné. |
type | Název události z katalogu událostí. |
apiVersion | Identifikátor schématu payloadu, aktuálně řetězec "1". |
organizationId | Organizace, které událost patří. Ověřte, že odpovídá vaší integraci. |
merchantId | Obchodník, kterému objekt patří. U starších plateb s neurčeným vlastníkem nebo diagnostického testu může být null. |
createdAt | Čas zachycení události v UTC, nikoli čas doručení. |
data | Neměnný snímek objektu v okamžiku zachycení. |
Částky jsou celá čísla v nejmenších jednotkách měny daného pole. Například 10000 s číselným ID měny ISO 4217 203 znamená 100,00 CZK. Požadovaná a zúčtovaná částka mohou používat různé měny.
Každý typ události vkládá do data vlastní snímek. Všechny tvary payloadu a hodnoty stavu najdete na stránce Typy událostí.
Pravidla doručování
Tapaya odešle událost, jakmile se její změna uloží, a odesílá ji znovu, dokud váš server neodpoví 2xx.
| Pravidlo | Chování |
|---|---|
| Potvrzení | Jakákoli odpověď 2xx do 10 sekund. Přesměrování se nenásledují. |
| Opakování | Nejvýše 12 pokusů během přibližně 20 hodin s prodlevami 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 a 360 minut. |
| Pořadí | Není zaručené. Doručení probíhá alespoň jednou, počítejte proto s duplicitami a staršími snímky. |
| Souběh | 2 požadavky současně na organizaci, sdílené s ručními testy. Ostatní události čekají ve frontě. |
Neúspěšné doručení nikdy nemění samotnou platbu a minulá doručení nelze odeslat znovu. Pro dohnání stavu po výpadku načtěte aktuální stav přes API plateb a obchodníků.