In this section, you will find everything you need to manage the various entry points that your application will receive during and after an dit gedeelte vind je alles wat je nodig hebt om de verschillende instappunten te beheren die je applicatie ontvangt tijdens en na een Axepta BNP Paribas Online payment-betaling.

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.

Je leert:
- Welke URL's je moet doorgeven bij het aanmaken van een betaling,
- De volgorde waarin ze worden aangeroepen,
- Hoe je de geretourneerde informatie moet interpreteren,
- Hoe je de daadwerkelijke status van een transactie kunt verifiëren,
- Hoe je de webhook beheert.

InhoudstafelTable of Contents

1.

URLs doorgeven: return, cancel, webhook

When initializing the payment, you must provide a URLs object:Bij het initialiseren van de betaling moet u een URLs-object opgeven.

2. Return URL & Cancel URL

Een van deze twee URL's (return

• 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

of cancel) wordt aangeroepen aan het einde van de transactieverwerking om:

• De klant terug te sturen naar de website van de handelaar,
• De handelaar te informeren over de transactiestatus (geslaagd of niet),
• Het unieke transactie-ID (payId) door te geven aan het back-officesysteem van de handelaar.

Axepta BNP Paribas Online voegt automatisch de volgende parameter toe: zie Integratieaanbevelingen

What to Do When You Receiving This Call?

Wat te doen bij ontvangst van deze oproep?

1. Haal de PayId-parameter op.
2. Roep de API aan om de daadwerkelijke transactiestatus op te halen

When one of these URLs is triggered:

1. Retrieve the PayId parameter.

Call the API to get the actual transaction status
2. : GET /payments/getByPayId/{payId}
- 
3. –  Retrieve payment details by Payment ID
Update your order based on the status and
4. Werk de bestelling bij op basis van de status en responseCode.

Key fields Belangrijke velden in the API Responsede API-respons:

Voorbeelden van samengevatte responsen:Examples of summarized responses

3. Webhook

At the end of transaction processing, Aan het einde van de transactieverwerking meldt 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?

 het definitieve transactieresultaat aan de website van de handelaar. De webhook-melding is de enige betrouwbare manier om op de hoogte te worden gebracht van de voltooiing van een transactie. Verplicht voor handelaren: verwerk webhook-oproepen in uw systeem.

• Verzonden via een HTTP REST-oproep naar de webhook-URL die u bij de betalingsinitialisatie hebt opgegeven.
• Wordt verzonden, zelfs als de klant:
  • De browser sluit,
  • De verbinding verliest,
  • Niet terugkeert naar uw website.

Wanneer wordt de webhook verzonden?

Na elke asynchrone verwerking van een betaling. Als het eindpunt niet beschikbaar is, wordt de melding tot 8 keer opnieuw verzonden:

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

Wat moet u doen?

1. Lees de JSON-payload.
2. Identificeer de transactie met payId of transId.
3. Werk uw systeem bij.
4. Reageer met HTTP 200 OK.

Webhook Structuur

Meegestuurde velden:

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

ExampleVoorbeeld

Security and Verification

Beveiliging en verificatie

Om de authenticiteit van webhookgegevens te garanderen, worden payloads ondertekend met To ensure the authenticity of webhook data, payloads are signed using HMAC-SHA256. 

De handtekening wordt meegestuurd in drie HTTP-headers: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 followsDe gegenereerde handtekening wordt hex-gencodeerd en als header meegegeven:

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

Signature Verification (Merchant)

To verify the authenticity of the webhook message data:

Extract the data carried by the HTTP
1. Extraheer de headers:
   • X-Paygate-Timestamp
   • X-Paygate-Signature
Retrieve the
2. Haalt de raw JSON-payload op (
exact binary
3. exacte binaire body).
Compute the HMAC using the extracted data
4. Bereken de HMAC:
   • signed_payload = timestamp + "." + raw_
body                                                                                                           
5. • body
   • expected_signature = HMAC_SHA256(secret, signed_payload)
Compare the calculated signature with the received signature using a
6. Vergelijk de handtekeningen met een "constant-time"
method
7. -methode.
Validate the
8. Valideer de webhook
if
9. als:
   • The signatures are identical
   • The Timestamp is within ±5 minutes of your local clock.
   • • De handtekeningen identiek zijn,
     • Het tijdstempel binnen ±5 minuten van uw lokale klok valt.

Voorbeeld van authenticiteitsverificatie:

Webhook authenticity verification example:

• Handelaars-ID: 

• BNP_DEMO_MID

• HMAC

• -sleutel: zie Sandbox & Testpagina.
• Transactiedatum: 19 mei 2026, 09:23:20 (Parijse tijd, 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 ValidationVerificatie:

BerekeningSignature verification:

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

• Data

• voor handtekening: 1779175402.<volle JSON-body>
• Verwachte HMAC-SHA256 (met sleutel 

• 6Gp_A!8f)3zZ9K]gb7S?2*tN(yH54[wB

• ): 

• df1f4aa6022460a9821832f9b89df82d92d01b35c80dddf596e97ff26e0abb14

Nota: signature verification should be done without case sensitivity

Best Pratices voor Integratie