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 (la seule notification garantie).

Pour les intégrateurs pressés : vous aurez ici les formats d’appel, les paramètres ajoutés automatiquement, les bonnes pratiques, et les exemples JSON.

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

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

Ajoutez un identifiant propre à votre système ans vos URLs afin de relier le retour à votre commande.

 Exemple d'url appelé lors de la validation du paiement par le client.

• en vert, l'url passée lors de l'initialisation du paiement, avec le transId ajouté pour lier le retour à un id marchand.
• en rouge, le paramètre payId ajouté par le serveur.

	urls{
		"return":"https://myProcessingServer.net/myApi/success.php?transId=95330876-67ae-4949-a11c-b9a29257831b",
		"cancel":"https://myProcessingServer.net/myApi/cancel.php?transId=95330876-67ae-4949-a11c-b9a29257831b",
 		"webhook":"https://myBackOfficeServer.net/webhook.php"
	}

https://myProcessingServer.net/myApi/success.php?transId=95330876-67ae-4949-a11c-b9a29257831b&PayId=b6eae9b16e3343fa90da39d4ee7bf4ad

Il est conseillé d'ajouter à l'url un paramètre propre à votre back-office permettant de lier ce retour à la vente.

2. Return URL & Cancel URL

• url return: c'est le point d'entrée du commerçant pour finaliser la commande coté back-office marchant.
  Cette url est appelé l
• url cancel: même principe que pour l'url return, cette url est appelée lorsque le client clic sur le bouton cancel.

Une de ces deux url (return ou cancel) sera appelé appelée à 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 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'url appelé est celle passée, a laquelle est ajout le paramètre PayId portant la valeur du Payment Id généré par le serveur Axepta BNP Paribas Online pour cette transaction.

À 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

🔔 Webhooks, Return URL & Cancel URL

Gestion des callbacks et notifications de paiement

🎯 Introduction

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 (la seule notification garantie).

Pour les intégrateurs pressés : vous aurez ici les formats d’appel, les paramètres ajoutés automatiquement, les bonnes pratiques, et les exemples JSON.

Pour les développeurs débutants : des encadrés “À savoir” expliquent les notions essentielles.

Il est fortement recommandé d’ajouter un diagramme de séquence illustrant :

1. l’initialisation du paiement ;
2. la navigation du client ;
3. l’appel Return/Cancel ;
4. l’envoi du webhook ;
5. l’appel de l’API GET /payments/getByPayId/{payId}.

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

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

"urls": {    "return":"https://myProcessingServer.net/myApi/success.php?transId=95330876",    "cancel":"https://myProcessingServer.net/myApi/cancel.php?transId=95330876",    "webhook":"https://myBackOfficeServer.net/webhook.php"}

À savoir

• return = redirection si le client valide son paiement
• cancel = redirection si le client annule
• webhook = notification asynchrone et garantie, indépendamment de l’action du client

➡️ Ajoutez un identifiant interne (ex : transId) dans vos URLs afin de relier le retour à votre commande.

2. Return URL & Cancel URL

Les URLs return et cancel sont appelées à la fin du parcours client.

2.1. Rôle des URLs

À l’appel de l’une de ces URLs, Axepta ajoute automatiquement le paramètre :

PayId=<paymentId généré par 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

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 : autorisation, capture, échec…asynchrone.

Ce que vous devez faire

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

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

{  "merchantId": "YOUR_MERCHANT_ID",  "payId": "91a6299a704147bf934aabd79fd1dc5d",  "transId": "Trans361039",  "xid": "b55e68b7e4644a90836ae31effe1fc60",  "refNr": "refNb77254",  "status": "AUTHORIZED",  "responseCode": "00000000",  "responseDescription": "Transaction successful",  "amount": {    "value": 126,    "currency": "EUR"  },  "paymentMethods": {    "type": "CARD"  },  "creationDate": "2025-10-30T11:27:57Z",  "channel": "ECOM"}

