In 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-betaling.

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.

Inhoudstafel

1. URLs doorgeven: return, cancel, webhook

Bij het initialiseren van de betaling moet u een URLs-object opgeven.

2. Return URL & Cancel URL

Een van deze twee URL's (return 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

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: GET /payments/getByPayId/{payId} –  Retrieve payment details by Payment ID
3. Werk de bestelling bij op basis van de status en responseCode.

Belangrijke velden in de API-respons:

Voorbeelden van samengevatte responsen:

3. Webhook

Aan het einde van de transactieverwerking meldt Axepta BNP Paribas Online 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:

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:

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

Voorbeeld

Beveiliging en verificatie

Om de authenticiteit van webhookgegevens te garanderen, worden payloads ondertekend met HMAC-SHA256. 

De handtekening wordt meegestuurd in drie HTTP-headers:

Signature headers

Signature Generation (Axepta BNP-Paribas Online)

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

• secret – HMAC key
• De gegenereerde handtekening wordt hex-gencodeerd en als header meegegeven:

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

Signature Verification (Merchant)

1. Extraheer de headers:
   • X-Paygate-Timestamp
   • X-Paygate-Signature
2. Haalt de raw JSON-payload op (exacte binaire body).
3. Bereken de HMAC:
   • signed_payload = timestamp + "." + raw_body
   • expected_signature = HMAC_SHA256(secret, signed_payload)
4. Vergelijk de handtekeningen met een "constant-time"-methode.
5. Valideer de webhook als:
   • De handtekeningen identiek zijn,
   • Het tijdstempel binnen ±5 minuten van uw lokale klok valt.

Voorbeeld van authenticiteitsverificatie:

• 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:

• 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