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

You will 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 the webhook.

Table of Contents

1. Provide URLs : return, cancel, webhook

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

2. Return URL & Cancel URL

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

• Redirect the customer back to the merchant website at the end of the transaction
• Inform the merchant of the transaction status: (successful or not)
• Return to the merchant’s back-office the unique transaction identifier payId generated by Axepta Online

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

What to Do When You Receiving This Call?

When one of these URLs is triggered:

1. Retrieve the PayId parameter.

2. Call the API to get the actual transaction status: GET /payments/getByPayId/{payId} - Retrieve payment details by Payment ID

3. Update your order based on the status and responseCode.

Key fields in the API Response

• Amount: value, capturedValue, refundedValue
• Identifiers: payId, transId, xId, refNr
• Status: status = AUTHORIZED, CAPTURE_REQUEST, OK, FAILED, etc.
• Result:
  • responseCode = "00000000" OR "0" indicates success
  • responseDescription = textual message

Examples of summarized responses

3. Webhook

At the end of transaction processing, Axepta BNP Paribas Online notifies the merchant website of the final transaction result.

The webhook notification is the only reliable way to be informed of transaction completion.

It is mandatory for the merchant system to process webhook calls.

It is sent via an HTTP REST call to the webhook URL provided during payment initialization.

It is sent even if the customer:

• Closes their browser,
• Loses connection,
• Does not return to your website.

General recommandations

Correct implementation of webhook reception is essential to ensure real-time updates of your transaction statuses and to guarantee the reliability of your ordering process.

To ensure the proper functioning of the service, we recommend applying the following technical prerequisites:

1) Connectivity and Network Security

In order for our servers to route notifications to your infrastructure, your network security rules must be configured as follows:

⚙️ Port Configuration Notifications are transmitted via the HTTPS protocol.

• Required Port: Port 443 must be open and accessible for inbound traffic on your server.
• Important: The use of non-standard ports (e.g., 8097, 8443) is not supported by the platform and will result in notification delivery failure. If your application listens on a specific port, we recommend implementing a reverse proxy or a routing rule to redirect traffic from port 443 to your application.

🌐 IP Whitelisting To secure your exchanges while allowing the reception of flows, you must authorize (whitelist) the IP address ranges of our technical provider, Computop. Please configure your firewalls (Firewalls / NSG) to accept incoming requests from the following IPs:

• 213.155.65.64/26
• 213.95.169.128/27
• 217.92.237.167

2) Technical Requirements for the Endpoint (Reception URL)

🔒 Protocol and Certificates

• HTTPS Mandatory: The notification URL must be secured via HTTPS.
• TLS Version: The destination server must support TLS 1.2 or higher.
• Certificates: We recommend using an SSL certificate issued by a recognized Certificate Authority (CA).

🚀 Performance and Availability

• Response Time: Your endpoint must respond quickly to avoid timeouts.
• Response Code: To confirm the successful reception of the notification, your server must return an HTTP 200 OK code. Any other code (e.g., 4xx or 5xx) will be considered a delivery failure and may trigger retry attempts.

3) Implementation Recommendations (Best Practices)

To make your integration more resilient, we recommend adopting the following mechanisms:

🛡️ Fallback Mechanism While webhooks are the preferred method for transaction notifications, intermittent network incidents may occur. 

Recommendation: Implement an active polling mechanism using the Get Payment Details by TransID operation. If a webhook is not received within a defined timeframe, your system should be able to query the API to retrieve the actual status of the transaction.

🔍 Signature Validation To guarantee the authenticity of notifications and ensure they originate from Axepta BNP Paribas, we recommend implementing the verification of the signature headers (HMAC) provided in each request.

When is it sent?

After each asynchronous payment processing completion

If the endpoint is unavailable, the notification is retried up to 8 times

What you must do

1. Read the JSON payload
2. Identify the transaction using payId or transId
3. Update your system accordingly
4. Respond with HTTP 200 OK

Webhook Structure

Provided Fields

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

Example

Security and Verification

To ensure the authenticity of webhook data, payloads are signed using HMAC-SHA256.

The signature is included in three HTTP headers within the webhook message.

Signature headers

Multiple Keys

It is possible to configure up to two sets of keys for API Authentication and Signature generation.

The keys are defined in the merchant portal and are labeled:
- Primary (v1)
- Secondary (v2)

 The key version used by the Axepta Platform for webhook signatures (v1 or v2) depends on the key used by the merchant during the authentication process.
For example, if the merchant authenticates using the Secondary (v2) REST API Key, the Secondary (v2) REST HMAC Key will be used for signature generation, and the X-Paygate-Signature header will start with: "v2=...".

The Key version used by Axepta Platform for webhook signature (v1 or v2) is choosed accordingly to key used by the Merchant during the authentication process (v1 or v2)

Key rotation

Two sets of keys can be configured, but only one set is active at a time (the one selected during the authentication process).
This allows you to update the inactive set, configure and distribute keys across all equipment, and then switch to the new version when ready.

Signature Generation (Axepta BNP-Paribas Online)

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

• secret – HMAC key
• The generated Signature is encoded 'hex' and the header is set as follows:

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

Signature Verification (Merchant)

To verify the authenticity of the webhook message data:

1. Extract the data carried by the HTTP headers:

   • X-Paygate-Timestamp
   • X-Paygate-Signature

2. Retrieve the raw JSON payload (exact binary body)

3. Compute the HMAC using the extracted data

4. signed_payload = timestamp + "." + raw_body                                                                                                           expected_signature = HMAC_SHA256(secret, signed_payload)
5. Compare the calculated signature with the received signature using a "constant-time" method.
6. Validate the webhook if:
   1. The signatures are identical
   2. The Timestamp is within ±5 minutes of your local clock.

Webhook authenticity verification example:

Merchant Id used : BNP_DEMO_MID
Merchant Id HMAC Key : see Sandbox & Test page 

Transaction done the 19th of May, 2026, at 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"
}

Webhook Validation:

Signature verification:

Data used for signature: <epoch timestamp value>.<full webhook json body>
Value:

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

Computed HMAC-SHA256 with previous value as input, using 6Gp_A!8f)3zZ9K]gb7S?2*tN(yH54[wB key: 

df1f4aa6022460a9821832f9b89df82d92d01b35c80dddf596e97ff26e0abb14

Nota: signature verification should be done without case sensitivity

Integration Best Pratices