4. Recommandations d’intégration

✔️ Toujours vérifier la transaction via l’API 

getByPayId

Même si le retour client laisse penser à un succès.

✔️ Toujours traiter le webhook

C’est votre source de vérité.

✔️ Logger tous les appels return/cancel/webhook

Utile pour l’analyse en cas de litige ou d’échec.

✔️ Anticiper les doublons

Les webhooks peuvent être renvoyés : votre endpoint doit être idempotent.

Ces urls sont passées lors de la demande de transaction, et rappelée ensuite à la fin du processus de paiement.

URL return & cancel 

Exemple d'url appelé lors de la validation du paiement par le client.
en vert, l'url passée lors de l'initialisation du paiement, avec le transId ajouté pour lier le retour à un id marchand.
en rouge, le paramètre payId ajouté par le serveur.

https://myProcessingServer.net/myApi/success.php?transId=95330876-67ae-4949-a11c-b9a29257831b&PayId=b6eae9b16e3343fa90da39d4ee7bf4ad

Action à faire lors de la reception de ce message

Vous pouvez contacter le serveur Axepta BNP Paribas Online avec le paiement Id reçut en paramètre pour connaitre le statut de la transaction.

Utilisez l'api  GET /payments/getByPayId/{payId}.

Eléments clés de la réponse à l'api getByPayId

• montant de la transaction
  • autorisé
  • capturé
  • remboursé
• Identifiants de la transaction 
  • payId: id transaction Axepta BNP Paribas Online
  • transId: id transaction Marchand
  • xId: id action Axepta BNP Paribas Online
  • refNr: numéro de reference de la transaction
• Status de la transaction 
  • status: Status de la transaction, succès (OK) ou en erreur (FAILED)
  • responseCode: "000000000" si la transaction est réussi, un code erreur en cas d'echec.
    (voir Response codes - Documentation pour le détail et la signification des différentes valeurs possibles.)
  • responseDescription: une phrase résumant l'état de la transaction.

 {
	"amount":{
		"value":126,
		"currency":"EUR",
		"capturedValue":0,
		"refundedValue":0
	},
	"payId":"91a6299a704147bf934aabd79fd1dc5d",
	"merchantId":"MY_MERCHANT_ID",
	"transId":"Trans361039",
	"xId":"b55e68b7e4644a90836ae31effe1fc60",
	"refNr":"refNb77254",
	"status":"AUTHORIZED",
	"responseCode":"00000000",
	"responseDescription":"Transaction successful",
	"paymentMethods":{
		"type":"CARD"
	}
}

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

• montant autorisé
• le mechant Id utilisé
• Identifiants de la transaction 
  • payId: id transaction Axepta BNP Paribas Online
  • transId: id transaction Marchand
  • xId: id action Axepta BNP Paribas Online
  • refNr: numéro de reference de la transaction
• Status de la transaction 
  • status: Status de la transaction, succès (OK) ou en erreur (FAILED)
  • responseCode: "000000000" si la transaction est réussi, un code erreur en cas d'echec.
    (voir Response codes - Documentation pour le détail et la signification des différentes valeurs possibles.)
  • responseDescription: une phrase résumant l'état de la transaction.
• la date de la transaction, timezone UTC
• le type de canal utilisé lors du paiement (ecom, mail order telephone order, pay by link ...)

{
    "merchantId": "YOUR_MERCHANT_ID",
    "payId": "91a6299a704147bf934aabd79fd1dc5d",
    "transId": "Trans361039",
    "xid": "b55e68b7e4644a90836ae31effe1fc60",
    "refNr": "refNb77254",
    "status": "AUTHORIZED",
    "responseCode": "00000000",
    "responseDescription": "Transaction successful",
    "amount": {
        "value": 126,
        "currency": "EUR"
    },
    "paymentMethods": {
        "type": "CARD"
    },
    "creationDate": "2025-10-30T11:27:57Z",
    "channel": "ECOM"
}

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