Webhook

DEUNA utilizza webhook per inviare al tuo backend un'istantanea aggiornata dell'ordine quando cambia lo stato di pagamento o dell'ordine configurato. Il corpo predefinito per l'utente commerciale contiene l'ordine stesso. Non è un envelope di evento nello stile di Stripe.

Come funziona#

Configura la destinazione#

Per Purchase V2, fornisci l'URL del ricevitore HTTPS nel campo di notifica dell'ordine asincrono mostrato di seguito:

{
  "order": {
    "order_id": "merchant-order-123",
    "webhook_urls": {
      "notify_order": "https://merchant.example.com/webhooks/deuna/orders"
    }
  }
}

DEUNA memorizza un URL a livello di ordine e può completare un valore mancante utilizzando la configurazione del merchant definita durante l’onboarding. L’attuale flusso di notifiche firmate utilizza la destinazione e la sottoscrizione agli stati a livello di merchant; conferma con il tuo TAM l’URL effettivo per ogni ambiente. I campi URL del webhook asincrono e sincrono sono mutuamente esclusivi per un ordine.

Le notifiche sullo stato dell’ordine non utilizzano una risorsa generica di registrazione degli endpoint webhook. Configura il campo dell’ordine riportato sopra oppure utilizza la configurazione a livello di merchant concordata con il tuo Technical Account Manager (TAM) DEUNA. Le callback dinamiche del checkout utilizzano l’API separata descritta di seguito.

Flussi di consegna supportati#

Utilizza la consegna asincrona a meno che DEUNA non abbia abilitato e certificato esplicitamente un altro modalità per la tua integrazione.

DEUNA crea notifiche candidate quando cambiano i valori di stato supportati dell’ordine o del pagamento, quando cambia il processore selezionato e per le decisioni di frode o 3DS supportate. La sottoscrizione configurata determina quindi quali stati di pagamento vengono inviati. Non tutte le transizioni di stato generano un webhook.

Questo meccanismo copre gli aggiornamenti dell'acquisto e i risultati finali delle operazioni di cattura, rimborso e annullamento asincrone supportate. Consulta Flusso e stati di pagamento per gli stati pubblici e Acquisizione, rimborso e annullamento asincroni per i flussi di queste operazioni.

Webhook di checkout dinamico#

I webhook dinamici del checkout costituiscono un flusso sincrono separato. Consentono a un’azione del checkout di chiamare un endpoint del merchant in base al nome dell’evento, convalidare o trasformare la risposta, aggiornare campi selezionati nell’ordine tokenizzato e restituire al chiamante i valori selezionati o la risposta del merchant.

Utilizzare questo flusso per azioni di checkout specifiche del merchant, come commissioni, punti fedeltà, donazioni e comportamento personalizzato dei coupon. Non utilizzarlo come sostituto per la consegna asincrona dello stato di pagamento.

L'API Gateway effettiva espone queste operazioni di webhook dinamico:

La richiesta di esecuzione può includere input specifici per l'evento in data:

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

DEUNA carica la configurazione attiva per il merchant e il nome dell’evento, quindi chiama l’URL configurato del merchant. La configurazione può selezionare il metodo HTTP, le intestazioni, i parametri URL e di query, i modelli di payload e risposta, le convalide, i campi dell’ordine da aggiornare, i campi di risposta da restituire e se propagare la risposta del merchant.

La richiesta del merchant include X-Signature e X-Deuna-Operation. L’esecuzione è sincrona: i timeout del merchant, le risposte non valide, gli errori di convalida e le risposte HTTP non riuscite vengono restituiti al chiamante. Se il merchant non dispone di una configurazione per il nome dell’evento, DEUNA restituisce una risposta di successo vuota senza chiamare un endpoint del merchant.

La configurazione del webhook dinamico è specifica del merchant e può modificare un ordine. Prima di abilitarla, conferma con il tuo TAM il nome dell’evento, l’autenticazione, i campi consentiti, i modelli, le convalide, il timeout e la risposta propagata. Consulta catalogo degli endpoint per l'inventario del gateway.

Payload predefinito per lo stato dell'ordine#

La richiesta predefinita è un POST con Content-Type: application/json e ha la seguente forma:

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

L’oggetto ordine completo può contenere gli stessi campi relativi a ordine, cliente, articolo, importo, pagamento, processore, frode e metadati restituiti in una risposta dell’ordine.

• Stato di pagamento autorevole: order.payment.data.status
• Identificatori aziendali stabili: order.token, order.order_ide gli identificatori di transazione applicabili

Le configurazioni personalizzate del commerciante possono trasformare questo corpo. Se il tuo ricevitore non utilizza la forma predefinita mostrata sopra, conferma il payload esatto con il tuo TAM.

Autentica la consegna dello stato dell'ordine#

Il flusso di consegna corrente invia questo header di richiesta:

X-Signature: <signature>

La firma è derivata da HMAC-SHA256 e codifica Base64 dal payload JSON e dalle credenziali del commerciante.

Valida il payload di richiesta esatto con le credenziali e la procedura di verifica fornite durante l'onboarding prima di fidarti del payload. Non fare affidamento su nomi di header alternativi o su helper SDK non documentati.

Riconoscere e elaborare#

Restituisci lo stato HTTP 200 o un'altra risposta 2xx non appena la richiesta è stata validata e memorizzata in coda. Puoi restituire un corpo vuoto. Se restituisci JSON, DEUNA accetta questa forma di risposta:

{
  "status": "success",
  "data": {
    "order_id": "merchant-order-123"
  }
}

Restituisci solo un identificatore di ordine diverso e non vuoto in questa risposta solo quando intendi che DEUNA sostituisca l'identificatore di ordine del commerciante.

Errori di rete, timeout e risposte di errore possono causare un nuovo tentativo di consegna. Non fare affidamento su un intervallo di retry fisso e non presumere l'ordine di consegna. Rendere il processo idempotente e confrontare ogni snapshot con lo stato di pagamento più recente noto.

Testare in ambiente sandbox#

1. Esporre un ricevitore HTTPS che registra le intestazioni della richiesta e il corpo non modificato.
2. Imposta l'URL di notifica dell'ordine asincrono su una richiesta di Purchase V2 di test, a meno che non sia già configurato un URL a livello di commerciante.
3. Completare un pagamento o una cattura, rimborso o annullamento asincrono che modifica lo stato del pagamento.
4. Verifica la forma del payload, la copertura dello stato configurata, il comportamento dell'header firmato, l'acknowledgement e la gestione dei duplicati.

Il flusso di stato dell'ordine non fornisce l'API generica /webhook_endpoints o il comando CLI locale. Testarlo producendo veri cambiamenti nello stato sandbox. Testare i webhook di checkout dinamico attraverso i loro percorsi di configurazione e di esecuzione verificati.