Contents

Action types

 

We will automatically perform an Action when criteria of a condition have been met. This page explains the different types of actions that can be configured on your Secure Trading account.

 


 

URL notifications

URL notification actions are requests sent from Secure Trading to a pre-defined URL.
These notifications contain information about requests processed on your Secure Trading account.

 


 

Info
We do not support localhost, loopback or multicast IP ranges in the URL.

 

There are three different notification flows you can choose from:

 

Online

 

Offline

 

Failover

 

Notification
If multiple online notification actions meet the required conditions to be triggered, only the first online notification will be processed during the request and any other online notifications will be discarded. If there are no online notifications triggered but there are multiple failover notifications, only the first failover notification will be processed during the request and any other notifications will be scheduled to be sent at a later time (treated as offline notification).

 

Format of URL notification

The notification sent from Secure Trading will include a valid HTTP/1.1 Content-type header to be accepted by your system. For example:

 


Content-type: application/x-www-form-urlencoded; charset=UTF-8

 

The included field names and data will be urlencoded.

For example, if the notification contains the fields “baseamount”, “errorcode” and “orderreference” with values “2499”, “0” and “customerorder1” respectively, then the notification may look like the following (notificationreference field is always returned):

 


baseamount=2499&errorcode=0&notificationreference=1-A60356&orderreference=customerorder1

 

Authentication (notification security)

To ensure the notification has not been modified by a malicious user, a field called responsesitesecurity can be included in the POST to your system, when configuring the notification in MyST. This field contains a cryptographic hash of a predefined set of field values.

Using the example above, with the addition of a notification password of “password”, using the sha256 security algorithm, the notification may look like the following:

 


baseamount=2499&errorcode=0&notificationreference=1-A60356&orderreference=customerorder1&responsesitesecurity=033e6bcc1971f150c5a6d5487548b375b8971c9bdc1962b2cc1844d26ff82c2a

 

Padlock
If you update your action to use a new notification password, all future notifications sent from the queue (offline or failover) will include a notification hash generated using the new password.

 

Step 1: To check the notification is legitimate, concatenate the values of all the fields in the request (excluding notificationreference and responsesitesecurity), in order of field name, in ASCII alphabetical order:

 


24990customerorder1

 

Step 2: To the end of this, append your notification password. This leaves:

 


24990customerorder1password

Where “password” would be replaced with your own notification password.

 

Notification
If a field returned in a notification has multiple values (e.g. fieldname=bravo&fieldname=alpha), these are concatenated in the order they were submitted in request. When included in the example above, the string generated would be:

 


24990bravoalphacustomerorder1password

 

 

Step 3: Then generate a hexadecimal hash of this value using sha256 and ensure the value matches the value in responsesitesecurity:

 


033e6bcc1971f150c5a6d5487548b375b8971c9bdc1962b2cc1844d26ff82c2a

 

If the generated hexadecimal hash does not match the responsesitesecurity received from Secure Trading, the notification should not be accepted. In such a case, please contact our Support Team.

 

Using Secure Socket Layer (SSL/TLS)

You can set up your system to receive URL notifications using SSL/TLS. In order to do so, your server must present a valid TLS certificate chain to the Secure Trading notifications client. A valid certificate contains the domain of the Notification URL in the common name of the certificate and the chain must correctly validate to an accepted certificate authority.

 

You must configure your system to accept incoming URL notifications on port 443.

Padlock
If the certificate is not signed by a known certificate authority (for example Verisign), your test notifications may work but you will need to use a valid CA for live transactions.

 

Response to Secure Trading

You must configure your system to respond to a notification with an HTTP 200 OK response. For example: “HTTP/1.0 200 OK”.

Your system must reply within 8 seconds of receiving a notification.

 

Retrying notifications

A notification is sent shortly after the criteria defined in the filters have been fulfilled. One notification is sent per request.

Notification
Each notification contains a unique reference that is called notificationreference. If we fail to receive a response to an offline or failover notification, the notification will be resent with the same notification reference for up to 48 hours.

 

Email alerts for failed URL notifications

Once a day, we will send email alerts for failed URL notifications on your account. A URL notification failure may be attributed to an invalid URL or if we fail to receive a response from your system.

The alert is sent to the email address of the user that configured the notification and has a subject of “Notification Problems”. For example:

 

 

Envelope
Ensure your email server is configured to accept all incoming emails from [email protected].

 

Fields to include

We recommend including at least the following fields as a minimum for inclusion in typical URL notifications:

 


 

Update response action

This action is used to automatically update the status of a request after it has been processed by the acquirer and the associated condition(s) has been met. e.g. For authorisations, where the results of the AVS checks return a “Not matched” postcode response, update the settle status in order to suspend the payment.

 


 

Info
By implementing the update response action, transactions may be left in a different status than before. Therefore, when enabling an update response rule, ensure any other active rules are updated to take this account.