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

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

Concept

<todo>

URL return & cancel 

Ces adresses sont appelées à la fin du processus de paiement.
Ces urls sont appelé lorsque le client valide le résultat de la transaction.
Nota: si le client ferme la fenêtre de navigation sans cliquer sur la validation, ces appels ne seront pas fait.
Il n'est donc pas garanti pour le site marchant de recevoir cette confirmation de paiement.

L'url appelée est celle renseignée par le commerçant lors de l'initialisation du paiement.

Vous devez intégrer à l'url un paramètre propre à votre back-office permettant de lier ce retour à la vente.

• url return: c'est le point d'entrée du commerçant pour finaliser la commande coté back-office marchant.
  Cette url est appelé lorsque la transaction est finalisée avec succès.
• url cancel: même principe que pour l'url return, cette url est appelée lorsque la transaction à été refusée.

Une de ces deux url sera obligatoirement appelé à la fin du traitement bancaire de la transaction, afin de:

• Rediriger le client sur le site marchant a la fin de la transaction
• Informer le 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 - Documentation Axepta BNP Paribas - Axepta

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, CAPTURED, FAILED, etc.
• Résultat :
  • responseCode = "00000000" si succès
  • responseDescription = message textuel

Exemple de réponse

URL webhook 

Cette adresse est appelée en dehors du processus de paiement.

C'est le mécanisme asynchrone utilisé par la plateforme Axepta BNP Paribas Online pour notifier le commerçant de la validation de la transaction.
Il est indispensable pour le sit marchand de prendre en charge la réception de ce message.

3. Webhook

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 envoyée même si le client :

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

Quand est-il envoyé ?

À chaque fin de traitement de paiement asynchrone.

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

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.

Recommandations d’intégration