Dans cette section, vous trouverez tout ce qu’il faut pour gérer les différents points d’entrée que votre application recevra pendant et après un paiement Axepta BNP Paribas Online.

Vous apprendrez :

• quelles URLs transmettre lors de la création d’un paiement,
• dans quel ordre elles sont appelées,
• comment interpréter les informations retournées,
• comment vérifier le statut réel d’une transaction,
• comment gérer le webhook

Table des matières

1. Déclarer les URLs : return, cancel, webhook

Lors de l’initialisation du paiement, vous devez fournir un objet urls :

2. Return URL & Cancel URL

Une de ces deux url (return ou cancel) sera appelée à la fin du traitement de la transaction, afin de:

• Rediriger le client sur le site marchant a la fin de la transaction
• Informer le commerçant du statut de la transaction : validée ou non.
• de retourner au back-office du commerçant l'identifiant unique de la transaction payId générée par Axepta Online.

À l’appel de l’une de ces URLs, Axepta BNP Paribas Online ajoute automatiquement le paramètre : PayId=<paymentId généré par Axepta> - cf Préconisation d'intégration

Que faire lorsque vous recevez cet appel ?

À l’appel de l’une de ces URLs : 

1. Récupérez le paramètre PayId.
2. Appelez l’API pour obtenir l’état réel de la transaction : GET /payments/getByPayId/{payId} - Retrieve payment details by Payment ID
3. Mettez à jour votre commande en fonction du status et du responseCode.

Champs importants dans la réponse API

• Montant : value, capturedValue, refundedValue
• Identifiants : payId, transId, xId, refNr
• Statut : status = AUTHORIZED, CAPTURE_REQUEST, OK, FAILED, etc.
• Résultat :
  • responseCode = "00000000" OU "0" si succès
  • responseDescription = message textuel

Exemples de réponses résumées

3. Webhook

A la fin du traitement de la transaction, Axepta BNP Paribas Online notifie le site marchand du résultat final de la transaction.

La notification Webhook est le seul moyen fiable d’être informé de la complétion d’une transaction. Il est impératif pour le site marchant de traiter les requêtes reçues sur l'Url Webhook.
Elle est réalisée par un appel http REST sur l'url webhook fournis lors de l'initialisation du paiement.

Elle est envoyée même si le client :

• ferme son navigateur,
• perd la connexion,
• ne revient pas sur votre site.

Recommandations générales

L'implémentation correcte de la réception des webhooks est essentielle pour garantir la mise à jour en temps réel du statut de vos transactions et assurer la fiabilité de votre processus de commande.

Pour garantir le bon fonctionnement du service, nous recommandons l'application des prérequis techniques suivants.

1) Connectivité et Sécurité Réseau

Afin que nos serveurs puissent acheminer les notifications vers votre infrastructure, vos règles de sécurité réseau doivent être configurées comme suit :

⚙️ Ouverture des Ports

Les notifications sont transmises via le protocole HTTPS.

• Port requis : Le port 443 doit être ouvert et accessible en entrée (Inbound) sur votre serveur.
• Attention : L'utilisation de ports non standards (ex: 8097, 8443) n'est pas supportée par la plateforme et entraînera un échec de livraison des notifications. Si votre application écoute sur un port spécifique, nous vous recommandons de mettre en place un reverse-proxy ou une règle de routage pour rediriger le trafic du port 443 vers votre application.

🌐 Whitelisting des Adresses IP

Pour sécuriser vos échanges tout en permettant la réception des flux, vous devez autoriser (whitelister) les plages d'adresses IP de notre prestataire technique.

Veuillez configurer vos pare-feux (Firewalls / NSG) pour accepter les requêtes entrantes provenant des IP suivantes :

• 213.155.65.64/26
• 213.95.169.128/27
• 217.92.237.167

2) Exigences Techniques de l'Endpoint (URL de réception)

🔒 Protocole et Certificats

• HTTPS Obligatoire : L'URL de notification doit impérativement être sécurisée en HTTPS.
• Version TLS : Le serveur de destination doit supporter le protocole TLS 1.2 ou supérieur.
• Certificats : Nous recommandons l'utilisation d'un certificat SSL émis par une autorité de certification (CA) reconnue.

🚀 Performance et Disponibilité

• Temps de réponse : Votre endpoint doit répondre rapidement pour éviter les timeouts.
• Code de réponse : Pour confirmer la bonne réception de la notification, votre serveur doit renvoyer un code HTTP 200 OK. Tout autre code (ex: 4xx ou 5xx) sera considéré comme un échec de livraison et pourra déclencher des tentatives de renvoi.

3) Recommandations d'Implémentation (Bonnes Pratiques)

Pour rendre votre intégration plus résiliente, nous préconisons l'adoption des mécanismes suivants :

🛡️ Mécanisme de Secours (Fallback)

Bien que le webhook soit le moyen privilégié pour être informé d'une transaction, des incidents réseau intermittents peuvent survenir. 

Préconisation : Implémentez un mécanisme de consultation active via l'opération Get Payment Details by TransID. En cas de non-réception d'un webhook après un délai défini, votre système doit pouvoir interroger l'API pour récupérer le statut réel de la transaction.

🔍 Validation de la Signature

Pour garantir l'authenticité des notifications et s'assurer qu'elles proviennent bien d'Axepta BNP Paribas, nous vous recommandons d'implémenter la vérification des headers de signature (HMAC) fournis dans chaque requête.

Quand est-il envoyé ?

