Webhooks

Les webhooks DEUNA couvrent deux flux serveur-à-serveur distincts : les notifications qui publient les changements d'état de paiement vers votre backend, et les rappels synchrones qui permettent à DEUNA de demander des données ou une logique spécifique au marchand pendant le paiement. Choisissez le flux en fonction des besoins de votre intégration.

Les redirections de navigateur, les rappels SDK et les rappels fournisseur-vers-DEUNA sont des surfaces d'intégration distinctes. Ne les utilisez pas comme preuve de paiement ou comme remplacement de ces flux backend.

Notifications d'état de commande et de paiementInterroger Athia à ce sujet#

Les notifications de statut envoient le dernier instantané de commande à votre backend lorsque le statut de paiement normalisé correspond à un événement auquel le marchand est abonné. Ces notifications sont asynchrones : le cycle de vie du paiement n'attend pas que votre logique métier se termine.

Configurer la livraison des statuts

Définissez le contrat de livraison pour chaque environnement :

Les événements disponibles suivent le cycle de vie de paiement documenté dans Workflow et statuts de paiement. La couverture des événements peut différer selon le moyen de paiement car tous les moyens ne prennent pas en charge chaque opération ou statut de paiement.

Payload par défaut

Sans transformation de charge utile personnalisée, DEUNA envoie une requête HTTP POST et Content-Type: application/json et la commande actuelle sous la propriété 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"
      }
    }
  }
}

La commande peut contenir les données client, article, montant, paiement, processeur, fraude, métadonnées et champ personnalisé associées à cette transaction. Traitez order.payment.data.status comme l'état de paiement faisant autorité, et utilisez order.token, order.order_id, ainsi que les identifiants de transaction applicables pour le rapprochement.

Une configuration spécifique à un marchand peut modifier la méthode HTTP, les en-têtes, les paramètres d'URL, les statuts souscrits et la forme de la charge utile. Si une configuration personnalisée est activée, implémentez le contrat exact certifié pour ce marchand au lieu de supposer le corps par défaut.

Vérifiez la signature

La livraison actuelle ajoute un X-Signature en-tête. Cela remplace les exemples plus anciens qui font référence à X-Deuna-Signature.

1. Lisez le corps de la requête non modifié avant qu'un framework ne l'analyse ou ne le resérialise.
2. Appliquez la procédure de vérification HMAC-SHA256 et Base64 certifiée pour le flux et l'environnement de livraison.
3. Comparez la valeur calculée avec X-Signature en utilisant une comparaison à temps constant.
4. Rejetez la requête avant tout traitement si les valeurs ne correspondent pas.

Les notifications de statut et les webhooks dynamiques ne signent pas toujours la même entrée lorsque la transformation de la charge utile est activée. Ne réutilisez pas un vérificateur entre ces flux tant que l'entrée signée et la dérivation de clé n'ont pas été confirmées lors de la certification.

Conservez les clés d'API privées sur le serveur. Ne les placez jamais dans le code du navigateur, les applications mobiles, les journaux ou les réponses de webhook.

Accusez réception et réconciliez

1. Vérifiez la signature avant de faire confiance à la charge utile.
2. Enregistrez une clé de déduplication qui inclut le jeton de commande et l'événement ou le statut de paiement résultant.
3. Renvoie une réponse 2xx réussie dès que la requête est acceptée de manière durable.
4. Relisez ou réconciliez l'état de commande faisant autorité avant l'exécution, l'annulation, la capture, le remboursement ou toute autre action irréversible.
5. Ignorez une notification qui ferait reculer votre enregistrement local depuis un état plus récent.

Les échecs de livraison peuvent être réessayés. Ne supposez pas une livraison exactement une fois, un intervalle de réessai fixe ou une arrivée dans l'ordre du cycle de vie.

Webhooks de paiement dynamiqueInterroger Athia à ce sujet#

Les webhooks dynamiques sont des rappels synchrones spécifiques au marchand. Lorsque le checkout déclenche un événement configuré, DEUNA envoie une requête signée à votre point de terminaison, valide la réponse, applique uniquement les mises à jour autorisées et renvoie le résultat configuré au checkout.

Les webhooks dynamiques sont activés et configurés dans le cadre de l'implémentation marchand. Ils ne sont pas enregistrés depuis le code du navigateur ou mobile.

Flux de configuration et d'exécution

Configurez le webhook avec DEUNA dans le cadre de votre configuration marchand. Convenez du nom de l'événement, de la destination, des formats de requête et de réponse, des règles de validation et des champs que le rappel peut mettre à jour. Après la configuration, le checkout peut exécuter l'événement via le même contrat convenu.

Si l'événement n'est pas configuré pour le marchand et l'environnement, DEUNA n'appelle pas votre point de terminaison. Traitez un rappel requis qui n'a pas été exécuté comme un problème de configuration lors de la certification.

Capacités de configuration

L'extrait suivant montre le cœur d'une définition de calcul de pourboire. Il s'agit de données de configuration, pas d'une requête qui devrait être envoyée depuis le navigateur :

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

Pendant l'exécution, le checkout peut fournir une entrée spécifique à l'événement :

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

Sans modèle de payload, le point de terminaison du marchand reçoit ces données d'événement. Avec un modèle de payload, le modèle peut utiliser à la fois la commande actuelle et l'entrée d'événement pour construire le JSON sortant.

Implémenter le point de terminaison du marchand

Les appels dynamiques incluent X-Signature et X-Deuna-Operation. Lorsqu'un modèle de payload modifie le corps sortant, utilisez l'entrée de vérification de signature convenue pendant la certification ; ne supposez pas qu'elle est identique au contrat de notification de statut ci-dessus.

Si la propagation de la réponse est désactivée, la réponse marchand par défaut peut contenir order, shipping_rateet shipping_methods; DEUNA renvoie uniquement les champs de réponse sélectionnés par la configuration. Si la propagation de la réponse est activée, la réponse du marchand doit être un JSON valide et est renvoyée directement comme résultat dynamique.

Modèles pratiques

Exemple de calcul de pourboire

Cet exemple montre le chemin complet du checkout au marchand pour un événement de pourboire configuré.

Pour une définition de pourboire, n'autorisez que le montant et les champs personnalisés que la réponse du marchand est censée modifier. Le point de terminaison du marchand reste responsable du calcul d'un total de commande cohérent.

Tester dans un environnement de testInterroger Athia à ce sujet#

Tester les notifications de statut

Tester un webhook dynamique

Documentation associéeInterroger Athia à ce sujet#