PayEngine Notifications

Introduction

The main purpose of notifications is to inform integrated backend systems properly when specific events or updates occur within a payment process.

Notifications are highly recommended for all asynchronous payment methods where further actions from end customer are required. For synchronous payment methods notifications are possible but not critical from a security perspective.

Notification Types

There are two types of notifications, depending on the way in which a integrator is notified for a particular event or a set of events - webhook (URL) notifications and email notifications.

Webhook (URL) Notifications

Webhooks are notifications that deliver event information directly to an integrator's system by calling a script hosted on the integrator's server.

Webhooks are sent as HTTP POST requests on a given URI.

The accepted ports for HTTPS are 80, 8080 and 443. Receiving notifications via HTTPS is highly recommended from a security perspective.

To receive webhooks via HTTPS a valid SSL certificate must be in place.

The format of the webhook notifications depends on the version that will be used. For more information, see the specific notification version sections below.

Validation of Notifications

Integrators can validate a webhook notification by sending the received notification content without modifying the Payengine notification validation URL.

Payengine notification validation URLs in Sandbox and live environment:

Integrators must use the POST method for validation requests where the POST body should contain the notification content as received.

Integrators will receive one of the following responses of the validation request they sent:

• VALIDATED - when the notification content can be verified for the notification URNs.
• INVALID - when notification content cannot be verified for the notification URNs.

Email Notifications

Email notifications enable an integrator to be notified for a specific event or multiple events by receiving an email to a specified email address.

Email notifications are sent from no-reply@payengine.de and the content depends on the version that will be used.

For more details, see the Notification Version section below.

Subscription

To activate webhook or email notifications, the integrator must subscribe for notifications on an event level.

You can subscribe for notifications directly via API within an order - related request, or via configuration in the Merchant Center.

Subscription via Merchant Center

For more specific instructions on how to subscribe for notifications via Merchant Center, see Merchant Center Notifications.

Subscription via API

You can subscribe for notifications via API for all payment methods, regardless of the technical flow type (synchronous or asynchronous).

You can subscribe for notifications via API, using the async.notifications object within the preauth or debit request.

The required parameters depend on the notification version, referenced in the Notification Version 1.0 or Notification Version 2.0 subsections.

Retry Mechanism

To sucessfully receive notifications for subscribed events is underpinned by Payengine retry mechanism.

The retry mechanism is applicable for webhook and email notifications, and covers three tiers of attempts to send a notification:

When the server responsible for receiving a notification is down, a retry attempt will be executed. Depending on its number, the retry attempt will be executed with a predefined delay, specific for each tier of retries.

The total number of retry attempts for a notification is 16 which is the total of all attempts from all tiers and one additional attempt.

Notification Version 1.0

Notification Version 1.0 is the initial version of notifications implemented within Payengine. While this version is still supported and used, it can be regarded as depricated.

We highly recommend the implementation of Notification Version 2.0 which offers a simplified message format for webhooks and especially for email notifications.

Events

The following events are supported with Notification version 1.0:

Transaction Events

Customer Events

Payment Intstrument Events

Order Events

Format

The content will be presented are JSON objects, inline with the formatting and requirements, known to the Payengine REST API.

There is no difference between webhook or email notifications, both use the JSON format.

{
      "notificationApiVersion": "1.0",
      "createdAt": 1534959158570,
      "payload": {

Subscription via API

The following parameters are required in the async.notification object to subscribe to a Notification version 1.0 via API requests.

"async": {
  "successUrl": "https://a.success.url",
  "failureUrl": "https://a.callback.url",
  "cancelUrl": "https://a.cancel.url",

Notification Version 2.0

Events

The following table lists all supported events, grouped by category, and specifies which events are available through which channel.

Format

Webhook

All notifications will be in a JSON format. The parameter depends on the notification category.

{
  "notificationApiVersion": "2.0",
  "notificationId": "notification_ewnozkeo6z",
  "globalTrackId": "XLg5rFkDCps-XAAa-qpMuwAAAAQ",

Transaction Parameter

3DS Parameter

Email

The email notification should include a pre-defined set of parameters, limited to the most relevant parameters.

NOTE Currenlty only transaction - related events are supported.

Subscription via API

The following parameters are required in the async.notification object to subscribe to a Notification version 2.0 via API requests.

Parameter: notificationUrn

The URN to which the notification should be sent to.

Number of notification URNs, which can be specified when setting up notifications via API, is limited to 8.

There are three options for the type of specified notification URNs:

Notification URNs to be specified only as URLs with an upper limit of eight URLs. Notification URNs to be specified only as email addresses with an upper limit of eight emails. Notification URNs to be specified as a combination of URLs and email addresses with a combined upper limit of eight URLs and emails.

Parameter: notificationVersion

1.0 or 2.0

In case the notificationVersion is not provided automatically, version 1.0 should be used for the notifications

notificationEvent

Supported values: see the values from Events abovesection.

Integrators should explicitly specify the events they are interested in rather than wildcard everything.

NOTE: Only the events that are supported for the corresponding transaction type should be raised as a notification. The others should be ignored.

"async": {
                ...
                "notifications": [
                  {