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 :

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

Code Block

title	exemple d'url de retour
linenumbers	true

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

URL return & cancel

Info
return = redirection

Elles sont renseignées lors de l'initialisation du paiement.

Il est conseillé d'ajouter à 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 le client clic sur le bouton de validation à la fin du paiement.

url cancel: même principe que pour l'url return, cette url est appelée lorsque le client clic sur le bouton cancel.

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

2. Return URL & Cancel URL

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

Tip

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

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

Que faire lorsque vous recevez cet appel ?

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

Récupérez le paramètre PayId.
Appelez l’API pour obtenir l’état réel de la transaction :

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}

.

- Retrieve payment details by Payment ID
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

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.

Code Block

language	json
title	Exemple réponse résumé getByPayId
linenumbers	true

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

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 site marchand de prendre en charge la réception de ce message.
C'est le seul accusé de complétion de transaction dont l'envoi est garanti.
Si le client ferme la fenêtre de navigation lors de la validation du paiement, l'appel a l'url return ou cancel ne sera pas fait.
Il n'est donc important pour le site marchant de traiter les requêtes reçues sur l'url webhook.

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

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

Tip

Important : ne déclenchez jamais la finalisation de commande uniquement à partir du Return URL.

Utilisez toujours le webhook comme source d’information fiable.

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

Le Serveur Axepta BNP Paribas Online retourne une payload json sur cette url à la fin de la transaction, avec les éléments clés suivant:

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 ...)

Code Block

language	json
title	webhook payload
linenumbers	true

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

X-Paygate-Signature-Version	Version du format de la signature (actuellement, `v1`)
X-Paygate-Timestamp	Unix epoch timestamp (secondes depuis 1970-01-01T00:00:00Z, UTC)
X-Paygate-Signature	Signature dans le format `v1=<hex-hmac>`Peut supporter de multiple signature, pour gérer le renouvellement des clés (e.g. `v1=<hmac1>,v2=<hmac2>`)

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:

Extraire les données portées par les headers HTTP:
- X-Paygate-Timestamp
- X-Paygate-Signature
Prendre les données brutes de la payoad Json (les données binaire reçues)
Calculer le HMAC avec les données extraites

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

Comparer la signature calculée avec celle reçue en utilisant une méthode "constant-time"
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

Tip
Toujours vérifier la transaction via le endpoint getByPayId, même si le retour client laisse penser à un succès. Toujours traiter le webhook. Toujours vérifier l'authenticité des données du webhook en validant sa signature. Logger tous les appels return/cancel/webhook.

Page tree

Versions Compared

Old Version 15

New Version Current

Key

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

URL return & cancel

2. Return URL & Cancel URL

Action à faire lors de la reception de ce message

Que faire lorsque vous recevez cet appel ?

URL webhook

3. Webhook

Quand est-il envoyé ?

Ce que vous devez faire

Structure du webhook

Sécurité et Vérification

Signature headers

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

Vérification de la signature (Commerçant)

Recommandations d’intégration

Help

Intranet Tools

Page tree

Page History

Versions Compared

Old Version 15

New Version Current

Key

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

URL return & cancel

2. Return URL & Cancel URL

Action à faire lors de la reception de ce message

Que faire lorsque vous recevez cet appel ?

URL webhook

3. Webhook

Quand est-il envoyé ?

Ce que vous devez faire

Structure du webhook

Sécurité et Vérification

Signature headers

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

Vérification de la signature (Commerçant)

Recommandations d’intégration