À chaque fin de traitement de paiement asynchrone.

Si l'adresse appelée n'est pas accessible, la notification est répétée jusqu'à 8 fois 

Ce que vous devez faire

1. Lire la payload JSON
2. Identifier la transaction via payId ou transId
3. Mettre à jour votre système
4. Répondre un code 200 OK 

Structure du webhook

Champs fournis

• merchantId
• payId
• transId
• xId
• refNr
• status (AUTHORIZED, FAILED, etc.)
• responseCode / responseDescription
• amount
• paymentMethods
• creationDate (UTC)
• channel (ECOM, MOTO, Pay By Link…)

Exemple

Sécurité et Vérification

Afin de garantir l'authenticité des données du webhook, elle sont signées avec un HMAC-SHA256.

La signature est portée par 3 header http dans le message webhook.

Signature headers

Multiple Clés

Il est possible de configurer jusqu'à 2 jeux de clés, pour l'Authentification API , et pour la génération des Signature.

Les clés sont définies dans le portail marchant, et sont identifiées comme:

- Primaire (v1)
- Secondaire (v2)

La version de la clé utilisée par la plateforme Axepta Online pour signer les webhook dépend de la version de la clé utilisée par le commerçant lors de l'authentification.
Par exemple, si le marchant s'authentifie avec le jeu de clé REST API Secondaire (v2), alors la clé REST HMAC Secondaire (v2) sera utilisée pour la signature, et l'entete http X-Paygate-Signature commencera par : "v2=...".

 La version de la clé utilisée par la plateforme Axepta Online pour la signature des webhook est la même que celle utilisée par le Marchant lors de du processus d'authentification.

Rotation des clés

Deux jeux de clés peuvent être configurés, mais un seul est actif à la fois (celui choisi lors de l'authentification).
Ceci permet de mettre a jour le jeu de clé inactif, de le configurer et le déployer sur l'ensemble des équipements avant de l'activer.

Génération de la signature (Axepta BNP-Paribas Online)

signed_payload = timestamp + "." + raw_json_body
signature = HMAC_SHA256(secret, signed_payload)

• secret – HMAC key
• La signature générée est encodé 'hex' et le header est valorisé comme suit:

X-Paygate-Signature: v1=<hex-hmac>

Vérification de la signature (Commerçant)

Pour vérifier l'authenticité des données du message webhook:

1. Extraire les données portées par les headers HTTP:

   • X-Paygate-Timestamp
   • X-Paygate-Signature
2. Prendre les données brutes de la payoad Json (les données binaire reçues)

3. Calculer le HMAC avec les données extraites

4. signed_payload = timestamp + "." + raw_body
   expected_signature = HMAC_SHA256(secret, signed_payload)
   

5. Comparer la signature calculée avec celle reçue en utilisant une méthode "constant-time"
6. Valider le webhook si
   1. Les signatures sont identiques
   2. le Timestamp est compris dans les ±5 minutes par rapport à votre horloge locale.

Exemple de vérification de l'authenticité du Webhook:

Merchant Id utilisé : BNP_DEMO_MID
Merchant Id HMAC utilisée: Voir Sandbox & Test page 

Transaction effectuée the 19 Mai, 2026, à 09h23m20sec Paris time (GMT+2)

Headers
{
	"Accept-Encoding": "gzip",
	"Content-Length": 381,
	"Content-Type": "application/json",
	"Expect": "100-continue",
	"X-Forwarded-Host": "bin.webhookrelay.com",
	"X-Forwarded-Proto": "https",
	"X-Paygate-Signature": "v1=DF1F4AA6022460A9821832F9B89DF82D92D01B35C80DDDF596E97FF26E0ABB14",
	"X-Paygate-Signature-Version": "v1",
	"X-Paygate-Timestamp": "1779175402",
	"X-Real-Ip": "213.155.65.68"
}

Body
{
	"merchantId": "BNP_DEMO_MID",
	"payId": "413cef3ff4fd4b08af2245d5a889dbaa",
	"transId": "Trans293156",
	"xid": "7919a1e81571466ca8f5737d5414f7a4",
	"refNr": "refNb81210",
	"status": "FAILED",
	"responseCode": "22940040",
	"responseDescription": "NO RESPONSE",
	"amount": {
		"value": 460,
		"currency": "EUR"},
	"paymentMethods": {
		"type": "CARD"},
	"creationDate": "2026-05-19T07:23:20Z",
	"channel": "ECOM"
}

Validation du Webhook :

Vérification de la Signature :

Donnée utilisées pour la signature: <valeur de epoch timestamp>.<corps du message json du webhook>
Valeurs:

1779175402.{"merchantId": "BNP_DEMO_MID","payId": "413cef3ff4fd4b08af2245d5a889dbaa","transId": "Trans293156","xid": "7919a1e81571466ca8f5737d5414f7a4","refNr": "refNb81210","status": "FAILED","responseCode": "22940040","responseDescription": "NO RESPONSE","amount": {"value": 460,"currency": "EUR"},"paymentMethods": {"type": "CARD"},"creationDate": "2026-05-19T07:23:20Z","channel": "ECOM"}

Calcul du HMAC-SHA256 avec les données ci dessus en entrée, en utilisant la clé: 6Gp_A!8f)3zZ9K]gb7S?2*tN(yH54[wB 

df1f4aa6022460a9821832f9b89df82d92d01b35c80dddf596e97ff26e0abb14

Note: la vérification de la signature doit se faire indépendamment de majuscule/minuscule

Préconisations d'intégration