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:

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.

Table of Contents

1. Provide URLs : return, cancel, webhook

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

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. Haalt 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 je 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

Aan het einde van de transactieverwerking meldt Axepta BNP Paribas Online

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 je systeem.

• Verzonden via een HTTP REST-oproep naar de webhook-URL die je bij de betalingsinitialisatie hebt opgegeven.
• Wordt verzonden, zelfs als de klant:
  • De browser sluit,
  • De verbinding verliest,
  • Niet terugkeert naar je 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 je doen?

1. Lees de JSON-payload.
2. Identificeer de transactie met payId of transId.
3. Werk je 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:

1. Extraheer de headers:
   • X-Paygate-Timestamp
   • X-Paygate-Signature

1. Haalt de raw JSON-payload op (

1. exacte binaire body).

1. Bereken de HMAC:
   • signed_payload = timestamp + "." + raw_

1. • body
   • expected_signature = HMAC_SHA256(secret, signed_payload)

1. Vergelijk de handtekeningen met een "constant-time"

1. -methode.

1. Valideer de webhook

1. als:

1. • De handtekeningen identiek zijn,
   • Het tijdstempel binnen ±5 minuten van je 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"
}

Verificatie:

Berekening:

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

Best Pratices voor Integratie