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.

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.

Image Added

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