Skip to main content

Session notifications

If a notificationUrl is provided with the request, notifications about changes (for example, the associated payment transaction completed or failed) will be POSTed to that URL asynchronously (independently from the user's browser session.) You can use these notifications to apply relevant updates within your own system.

Example session notifications​

Succesful checkout session:​

{
  "outcome": "Success",
  "sessionId": "ac097ba17bcb437f8c966895ecc6aa06",
  "reference": "TestRef",
  "amount": 30000,
  "currencyCode": "EUR",
  "createdAt": "2025-01-03T10:47:16.4777072Z",
  "paymentTakenAt": "2025-01-03T10:48:50.035Z",
  "transactionId": "LAGERMAN-3DSV2-684c3fac-dee8-499d-b246-0873078046f4",
  "token": "58-9-3988545",
  "providerName": "SecureTrading",
  "cardType": "VISA",
  "errorCode": null,
  "errorMessage": null,
  "acquirerResponseCode": null
}

Failed checkout session:​

{
  "outcome": "Failure",
  "sessionId": "bf261e90ab2c44c78b03d52aedf192af",
  "reference": "TestRef",
  "amount": 70000,
  "currencyCode": "EUR",
  "createdAt": "2025-01-10T11:59:33.3265623Z",
  "paymentTakenAt": null,
  "transactionId": "LAGERMAN-3DSV2-61fd0b29-2109-4704-bf0f-c113c14d6218",
  "token": "56-9-3985377",
  "providerName": null,
  "cardType": null,
  "errorCode": "decline",
  "errorMessage": "SecureTrading: Decline. No further data.",
  "acquirerResponseCode": "05"
}

Authorization​

Requests sent to the notification URL will include an Authorization header with Basic Authentication. The credential included depends on how the checkout session was originally created:

  • Sessions created with product-level authentication: The notification will include Authorization: Basic base64(ProductId:ProductApiKey). The recipient should validate the decoded credentials against the expected ProductId and ProductApiKey.
  • Sessions created with client-level authentication (or if no product API key is found): The notification will include Authorization: Basic base64(ClientId:ClientApiKey) as described under Authorization.

You can Base64 decode the Basic Authentication text and cross-check it against the appropriate credentials to guard against unauthorized requests. We recommend that you refuse requests that have a missing or incorrect Authorization header with a 401 Unauthorized error.

Example header (client-level)​

For instance, a session notification request for a session created with client-level authentication could include the following Authorization header:

  • Header Name: Authorization
  • Header Value: Basic TEFHRVJNQU46OTQzZjM2Mjk0N2EyNDA0NTgyYTI2ODkzN2QyM2JjMzM=

Taking the Basic Authentication text and Base64 decoding it gives the following:

LAGERMAN:87ba874b8a5049beadc9710984606715

You can then compare this with your ClientId and APIKey and, if they match, apply any relevant updates to your system based on the session notification. Otherwise, you can discard the request and return a 401 Unauthorized error.

Example header (product-level)​

For a session created with product-level authentication, the notification could instead include:

  • Header Name: Authorization
  • Header Value: Basic TVlQUk9EVUNUOmFiYzEyM2RlZjQ1NmdoaTc4OWprbDAxMm1ubzM0NXBx

Taking the Basic Authentication text and Base64 decoding it gives:

MYPRODUCT:abc123def456ghi789jkl012mno345pq

You can then compare this with the ProductId and ProductApiKey. If they match, apply any relevant updates to your system. Otherwise, discard the request and return a 401 Unauthorized error.