Webhooks

DEUNA utilise des webhooks pour envoyer à votre backend une capture à jour de la commande lorsque l'état de paiement ou de la commande est modifié. Le corps par défaut destiné au commerçant contient la commande elle-même. Il ne s'agit pas d'un en-tête d'événement de type Stripe.

Comment ça marche#

Configurez la destination#

Pour Purchase V2, fournissez l'URL de réception HTTPS dans le champ de notification de commande asynchrone présenté ci-dessous :

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

DEUNA stocke une URL au niveau de la commande et peut compléter une valeur manquante à partir de la configuration du commerçant définie lors de l’onboarding. Le flux actuel de notifications signées utilise la destination et l’abonnement aux statuts au niveau du commerçant ; confirmez avec votre TAM l’URL effective pour chaque environnement. Les champs d’URL de webhook asynchrone et synchrone sont mutuellement exclusifs pour une commande.

Les notifications de statut de commande n’utilisent pas de ressource générique d’enregistrement de endpoints webhook. Configurez le champ de commande ci-dessus ou utilisez la configuration au niveau du commerçant convenue avec votre Technical Account Manager (TAM) DEUNA. Les callbacks dynamiques du checkout utilisent l’API distincte décrite ci-dessous.

Flux de livraison pris en charge#

Utilisez la livraison asynchrone, sauf si DEUNA a explicitement activé et certifié un autre mode pour votre intégration.

DEUNA crée des notifications candidates lorsque les valeurs de statut de commande ou de paiement prises en charge changent, lorsque le processeur sélectionné change, ainsi que pour les décisions de fraude ou 3DS prises en charge. L’abonnement configuré détermine ensuite les statuts de paiement envoyés. Toutes les transitions de statut ne génèrent pas de webhook.

Ce mécanisme couvre les mises à jour de commande et les résultats finaux des opérations asynchrones de capture, de remboursement et d'annulation prises en charge. Voir Workflow et statuts de paiement pour les statuts publics et Capture, remboursement et annulation asynchrones pour les flux d'opérations correspondants.

Webhooks de paiement dynamique#

Les webhooks dynamiques du checkout constituent un flux synchrone distinct. Ils permettent à une action du checkout d’appeler un endpoint du commerçant par nom d’événement, de valider ou transformer la réponse, de mettre à jour certains champs de la commande tokenisée et de renvoyer les valeurs sélectionnées ou la réponse du commerçant à l’appelant.

Utilisez ce flux pour les actions de paiement spécifiques au commerçant, telles que les pourboires, les points de fidélité, les dons et le comportement des coupons personnalisés. Ne l'utilisez pas comme remplacement pour la livraison asynchrone de l'état de paiement.

L'API Gateway effectif expose ces opérations de webhooks dynamiques :

La requête d'exécution peut inclure des entrées spécifiques à l'événement. data:

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

DEUNA charge la configuration active du commerçant et du nom d’événement, puis appelle l’URL configurée du commerçant. La configuration peut sélectionner la méthode HTTP, les en-têtes, les paramètres d’URL et de requête, les modèles de payload et de réponse, les validations, les champs de commande à mettre à jour, les champs de réponse à renvoyer et la propagation éventuelle de la réponse du commerçant.

La requête du commerçant sortante inclut X-Signature et X-Deuna-Operation. L’exécution est synchrone : les délais d’attente du commerçant, les réponses non valides, les échecs de validation et les réponses HTTP infructueuses sont renvoyés à l’appelant. Si le commerçant ne dispose d’aucune configuration pour le nom d’événement, DEUNA renvoie une réponse de succès vide sans appeler d’endpoint du commerçant.

La configuration du webhook dynamique est propre au commerçant et peut modifier une commande. Confirmez avec votre TAM le nom de l’événement, l’authentification, les champs autorisés, les modèles, les validations, le délai d’attente et la réponse propagée avant de l’activer. Consultez catalogue des endpoints pour l'inventaire du Gateway.

Payload par défaut pour l'état de la commande#

La requête par défaut est une requête HTTP POST et Content-Type: application/json et a la forme suivante :

{
  "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’objet de commande complet peut contenir les mêmes champs de commande, de client, d’article, de montant, de paiement, de processeur, de fraude et de métadonnées que ceux renvoyés dans une réponse de commande.

• État de paiement autoritaire : order.payment.data.status
• Identifiants commerciaux stables : order.token, order.order_id, et les identifiants de transaction applicables

Les configurations personnalisées du commerçant peuvent transformer ce corps. Si votre récepteur n'utilise pas la forme par défaut présentée ci-dessus, veuillez confirmer le payload exact avec votre TAM.

Authentifier l'état de livraison de la commande#

Le flux de livraison actuel envoie cet en-tête de requête :

X-Signature: <signature>

La signature est dérivée par HMAC-SHA256 et encodage Base64 à partir du payload JSON et des identifiants du commerçant.

Validez le payload de requête exact avec les identifiants et la procédure de vérification fournis lors de l'onboarding avant de faire confiance au payload. Ne vous fiez pas à des noms d'en-tête alternatifs ou à des helpers SDK non documentés.

Accepter et traiter#

Renvoyez un statut HTTP 200 ou une autre réponse 2xx dès que la requête est validée et durablement mise en file d'attente. Vous pouvez renvoyer un corps vide. Si vous renvoyez un JSON, DEUNA accepte la forme de réponse suivante :

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

N'envoyez qu'un identifiant de commande différent et non vide dans cette réponse uniquement lorsque vous souhaitez que DEUNA remplace l'identifiant de commande du commerçant.

Les erreurs de réseau, les délais d'attente et les réponses non réussies peuvent entraîner une nouvelle tentative de livraison. Ne vous appuyez pas sur un intervalle de tentatives fixe et ne supposez pas l'ordre de livraison. Rendez le traitement idempotent et réconciliez chaque instantané avec l'état de paiement le plus récent connu.

Tester dans un environnement de test#

1. Exposez un récepteur HTTPS qui enregistre les en-têtes de requête et le corps non modifié.
2. Définissez l'URL de notification de commande asynchrone sur une requête Purchase V2 de test, sauf si une URL au niveau du commerçant est déjà configurée.
3. Effectuez un paiement ou une capture, un remboursement ou une annulation qui modifie le statut du paiement.
4. Confirmez la forme du payload, la couverture des statuts configurés, le comportement de l'en-tête signé, l'accus de réception et la gestion des doublons.

Le flux de statut de commande ne fournit pas l'API générique /webhook_endpoints ou la commande CLI locale. Testez-le en produisant des modifications réelles de l'état de test. Testez les webhooks de paiement dynamique via leurs routes de configuration et d'exécution vérifiées.