Webhook

I webhook DEUNA coprono due flussi server-to-server diversi: notifiche che pubblicano le variazioni dello stato del pagamento al tuo backend e callback sincroni che permettono a DEUNA di richiedere dati o logiche specifiche del merchant durante il checkout. Scegli il flusso in base a ciò che la tua integrazione deve realizzare.

I reindirizzamenti del browser, le callback dell'SDK e le callback da provider a DEUNA sono superfici di integrazione separate. Non usarle come prova di pagamento o come sostituti di questi flussi backend.

Notifiche sullo stato dell'ordine e del pagamentoChiedi ad Athia informazioni#

Le notifiche di stato inviano l'ultimo snapshot dell'ordine al tuo backend quando lo stato di pagamento normalizzato corrisponde a un evento sottoscritto per il merchant. Queste notifiche sono asincrone: il ciclo di vita del pagamento non attende il completamento della tua logica di business.

Configura la consegna degli stati

Definisci il contratto di consegna per ogni ambiente:

Gli eventi disponibili seguono il ciclo di vita del pagamento documentato in Flusso e stati di pagamento. La copertura degli eventi può differire per metodo di pagamento perché non tutti i metodi supportano ogni operazione o stato di pagamento.

Payload predefinito

Senza una trasformazione personalizzata del payload, DEUNA invia una richiesta HTTP POST con Content-Type: application/json e l'ordine corrente sotto la proprietà order :

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "processed",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "processed",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

L'ordine può contenere i dati del cliente, articolo, importo, pagamento, processore, frode, metadati e campo personalizzato associati a quella transazione. Tratta order.payment.data.status come lo stato di pagamento autorevole e usa order.token, order.order_ide gli identificatori di transazione applicabili per la riconciliazione.

Una configurazione specifica per merchant può cambiare il metodo HTTP, gli header, i parametri URL, gli stati sottoscritti e la forma del payload. Se è abilitata una configurazione personalizzata, implementa l'esatto contratto certificato per quel merchant invece di assumere il corpo predefinito.

Verifica la firma

La consegna corrente aggiunge un X-Signature header. Questo sostituisce esempi precedenti che si riferiscono a X-Deuna-Signature.

1. Leggi il corpo della richiesta non modificato prima che un framework lo analizzi o riserializzi.
2. Applica la procedura di verifica HMAC-SHA256 e Base64 certificata per il flusso e l'ambiente di consegna.
3. Confronta il valore calcolato con X-Signature utilizzando un confronto a tempo costante.
4. Rifiuta la richiesta prima dell'elaborazione se i valori non corrispondono.

Le notifiche di stato e i webhook dinamici non firmano sempre lo stesso input quando è abilitata la trasformazione del payload. Non riutilizzare un verificatore tra quei flussi finché l'input firmato e la derivazione della chiave non sono stati confermati durante la certificazione.

Mantieni le chiavi API private sul server. Non inserirle mai nel codice del browser, nelle applicazioni mobili, nei log o nelle risposte dei webhook.

Accetta e riconcilia

1. Verifica la firma prima di fidarti del payload.
2. Registra una chiave di deduplicazione che includa il token dell'ordine e l'evento o lo stato di pagamento risultante.
3. Restituisci una risposta 2xx di successo non appena la richiesta è accettata in modo durevole.
4. Rileggi o riconcilia lo stato autoritativo dell'ordine prima di un'azione irreversibile come evasione, annullamento, cattura, rimborso o un'altra operazione.
5. Ignora una notifica che sposterebbe il tuo record locale indietro da uno stato più recente.

Gli errori di consegna possono essere ritentati. Non presupporre una consegna esattamente una volta, un intervallo di ritentativo fisso o l'arrivo in ordine del ciclo di vita.

Webhook di checkout dinamicoChiedi ad Athia informazioni#

I webhook dinamici sono callback sincroni specifici del merchant. Quando il checkout attiva un evento configurato, DEUNA invia una richiesta firmata al tuo endpoint, convalida la risposta, applica solo gli aggiornamenti consentiti e restituisce il risultato configurato al checkout.

I webhook dinamici sono abilitati e configurati come parte dell'implementazione del merchant. Non vengono registrati dal codice del browser o mobile.

Flusso di configurazione ed esecuzione

Configura il webhook con DEUNA come parte della configurazione del tuo merchant. Concorda il nome dell'evento, la destinazione, le forme di richiesta e risposta, le regole di convalida e i campi che il callback può aggiornare. Dopo la configurazione, il checkout può eseguire l'evento attraverso lo stesso contratto concordato.

Se l'evento non è configurato per il merchant e l'ambiente, DEUNA non chiama il tuo endpoint. Considera un callback richiesto che non è stato eseguito come un problema di configurazione durante la certificazione.

Capacità di configurazione

Il seguente estratto mostra il nucleo di una definizione di calcolo della mancia. Si tratta di dati di configurazione, non di una richiesta che dovrebbe essere inviata dal browser:

{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

Durante l'esecuzione, il checkout può fornire input specifici dell'evento:

{
  "data": {
    "tip_amount": 500
  }
}

Senza un modello di payload, l'endpoint del merchant riceve quei dati dell'evento. Con un modello di payload, il modello può utilizzare sia l'ordine corrente che l'input dell'evento per costruire il JSON in uscita.

Implementa l'endpoint del merchant

Le chiamate dinamiche includono X-Signature e X-Deuna-Operation. Quando un modello di payload modifica il corpo in uscita, utilizza l'input di verifica della firma concordato durante la certificazione; non assumere che sia identico al contratto di notifica dello stato sopra.

Se la propagazione della risposta è disabilitata, la risposta predefinita del merchant può contenere order, shipping_ratee shipping_methods; DEUNA restituisce solo i campi di risposta selezionati dalla configurazione. Se la propagazione della risposta è abilitata, la risposta del merchant deve essere JSON valido e viene restituita direttamente come risultato dinamico.

Pattern pratici

Esempio di calcolo della mancia

Questo esempio mostra il percorso completo dal checkout al merchant per un evento di mancia configurato.

Per una definizione di mancia, autorizza solo l'importo e i campi personalizzati che si prevede che la risposta del merchant modifichi. L'endpoint del merchant rimane responsabile del calcolo di un totale dell'ordine coerente.

Testare in ambiente sandboxChiedi ad Athia informazioni#

Testa le notifiche di stato

Testa un webhook dinamico

Documentazione correlataChiedi ad Athia informazioni#