Webhook
Riceva notifiche firmate quando cambiano pagamenti, rimborsi, esercenti e onboarding.
I webhook notificano al Suo server le modifiche nell'organizzazione Tapaya. Utilizzi la stessa integrazione per i pagamenti in presenza e online, indipendentemente dal processore di pagamento.
Funzionamento
TapayaConfiguri una destinazione HTTPS per organizzazione e selezioni gli eventi necessari. Tapaya invia una richiesta HTTP POST con un'istantanea JSON e una firma. Verifichi la firma, memorizzi l'evento e restituisca una risposta di esito positivo prima di elaborare la logica applicativa.
Può iscriversi a singoli tipi o a tutti i tipi supportati. Un'iscrizione a tutti i tipi riceve anche i nuovi tipi supportati in futuro, quindi ignori quelli che l'applicazione non riconosce.
Integrazione rapida
Salvare una destinazione
Nella Platform, apra API Keys, poi Webhooks. Inserisca l'URL HTTPS, scelga gli eventi necessari e salvi. Copi subito il signing secret (chiave di firma): viene mostrato una sola volta. Si veda Configurazione.
Verificare ogni richiesta
Calcoli un HMAC-SHA256 del timestamp, di un punto e del corpo originale con il Suo signing secret, e lo confronti con X-Tapaya-Signature. Si veda Controllare la firma.
Memorizzare l'evento, poi restituire 2xx
Salvi l'evento con un id univoco, risponda 2xx entro 10 secondi e lo elabori in seguito. Si veda Memorizzare e confermare.
Inviare un webhook di test
Nella stessa pagina, utilizzi l'azione di test per inviare un webhook.test firmato. Si veda Inviare un webhook di test.
Struttura comune dell'evento
Ogni evento utilizza questa struttura comune. L'istantanea della risorsa in data dipende dal tipo di evento.
{
"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
}
}
}| Campo | Significato |
|---|---|
id | ID univoco dell'evento. Lo utilizzi per deduplicare le consegne. I tentativi successivi mantengono lo stesso ID. |
type | Nome dell'evento dal catalogo degli eventi. |
apiVersion | Identificatore dello schema del payload, attualmente la stringa "1". |
organizationId | Organizzazione a cui appartiene l'evento. Verifichi che corrisponda alla Sua integrazione. |
merchantId | Esercente a cui appartiene la risorsa. Può essere null per pagamenti meno recenti la cui titolarità non è stata determinata o per un test diagnostico. |
createdAt | Ora UTC in cui è stato acquisito l'evento, anziché l'ora di consegna. |
data | Istantanea immutabile della risorsa al momento dell'acquisizione dell'evento. |
Gli importi sono numeri interi espressi nell'unità minima della valuta del campo. Ad esempio, 10000 con l'ID numerico ISO 4217 della valuta 203 indica 100,00 CZK. Gli importi richiesti e di regolamento possono utilizzare valute diverse.
Ogni tipo di evento inserisce la propria istantanea in data. Per ogni struttura del payload e ogni valore di stato, si veda Tipi di evento.
Regole di consegna
Tapaya invia un evento non appena la modifica viene salvata e continua a inviarlo finché il Suo server non risponde 2xx.
| Regola | Comportamento |
|---|---|
| Conferma | Qualsiasi risposta 2xx entro 10 secondi. I reindirizzamenti non vengono seguiti. |
| Nuovi tentativi | Fino a 12 tentativi in circa 20 ore, con attese di 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 e 360 minuti. |
| Ordine | Non garantito. La consegna avviene almeno una volta, quindi si aspetti duplicati e istantanee meno recenti. |
| Concorrenza | 2 richieste alla volta per organizzazione, condivise con i test manuali. Gli altri eventi attendono in coda. |
Una consegna fallita non cambia mai il pagamento stesso e le consegne passate non possono essere reinviate. Per recuperare dopo un'interruzione, legga lo stato corrente tramite le API di pagamento e degli esercenti.