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:

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

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: GET /payments/getByPayId/{payId} - Retrieve payment details by Payment ID

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

Important Fields in the API Response

• Amount: value, capturedValue, refundedValue
• Identifiers: payId, transId, xId, refNr
• Status: status = AUTHORIZED, CAPTURED, FAILED, etc.
• Result:
  • responseCode = "00000000" if successful
  • responseDescription = text message

Example Response

3. Webhook

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

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, it is signed using HMAC-SHA256.

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

Signature headers

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. Take the raw JSON payload data (the binary data received)

3. Calculate the HMAC with 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.

Integration Recommendations