Versions Compared

Old Version 2

changes.mady.by.user writer

Saved on

compared with

New Version 3

changes.mady.by.user writer

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

In this section, you'll find everything you need to manage the various entry points your application will receive during and after an Axepta BNP Paribas Online payment.

You'll learn:

  • Which URLs to transmit when creating a payment,
  • The order in which they are called,
  • How to interpret the returned information,
  • How to verify the actual status of a transaction,
  • How to manage webhooks


1. Provide URLs : return, cancel, webhook

When initializing the payment, you must provide a URLs object:

Code Block
titleexemple d'url de retour
linenumberstrue
	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"
	}


Info
  • return = redirection when the customer clicks the validation button at the end of payment
  • cancel = redirection if the customer cancels
  • webhook = asynchronous and guaranteed notification, regardless of the customer's action


2. Return URL & Cancel URL

One of these two URLs (return or cancel) will be called at the end of transaction processing to:

  • Redirect the customer to the merchant's site at the end of the transaction
  • Inform the merchant of the transaction status: whether it was validated or not
  • Return the unique transaction identifier payId generated by Axepta Online to the merchant's back office

When either of these URLs is called, Axepta BNP Paribas Online automatically adds the parameter: PayId=<paymentId generated by Axepta> - see Integration recommendation

- Documentation Axepta BNP Paribas - Axepta

Tip

Add a unique identifier from your system to your URLs to link the response to your order.

Example of URL called during customer payment validation:

  • en vert, the URL passed during payment initialization, with the transId added to link the response to a merchant ID

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 serveurthe PayId parameter added by the server.


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

Que faire lorsque vous recevez cet appel ?


What to Do When You Receive This Call?

When one of these URLs is called:

  1. Retrieve the PayId parameter.

  2. Call the API to get the actual transaction status

À 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

  2. : GET /payments/getByPayId/{payId} - Retrieve payment details by Payment ID

  3. Mettez à jour votre commande en fonction du status et du responseCode.
  4. Update your order based on the status and responseCode.


Important Fields in the API Response

  • Amount

Champs importants dans la réponse API

Montant
  • : value, capturedValue, refundedValue
Identifiants
  • Identifiers: payId, transId, xId, refNr
Statut
  • Status: status = AUTHORIZED, CAPTURED, FAILED, etc.
Résultat
  • Result:
    • responseCode = "00000000"
si succès
    • if successful
    • responseDescription = text message
textuel


Exemple de réponseExample Response

Code Block
languagejson
titleExemple réponse résumé getByPayId
linenumberstrue
 {
	"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"
	}
}


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 


The Webhook notification is the only reliable way to be informed of transaction completion. It is essential for the merchant site to process requests received at the Webhook URL.

This notification is sent even if the customer:

  • Closes their browser,
  • Loses connection,
  • Doesn't return to your site.


When is it sent?

At the end of each asynchronous payment processing.


What you need to do

  1. Read the JSON payload
  2. Identify the transaction via payId or transId
  3. Update your system
  4. Respond with a 200 OK status code
Tip

Important:

Never trigger order finalization based solely on the Return URL.

Always use the webhook as the reliable source of information

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

Code Block
languagejson
titlewebhook payload
linenumberstrue
{
    "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-VersionVersion du format de la signature (actuellement, v1)
X-Paygate-TimestampUnix epoch timestamp (secondes depuis 1970-01-01T00:00:00Z, UTC)
X-Paygate-Signature

Signature dans le format v1=&lt;hex-hmac&gt;
Peut supporter de multiple signature, pour gérer le renouvellement des clés (e.g. v1=&lt;hmac1&gt;,v2=&lt;hmac2&gt;)


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

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.