Notifications API

NotificationRequest

These are the fields that can be included in a notification message.

Field Type Required Description
live String (tick)

Informs about the origin of the notification:

  • true: the notification originated from the live environment.
  • false: the notification originated from the test environment.
notificationItems Array of NotificationRequestItem objects (tick) A container object for the details included in the notification.

NotificationRequestItem

A container object for the details referring to a single transaction.

Field Type Required Description
additionalData Object (error)

The additionalData object is a generic container that can hold extra fields.

It contains the following elements:

  • shopperReference
  • shopperEmail
  • authCode
  • cardSummary
  • expiryDate
  • authorisedAmountValue
  • authorisedAmountCurrency
  shopperReference String (error)

The ID that uniquely identifies the shopper. This shopperReference is the same as the shopperReference used in the initial payment.

This field is returned in case of recurring contract notifications.

  shopperEmail String (error)

The shopper's email address.

This field is returned in case of recurring contract notifications.

  authCode String (error)

Authorisation code: 

  • When the payment is authorised successfully, this field holds the authorisation code for the payment. 
  • When the payment is not authorised, this field is empty.
  cardSummary String (error)

Returns the last 4 digits of the credit card.

Only digits allowed. No alphabetic characters.
  expiryDate String (error)

Returns the card expiry date.

  • Format: MM/YYYY

authorisedAmountValue String (error)

Value of the amount authorised.

Scenario 1 - Zero value auth transaction

Some issuers don't allow a zero value transaction. In this case Adyen authorises a minimum amount, for example Euro 1.00, to verify the shopper's card. After successful authorisation, Adyen's system automatically cancels the authorisation. The actual authorised amount is returned in this field which may differ from the amount sent in in the payment request.

Scenario 2 - Available amount

A shopper makes a transaction of Euro 10 using a gift card but the card contains only Euro 06. In this case, Adyen deducts the available amount and keeps the pending amount open to be completed with other payment options. The authorised amount is returned in this field.

You can enable this feature in your Customer Area:

  1. Go to Settings > Server Communication.
  2. Next to Standard Notification, click Edit & Test.
  3. Under Additional Settings, toggle Include Authorised Amount (dynamic zero auth).
  4. Click Save Configuration.
  authorisedAmountCurrency String (error)

Currency of the authorised amount.

amount Amount (tick)

A container object for the payable amount information for the transaction.

For HTTP POST notifications, currency and value are returned as URL parameters

pspReference

String

(tick)

Adyen's 16-character unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

In REPORT_AVAILABLE response you receive a file name in this field.

In PAIDOUT_REVERSED event code pspsreference is for Capture's pspsreference.

eventCode String (tick)

The type of event the notification item refers to.

When eventCode returns AUTHORISATION , it does not necessarily mean that the payment authorisation request has been successfully processed.

The authorisation is successful if successtrue.

If success = false, check the  the reason value for further information on the authorisation failure cause.

This can occur, for example, if an error occurs or if the transaction is refused.

eventDate String (tick)

The time when the event was generated.

  • Format: ISO 8601;  YYYY-MM-DDThh:mm:ssTZD
  • Example: 2017-07-17T13:42:40+01:00
merchantAccountCode

String

(tick) The merchant account identifier used in the transaction the notification item refers to.
operations List (tick)

This field holds a list of the modification operations supported by the transaction the notification item refers to.

The available operations in the list give information on the follow-up actions concerning the payment.
You may be requested to:

  • Capture the payment (for example, if auto-capture is not set up),
  • Cancel the payment (if the payment has not been captured yet), or
  • Refund the payment (if the payment has already been captured).

Possible values:

  • CANCEL
  • CAPTURE
  • REFUND

This field is populated only in authorisation notifications.

In case of HTTP POST notifications, the operation list is a sequence of comma-separated string values.

merchantReference

String

(tick)

A reference to uniquely identify the payment.
This reference is used in all communication with you about the payment status.
We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field.
Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

By default, merchantReference is always returned with payment notifications,
as merchantReference returns the reference field value of the corresponding payment request.
In this case, returned by default = (tick)

Modification requests do not require sending a merchant reference value along with the call.
Therefore, the corresponding notifications do not include it by default.
In this case, returned by default = (error)

An empty merchantReference field in a notification message takes null as a value.

originalReference String (error)

If the notification item is about a payment authorisation, this field is not populated and is blank.

If the notification item is about a modification, the originalReference value corresponds to the pspReference value assigned to the original payment.

paymentMethod String (tick)

The payment method used in the transaction the notification item refers to.

Example payment methods that can be set to this field:

visa, mc, ideal, elv, wallie, and so on.

This field is populated only in authorisation notifications.
reason

String

(error)

This field is included only in some notifications.

This field holds plain text. The value varies depending on whether the outcome of the event is successful or not (successtrue or false):

If... ...then:
  • eventCodeAUTHORISATION
  • successtrue
  • paymentMethod = visamc or amex

reason includes the following details:

  • Authorisation code
  • Last 4 digits of the card
  • Card expiry date

Format:

6-digit auth code:last 4 digits:expiry date

Example:

874574:1935:11/2012

  • success = false
reason includes a short message with an explanation for the refusal.
  • eventCode = REPORT_AVAILABLE
reason includes the download URL where you can obtain a copy of the report.
  • eventCode = PAIDOUT_REVERSED

reason field in the notification contains the bank statement description if present, else it contains PaidOutReversed.

success String (tick)

Informs about the outcome of the event (eventCode) the notification refers to:

  • true: the event (eventCode) the notification refers to was executed successfully.
  • false: the event was not executed successfully.

When eventCode returns AUTHORISATION , it does not necessarily mean that the payment authorisation request has been successfully processed.

The authorisation is successful if successtrue.

If success = false, check the  the reason value for further information on the authorisation failure cause.

This can occur, for example, if an error occurs or if the transaction is refused.