Tipi di evento

Selezioni tra questi 23 tipi di evento oppure abiliti un'iscrizione a tutti i tipi. Ogni notifica utilizza la struttura comune dell'evento; questa pagina mostra cosa inserisce in data ciascuna famiglia di eventi.

Famiglie di eventi

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

Questi eventi descrivono l'intero pagamento, nei diversi processori di pagamento e canali supportati. Contengono data.payment, inclusi status e statusId del pagamento.

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:

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

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.

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

Gli eventi dell'esercente contengono data.merchant con id, token e un'istantanea dello stato salvato dell'esercente.

{
  "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

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.

{
  "onboarding": {
    "status": "action_required",
    "reason": "The submitted company document is no longer valid.",
    "requiredAction": "Upload a current company registration document."
  }
}

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

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.