# Tipi di evento (/it/webhooks/events)
Selezioni tra questi 23 tipi di evento oppure abiliti un'iscrizione a tutti i tipi. Ogni notifica utilizza la [struttura comune dell'evento](/webhooks#event-envelope); questa pagina mostra cosa inserisce in `data` ciascuna famiglia di eventi.
## Famiglie di eventi [#event-families]
| Famiglia | Eventi | `data` contiene |
| ------------------------------------------------- | ------ | -------------------- |
| [Pagamenti](#payments) | 7 | `payment` |
| [Rimborsi](#refunds) | 6 | `payment` e `refund` |
| [Esercenti](#merchants) | 2 | `merchant` |
| [Onboarding dell'esercente](#merchant-onboarding) | 8 | `onboarding` |
La maggior parte delle integrazioni inizia con `payment.succeeded`, `payment.failed` e `payment.refund.succeeded`. Le piattaforme che gestiscono l'onboarding degli esercenti aggiungono `merchant.onboarding.approved` e `merchant.onboarding.action_required`.
## Pagamenti [#payments]
Questi eventi descrivono l'intero pagamento, nei diversi processori di pagamento e canali supportati. Contengono `data.payment`, inclusi `status` e `statusId` del pagamento.
| Evento | Quando viene inviato |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `payment.created` | Viene salvato un pagamento. |
| `payment.updated` | Lo stato passa a `pending` o a un altro stato senza un nome di evento dedicato. Non è una notifica per ogni modifica ai campi. |
| `payment.succeeded` | Lo stato passa a `success`. |
| `payment.failed` | L'intero pagamento passa a `failed`, anziché il fallimento di un singolo tentativo di pagamento. |
| `payment.canceled` | Lo stato passa a `cancelled`. |
| `payment.refunded` | Tapaya contrassegna il pagamento come `refunded`. |
| `payment.action_required` | Lo stato passa a `actionNeeded`. |
La creazione di un pagamento in uno stato diverso da quello in attesa invia sia `payment.created` sia l'evento di stato corrispondente, se è iscritto a entrambi. Salvare nuovamente lo stesso stato non invia né un nuovo evento di stato né `payment.updated`.
Nelle istantanee di pagamenti e rimborsi, `status` e `statusId` assumono questi valori:
| `statusId` | `status` | Significato |
| ---------- | -------------- | ------------------------------------------------------- |
| `1` | `pending` | L'elaborazione non ha ancora raggiunto un esito finale. |
| `2` | `success` | Il pagamento o rimborso è riuscito. |
| `3` | `cancelled` | Il pagamento o rimborso è stato annullato. |
| `4` | `refunded` | Tapaya ha contrassegnato il pagamento come rimborsato. |
| `5` | `failed` | Il pagamento o rimborso è fallito. |
| `6` | `actionNeeded` | È necessaria un'ulteriore azione. |
Gli ID di stato futuri sconosciuti utilizzano `status: "unknown"` e mantengono il proprio `statusId` numerico. I nomi degli eventi utilizzano `succeeded` e `canceled`; i valori di stato utilizzano `success` e `cancelled`.
## Rimborsi [#refunds]
Gli eventi di rimborso contengono sia `data.payment` sia `data.refund`. Il rimborso ha ID, token, stato, importi e valute richiesti e di regolamento propri. Utilizzi l'ID del rimborso per seguirlo indipendentemente dal pagamento a cui appartiene.
| Evento | Quando viene inviato |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `payment.refund.created` | Viene salvato un rimborso. |
| `payment.refund.updated` | Lo stato passa a `pending` o a un altro stato senza un nome di evento dedicato. |
| `payment.refund.succeeded` | Lo stato passa a `success`. |
| `payment.refund.failed` | Lo stato passa a `failed`. |
| `payment.refund.canceled` | Lo stato passa a `cancelled`. |
| `payment.refund.action_required` | Lo stato passa a `actionNeeded`. |
La creazione di un rimborso in uno stato diverso da quello in attesa può inviare anche l'evento di stato corrispondente. Un rimborso riuscito, da solo, non descrive lo stato finale dell'intero pagamento: verifichi `data.payment.status` ed eventuali notifiche separate `payment.refunded`.
## Esercenti [#merchants]
Gli eventi dell'esercente contengono `data.merchant` con `id`, `token` e un'istantanea dello stato salvato dell'esercente.
| Evento | Quando viene inviato |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant.created` | Viene creato un esercente nella Sua organizzazione. |
| `merchant.status_changed` | Cambiano l'attivazione, lo stato di record di base dell'esercente, la presenza del profilo oppure un account, un invio, un'approvazione o un rifiuto presso un processore. |
```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` indica che esiste un profilo. Non significa che un processore abbia approvato l'esercente o che ogni metodo di pagamento sia pronto.
* Non sono inclusi gli identificatori degli account presso il processore né i messaggi privati di rifiuto del processore. L'ID del processore nell'esempio è illustrativo.
* Aggiornare valori invariati o modificare dettagli dell'esercente non pertinenti non invia alcun evento. Non esistono un evento `merchant.updated` né un evento di eliminazione dell'esercente.
## Onboarding dell'esercente [#merchant-onboarding]
Gli eventi di onboarding contengono `data.onboarding`. Il relativo `status` corrisponde all'ultimo segmento del nome dell'evento e alcuni eventi aggiungono i campi indicati di seguito.
| Evento | Quando viene inviato |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant.onboarding.started` | Vengono salvati il primo profilo dell'esercente e i dati di onboarding. |
| `merchant.onboarding.profile_completed` | Viene salvato il primo profilo completo dell'esercente. |
| `merchant.onboarding.document_added` | Viene salvato un nuovo documento. Aggiunge `documentId`, `documentTypeId`, `paymentProcessorId` e `source: "cache"` per un documento archiviato temporaneamente. |
| `merchant.onboarding.stakeholder_completed` | Vengono completati i dati di onboarding di un soggetto coinvolto. Aggiunge `stakeholderId`. |
| `merchant.onboarding.submitted` | L'onboarding è pronto per l'invio a un processore. Aggiunge `paymentProcessorId`. |
| `merchant.onboarding.approved` | Un account presso un processore viene approvato per la prima volta. Aggiunge `paymentProcessorId`. |
| `merchant.onboarding.rejected` | Tapaya rifiuta l'onboarding dopo una revisione manuale. Aggiunge `reason`, con `requiredAction` impostato su `null`. |
| `merchant.onboarding.action_required` | Tapaya richiede ulteriori informazioni dopo una revisione manuale. Aggiunge `reason` e `requiredAction`. |
```json title="data"
{
"onboarding": {
"status": "action_required",
"reason": "The submitted company document is no longer valid.",
"requiredAction": "Upload a current company registration document."
}
}
```
* `profile_completed` attualmente arriva insieme a `started`. Nessuno dei due indica l'approvazione del processore.
* `document_added` contiene metadati, non il file. Trasferire un documento dall'archivio temporaneo al processore non lo invia nuovamente.
* `stakeholder_completed` copre anche il completamento tramite un invito. Salvare nuovamente lo stesso completamento non lo invia di nuovo.
* `submitted` è la notifica dello stato di preparazione; non conferma che una richiesta sia giunta al processore. Non esiste un evento separato `merchant.onboarding.ready`.
* `approved` vale per singolo processore. L'approvazione di un processore non implica l'approvazione di tutti.
* `rejected` e `action_required` provengono esclusivamente dalla revisione manuale di Tapaya, mai direttamente da un processore di pagamento. Ripetere una decisione non invia un nuovo evento, le identità dei revisori non sono incluse e la decisione non modifica gli indicatori di approvazione del processore.
Gli eventi di onboarding e di stato dell'esercente descrivono aspetti diversi di una modifica. Lo stesso profilo salvato o la stessa approvazione del processore possono produrre entrambe le famiglie di eventi quando è iscritto a entrambe; non presuma un ordine tra di esse. Gli eventi non vengono generati retroattivamente per attività di onboarding precedenti.
## Test diagnostici [#diagnostic-tests]
Utilizzi l'azione di test della Platform per inviare `webhook.test`. Include `test: true`, `merchantId: null` e `data.message`, senza alcuno stato di pagamento o esercente. Non può essere selezionato come iscrizione agli eventi.
Per verificare la consegna senza creare un pagamento, si veda [Verificare e testare](/webhooks/receiving#send-a-test-webhook).