Webhook
Ricevi notifiche firmate sullo stato dei pagamenti e integra callback configurabili per il checkout.
In questa pagina
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.
| Flusso | Quando viene eseguito | Usalo per |
|---|---|---|
| Notifica sullo stato dell'ordine e del pagamento | Dopo che uno stato di pagamento sottoscritto cambia | Aggiorna lo stato di evasione, riconciliazione e ordine cliente senza dover effettuare polling continuo. |
| Webhook di checkout dinamico | Mentre il checkout è in attesa di una risposta del merchant | Applica coupon o sconti in base alla carta, calcola mance o imposte, recupera informazioni sulla spedizione o convalida i dati. |
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 pagamento#
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.
stato_pagamentoe DEUNA verifica l'abbonamento del merchant.Configura la consegna degli stati
Definisci il contratto di consegna per ogni ambiente:
| Impostazione | Cosa definire |
|---|---|
| Destinazione | L'endpoint HTTPS che accetta le notifiche di stato. |
| Eventi | Il payment.<status> eventi richiesti dal tuo ciclo di vita dell'ordine. |
| Contratto di richiesta | Qualsiasi header statico, parametri URL e trasformazione del payload approvata. |
| Gestione degli errori | Il comportamento di conferma, riprova, monitoraggio e riconciliazione concordato per l'integrazione. |
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.
- Leggi il corpo della richiesta non modificato prima che un framework lo analizzi o riserializzi.
- Applica la procedura di verifica HMAC-SHA256 e Base64 certificata per il flusso e l'ambiente di consegna.
- Confronta il valore calcolato con
X-Signatureutilizzando un confronto a tempo costante. - 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
- Verifica la firma prima di fidarti del payload.
- Registra una chiave di deduplicazione che includa il token dell'ordine e l'evento o lo stato di pagamento risultante.
- Restituisci una risposta
2xxdi successo non appena la richiesta è accettata in modo durevole. - Rileggi o riconcilia lo stato autoritativo dell'ordine prima di un'azione irreversibile come evasione, annullamento, cattura, rimborso o un'altra operazione.
- 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 dinamico#
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
| Configurazione | Requisito | Cosa controlla |
|---|---|---|
event_name | Obbligatorio | Nome dell’evento specifico del merchant, composto da lettere, numeri, trattini o trattini bassi. Configura il trigger separatamente. |
url | Obbligatorio | Destinazione dell’endpoint del merchant. Usa HTTPS per l’integrazione. |
http_method | Facoltativo | Metodo HTTP: GET, POST, PUT, o PATCH. Il valore predefinito è POST. |
headers | Facoltativo | Array di coppie di key e value per le intestazioni aggiuntive della richiesta. I valori possono usare template basati sull’ordine. |
params, query_params | Facoltativo | Array di coppie di key e value per i segnaposto dell’URL e i parametri di query. I valori possono usare template basati sull’ordine. |
payload_template | Facoltativo | Crea la richiesta JSON al merchant dall’ordine corrente e dai dati dell’evento. Senza questo template, il corpo della richiesta contiene solo i dati dell’evento. |
response_template | Facoltativo | Converte il JSON del merchant nel contratto di risposta dell’ordine. Omettilo se il tuo endpoint restituisce già quel contratto. |
response_data | Obbligatorio con response_template | JSON codificato come stringa, usato per convalidare il template di risposta durante la configurazione. Non è la risposta del merchant durante l’esecuzione. |
error_response_template | Facoltativo | Converte un formato alternativo di errore del merchant. Senza questo template, le risposte di errore del merchant usano code e message. |
fields_update.fields | Facoltativo | Array degli aggiornamenti consentiti per l’ordine. Includi ogni importo, elenco di sconti o campo articolo che il callback deve sostituire. Consulta i campi di prezzo qui sotto. |
fields_update.custom_fields | Facoltativo | Array dei nomi dei campi personalizzati modificabili. I campi devono essere dichiarati e i valori restituiti devono rispettare lo schema dei campi personalizzati dell’ordine. |
response_body.fields | Obbligatorio alla creazione della configurazione | Accetta Order, ShippingRate, e ShippingMethods. La risposta convertita include l’ordine; questo elenco seleziona anche i risultati di spedizione aggiuntivi. Non limita le proprietà presenti nell’ordine. |
response_body.custom_fields | Facoltativo | Array dei nomi dei campi personalizzati dichiarati da includere nel risultato del checkout. È separato dal permesso di aggiornare quei campi. |
propagate_response | Facoltativo | Predefiniti per false. Mantienilo su false per gli aggiornamenti dell’ordine; l’alternativa include il JSON del merchant in dynamic_response al posto del risultato dell’ordine convertito. |
Configura gli aggiornamenti dei prezzi
I nomi dei campi di configurazione e i percorsi JSON della risposta sono diversi. Seleziona solo gli aggiornamenti necessari per la tua promozione:
Valore in fields_update.fields | Dati della risposta del merchant | Comportamento dell’aggiornamento |
|---|---|---|
TotalAmount | order.total_amount | Sostituisce il totale da pagare. |
TotalDiscount | order.total_discount | Sostituisce l’importo totale degli sconti. |
Discounts | order.discounts | Sostituisce l’intero array di sconti dell’ordine. |
Items.TotalAmount | order.items[].id, order.items[].total_amount | Individua gli articoli esistenti per ID e aggiorna importo, importo originale e sconto totale. |
Items.Discounts | order.items[].id, order.items[].discounts | Individua gli articoli esistenti per ID e sostituisce i riferimenti agli sconti. |
Shipping | order.shipping | Sostituisce l’importo originale della spedizione, lo sconto totale e i riferimenti agli sconti. |
Il webhook assegna questi valori in modo indipendente. Non ricalcola il totale da pagare, gli sconti aggregati o la ripartizione per articolo a partire dall’elenco degli sconti. Restituisci tutti i campi consentiti a ogni chiamata riuscita. Omettere un campo selezionato può azzerare un importo o svuotare un elenco; non è un’istruzione di aggiornamento parziale.
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
| Preoccupazione | Requisito dell'endpoint del merchant |
|---|---|
| Esecuzione ripetuta | Gestisci gli input ripetuti in modo idempotente. Ricalcola quando cambiano i dati della promozione. |
| Contratto di risposta | Restituisci JSON che corrisponda alla forma di risposta configurata o al modello di risposta. |
| Campi obbligatori | Includi tutti i campi di aggiornamento configurati, compresi i valori pari a zero quando rimuovi uno sconto. |
| Latenza | Completa entro il timeout certificato per l'integrazione perché il checkout attende la risposta. |
| Errori | Restituisci una risposta non-2xx per un errore di business o di elaborazione, utilizzando la forma di errore configurata. |
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.
Con la propagazione delle risposte disattivata, la risposta del merchant può contenere order, shipping_rate, e shipping_methods. DEUNA restituisce l’ordine convertito e i risultati aggiuntivi configurati. Con la propagazione attivata, la risposta del merchant deve essere un JSON valido e viene esposta in dynamic_response. Usa il flusso con conversione per ricalcolare il prezzo dell’ordine.
Pattern pratici
Sconti in base alla carta
Usa un webhook dinamico di checkout per applicare una promozione in base alla carta inserita durante il checkout. Il tuo backend determina l’idoneità e calcola lo sconto; DEUNA applica gli aggiornamenti configurati all’ordine prima del pagamento.
Il tuo backend gestisce i numeri di identificazione bancaria (BIN), i circuiti di carte idonei e le regole di sconto. Il tuo DEUNA Technical Account Manager (TAM) non ha bisogno di questo elenco di idoneità. DEUNA chiama l’endpoint quando viene eseguito il trigger configurato; il tuo endpoint valuta ogni richiesta e restituisce l’ordine scontato o l’ordine senza quella promozione.
Un callback configurato prima del pagamento viene eseguito prima di ogni richiesta di pagamento in quel flusso configurato, senza un filtro di idoneità per BIN in DEUNA. Un callback di rilevamento del BIN può essere eseguito prima per aggiornare il prezzo del checkout quando il cliente inserisce o cambia una carta. Conferma con DEUNA quando eseguire il callback e quali dati includere nella richiesta.
Completa il ricalcolo del prezzo e aggiorna l’ordine prima che il checkout costruisca la richiesta di pagamento. Aggiornare i totali salvati dell’ordine in un callback precedente al pagamento non ricostruisce automaticamente gli importi già inseriti in quella richiesta di pagamento.
L’esempio seguente usa il rilevamento del BIN. L’inserimento della carta può generare un evento BIN dopo le prime sei cifre, prima che il cliente completi i dati della carta. Il rilevamento del BIN non conferma che la carta completa sia valida o che un pagamento sia autorizzato.
Configura e implementa questo flusso per ogni ambiente:
- Configura il webhook con DEUNA. Fornisci al tuo DEUNA Technical Account Manager (TAM) la destinazione HTTPS e la richiesta e la risposta previste. Concorda il nome dell’evento, quando eseguire il callback, la verifica della firma, il timeout, la gestione degli errori e i campi dell’ordine che la risposta può aggiornare. Mantieni la logica di idoneità alla promozione e il calcolo dello sconto nel tuo backend.
- Collega il trigger concordato. Per un callback precedente al pagamento, configurane l’esecuzione con DEUNA per il flusso di pagamento richiesto. Per l’esempio di rilevamento del BIN seguente, coordina il collegamento del checkout affinché un BIN rilevato o modificato esegua l’evento concordato. La sola registrazione di un webhook non lo collega all’inserimento della carta. Per Payment Widget ed Elements del Web SDK,
onCardBinDetectedesponecardBinecardBrand; consulta il riferimento ai callback del Web SDK. Il callback client e il webhook tra server sono passaggi separati. - Implementa l’endpoint del merchant. Verifica la richiesta firmata e valuta la promozione sul tuo server usando i dati dell’ordine e del BIN concordati. Conserva le credenziali private sul server e non richiedere il numero completo della carta o il codice di sicurezza per questo flusso. Gestisci le chiamate ripetute senza accumulare lo stesso sconto.
- Restituisci l’ordine ricalcolato. Restituisci il totale da pagare aggiornato, lo sconto aggregato e l’array completo di sconti nella risposta JSON concordata. Configura i tre aggiornamenti consentiti mostrati qui sotto e restituisci l’ordine convertito al checkout. Concorda un template di risposta se il tuo endpoint usa un altro formato e disattiva la propagazione delle risposte per questo aggiornamento.
- Aggiorna il prezzo prima del pagamento. Mostra l’ordine restituito da DEUNA e usa il totale aggiornato per il pagamento. Concorda come il checkout rimuove o ricalcola la promozione quando il cliente cambia o cancella la carta. Definisci se il checkout riprova, blocca il pagamento o continua senza la promozione quando il callback non riesce.
Ad esempio, una promozione del 10% su un ordine di USD 100.00 senza altri addebiti produce uno sconto di USD 10.00 e un totale da pagare di USD 90.00. Il tuo endpoint deve calcolare totali coerenti; restituire solo un indicatore di idoneità non modifica l’importo dell’ordine.
Esempio di contratto di richiesta e risposta
L’esempio seguente riguarda un ordine senza altri sconti o addebiti. Il nome dell’evento e la struttura della richiesta in uscita sono un esempio di accordo con il merchant, non un evento integrato di sconto sulla carta né uno schema predefinito per tutti i merchant. Conferma il contratto e il collegamento del checkout con il tuo TAM prima di usarlo.
Gli importi sono numeri interi espressi nelle unità minime della valuta dell’ordine: 10000 rappresenta USD 100.00. Mantieni il BIN come stringa per conservare gli zeri iniziali.
Il checkout fornisce questi dati quando esegue l’evento concordato:
{
"data": {
"cardBin": "411111",
"cardBrand": "visa"
}
}Configura la seguente mappatura con DEUNA. È un estratto di configurazione, non una richiesta del browser. Il template del payload combina l’ordine corrente con i dati dell’evento; senza di esso, il merchant riceve solo i dati dell’evento.
{
"event_name": "card_discount",
"url": "https://merchant.example.com/checkout/card-discounts",
"http_method": "POST",
"payload_template": "{\"order_token\":\"{{ .Order.Token }}\",\"order_id\":\"{{ .Order.OrderID }}\",\"currency\":\"{{ .Order.Currency }}\",\"total_amount\":{{ .Order.TotalAmount }},\"cardBin\":\"{{ .Payload.cardBin }}\",\"cardBrand\":\"{{ .Payload.cardBrand }}\"}",
"fields_update": {
"fields": ["TotalAmount", "TotalDiscount", "Discounts"]
},
"response_body": {
"fields": ["Order"]
},
"propagate_response": false
}L’endpoint del merchant riceve una richiesta equivalente al seguente cURL. DEUNA fornisce i valori degli header di firma e operazione. Conferma la verifica della firma per i payload trasformati con il tuo TAM.
curl --request POST 'https://merchant.example.com/checkout/card-discounts' \
--header 'Content-Type: application/json' \
--header 'X-Signature: SIGNATURE_FROM_DEUNA' \
--header 'X-Deuna-Operation: OPERATION_FROM_DEUNA' \
--data '{
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
}'const response = await fetch("https://merchant.example.com/checkout/card-discounts", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
body: JSON.stringify({
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"POST",
"https://merchant.example.com/checkout/card-discounts",
headers={
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
json={
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://merchant.example.com/checkout/card-discounts",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Signature: SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation: OPERATION_FROM_DEUNA"
],
CURLOPT_POSTFIELDS => json_encode([
"order_token" => "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id" => "merchant-order-123",
"currency" => "USD",
"total_amount" => 10000,
"cardBin" => "411111",
"cardBrand" => "visa"
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://merchant.example.com/checkout/card-discounts"))
.header("Content-Type", "application/json")
.header("X-Signature", "SIGNATURE_FROM_DEUNA")
.header("X-Deuna-Operation", "OPERATION_FROM_DEUNA")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("POST", "https://merchant.example.com/checkout/card-discounts", strings.NewReader("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
if err != nil { panic(err) }
request.Header.Set("Content-Type", "application/json")
request.Header.Set("X-Signature", "SIGNATURE_FROM_DEUNA")
request.Header.Set("X-Deuna-Operation", "OPERATION_FROM_DEUNA")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}I campi dell’ordine identificano l’ordine di cui viene ricalcolato il prezzo; i campi della carta contengono i dati dell’evento. Convalida i dati sul tuo server e usa le tue regole ufficiali per prezzi e promozioni. Ricalcola a partire dall’importo base della promozione dell’ordine, perché il totale ricevuto potrebbe già includere uno sconto da una chiamata precedente. Concorda come gestire un circuito sconosciuto o un BIN vuoto quando la carta viene cancellata.
Per una carta idonea, restituisci la seguente risposta con uno stato HTTP di successo e un corpo JSON:
HTTP/1.1 200 OK
Content-Type: application/json
{
"order": {
"total_amount": 9000,
"total_discount": 1000,
"discounts": [
{
"amount": 1000,
"code": "CARD_PROMO",
"reference": "merchant-promotion-123",
"description": "Card promotion",
"type": "order_value",
"discount_category": "promotion"
}
]
}
}| Campo della risposta | Tipo JSON | Obbligatorio in questo esempio | Significato |
|---|---|---|---|
order.total_amount | integer | Sì. | Totale finale da pagare nelle unità minime della valuta, dopo lo sconto. |
order.total_discount | integer | Sì. | Sconto totale nelle stesse unità, inclusa la promozione legata alla carta. |
order.discounts | array di oggetti | Sì. | Elenco completo degli sconti da salvare nell’ordine. Un array vuoto cancella questo elenco. |
Restituisci tutti e tre i campi configurati a ogni chiamata riuscita, incluse quelle che rimuovono la promozione. Per una carta non idonea in questo esempio, restituisci:
HTTP/1.1 200 OK
Content-Type: application/json
{
"order": {
"total_amount": 10000,
"total_discount": 0,
"discounts": []
}
}DEUNA aggiorna solo i campi consentiti da fields_update e restituisce l’ordine salvato in order al checkout. La risposta del merchant sopra contiene i tre campi da aggiornare; la risposta al checkout contiene l’ordine con gli altri campi preservati. Se si applicano altre promozioni, mantienile nell’elenco degli sconti restituito e ricalcola i totali. Restituisci un elenco vuoto e uno sconto aggregato pari a zero solo quando non rimangono sconti.
Contratto dell’oggetto sconto
Ogni voce dell’array di sconti dell’ordine descrive uno sconto applicato. Usa importi interi nelle unità minori della valuta; una promozione percentuale deve restituire il suo importo monetario calcolato. Il contratto di sconto convertito supporta i seguenti campi:
| Campo dello sconto | Tipo JSON | Significato |
|---|---|---|
amount | integer | Importo monetario applicato da questo sconto. |
code, reference | string | Codice promozionale e identificatore di riferimento del merchant. |
description, details_url | string | Descrizione e link facoltativo ai dettagli della promozione. |
type | string | Tipo di sconto: order_value, product, o free_shipping. |
discount_category | string | Classificazione dello sconto definita dal merchant. |
target_type | string | Componente di destinazione, quando applicabile: item o shipping. |
free_shipping | object | Dettagli della promozione di spedizione: is_free_shipping è un booleano; maximum_cost_allowed è un intero nelle unità minori della valuta. |
Questi campi descrivono il risultato della tua logica promozionale; non configurano i BIN idonei né fanno calcolare uno sconto a DEUNA. Includi i campi richiesti dal contratto concordato. Gli elenchi degli sconti per articoli e spedizione usano oggetti di riferimento contenenti amount e ref_idx; non ripetono l’oggetto sconto completo dell’ordine. Mantieni questi riferimenti coerenti con gli sconti dell’ordine restituiti.
In caso di errore di calcolo o elaborazione, restituisci uno stato HTTP diverso da 2xx. Senza una mappatura degli errori personalizzata, usa il corpo dell’errore mostrato di seguito. Lo stato illustra un errore temporaneo e il codice di errore è definito dal merchant:
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{
"code": "PROMOTION_UNAVAILABLE",
"message": "Unable to calculate the card promotion."
}Concorda un error_response_template se il tuo endpoint usa un’altra struttura di errore. Una carta non idonea è un normale risultato senza sconto, non un errore di elaborazione. Il checkout deve seguire il comportamento in caso di errore concordato al passaggio 5, anziché presumere che sia stato applicato uno sconto.
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 sandbox#
Testa le notifiche di stato
Testa un webhook dinamico
Prova uno sconto in base alla carta
Completa le verifiche del webhook dinamico e verifica il flusso di inserimento della carta prima di abilitare la promozione in produzione: