This page explains the "URL notification" Action type that can be configured in the Rule Manager.
Remember: Trust Payments will perform an Action when all criteria of a Condition have been met.
Required user roles
Admin, Developer
Conditions and Actions can only be managed by the users that created them.
How to access
Select your site from the “Sites” page and click the “Rule Manager” icon.
Then select the "URL notification" Action type from the drop-down box and click “Go”.
URL notification Actions are requests sent from Trust Payments to a pre-defined URL.
These notifications contain information about requests processed on your Trust Payments account.
We do not support localhost, loopback or multicast IP ranges in the URL.
There are three different notification flows you can choose from:
1. Online
- The notification will be processed during the transaction.
- Your customer will be made to wait for your server to respond.
- In the event of failure, the notification will not be retried.
2. Offline
- The notification will be scheduled during the transaction.
- Scheduled notifications will be processed as soon as possible after the customer has been shown a response.
- In the event of failure, the notification will be retried for approximately 48 hours.
3. Failover
- The notification will be processed during the transaction.
- Your customer will be made to wait for your server to respond.
- In the event of failure, the notification will be scheduled to be sent again and will be retried for approximately 48 hours.
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 Trust Payments 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¬ificationreference=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 Portal. 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¬ificationreference=1-A60356&orderreference=customerorder1&responsesitesecurity=033e6bcc1971f150c5a6d5487548b375b8971c9bdc1962b2cc1844d26ff82c2a
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.
You will need to re-generate this hash on your own server and check this matches the value we return in the notification. Here's how to do so:
-
Start by concatenating the values of all the fields in the request (ensuring that you include any custom fields present, while excluding notificationreference and responsesitesecurity), in order of field name, in ASCII alphabetical order.
24990customerorder1
-
To the end of this, append your notification password. This leaves:
24990customerorder1passwordWhere “password” would be replaced with your own notification password.
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
-
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 Trust Payments, the notification should not be accepted. In such a case, please contact our Support Team.
Response to Trust Payments
A notification is sent shortly after the criteria defined in the filters have been fulfilled. One notification is sent per request.
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. If you fail to respond, we will continue to resend the notification for up to 48 hours.
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.
URL notification failures will trigger an email that summarises affected transactions. We will email this to you daily until the issues are resolved. This could happen if an invalid URL is specified in the Action, or we fail to receive a response from your system, as described above.
If you receive an email from "support.stpp@securetrading.com" with the subject “Notification Problems”, please be aware that your system may not have received notifications for the transactions outlined in the email. You will need to investigate why the errors occurred and take steps to resolve the problem. If you need assistance, please contact our Support Team.
Using Secure Socket Layer / Transport Layer Security (SSL/TLS)
You can set up your system to receive URL notifications using SSL/TLS. To do so, you must meet the following requirements:
- You must configure your system to accept incoming URL notifications on port 443.
- Your server must present a valid TLS certificate chain to the Trust Payments notifications client:
- The certificate must contain the domain of the Notification URL in the common name.
- The chain must correctly validate to an accepted certificate authority.
- The certificate must be signed by a known, trusted Certificate Authority (for example Verisign).
You are responsible for renewing SSL certificates before they expire. Expired certificates will cause notification failures.
If the certificate is not signed by a known Certificate Authority, your test notifications may work but you will need to use a valid Certificate Authority for live transactions.
Fields to include
When creating the Action, use the “Fields” tab to specify fields to be included in the notification.
Start to type the name of the fields you would like to include to filter down the list displayed, and tick the fields to add them to the Action.
We recommend including at least the following fields as a minimum for inclusion in typical URL notifications:
- Acquirer Response Code (acquirerresponsecode)
- Acquirer Response Message (acquirerresponsemessage)
- Auth Code (authcode)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Parent Transaction Reference (parenttransactionreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
