Skip to content

    PayEngine Notifications


    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.


    Integrators have to validate the notifications they have received.

    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.


    When the formatting is incorrect, Payengine might not be able to validate notifications.

    The reason for such validation errors can be:

    • Whitespace changes, reformatting or similar actions, in cases of deserialization and serialization before validation;
    • Changes of the line endings;
    • Validating notifications prior to responding to Concardis with HTTP 200;
    • Sending address parameter in POST URL not URL-encoded.

    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 and the content depends on the version that will be used.

    For more details, see the Notification Version section below.


    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:

    Number of TierNumber of AttemptsDelay Between Sent Attempts in Milliseconds
    Tier 1510000
    Tier 2560000
    Tier 35600000

    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 2.0


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

    CategoryEventTransaction TypeStatusWebhookEmail
    Transactiontrx.preauth.failurePREAUTHFAILURE, ABORTED, DECLINED, EXPIREDyesyes
    Transactiontrx.cancel.failureCANCELFAILURE, DECLINEDyesyes



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

    Sample async.notifications object

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

    Transaction Parameter

    notificationApiVersionVersion of the notification service, always set to "2.0"
    notificationIdPayengine notification identifier
    globalTrackIdPayengine global tracking ID (for debugging)
    eventTypeType of the event, for example trx.debit.success
    createdAtTimestamp of the event
    merchantIdPayengine merchantId
    transactionIdPayengine transactionId
    transactionAmountAmount of the transaction event
    currencyCurrency code

    3DS Parameter

    notificationApiVersionVersion of the notification service, always set to "2.0"
    notificationIdPayengine notification identifier
    globalTrackIdPayengine global tracking ID (for debugging)
    eventTypetype of the event, for example trx.debit.success
    createdAttimestamp of the event
    merchantIdPayengine merchantId
    threeAuthenticationIdIdentifier of the 3DS authentication transaction generated by the Payengine if the transaction was triggered through a dedicated authentication service
    orderDataOrder object in case the authentication was triggered as part of an order
    orderData.transactionIdPayengine transactionId


    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.

    StatusEvent type status
    TimestampTimestamp of the transaction update
    Merchant IDPayengine merchant identifier
    Order IDPayengine orderId
    Transaction IDPayengine transactionId for this event
    Merchant Order IDMerchant order reference
    Order AmountOrder amount
    CurrencyCurrency of the order
    Transaction AmountTransaction amount for the transaction status, might fully match the order amount

    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

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


    Supported values: see the values from Events above section.

    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.

    The notificationState should not be used anymore for version 2.0.


    "async": {
                    "notifications": [

    Was this helpful?

    What was your feeling about it?