You can configure URL notifications (webhooks) to be submitted to your system automatically whenever transactions are processed on your site.
Configuring URL notification
We support three types of URL notifications, which can be enabled/disabled independently of each other, by updating your HTTPS POST with the examples below:
<!--This enables the successful URL notification rule-->
<input type=hidden name="ruleidentifier" value="STR-8">
<!--Successful URL notification destination-->
<input type=hidden name="successfulurlnotification" value="http://yourwebsite.com/successful"><!--This enables the declined URL notification rule-->
<input type=hidden name="ruleidentifier" value="STR-9">
<!--Declined URL notification destination-->
<input type=hidden name="declinedurlnotification" value="http://yourwebsite.com/declined"><!--This enables the all URL notification rule-->
<input type=hidden name="ruleidentifier" value="STR-10">
<!--All URL notification destination-->
<input type=hidden name="allurlnotification" value="http://yourwebsite.com/all">Any rule identifiers included in your post (e.g. “STR-8”) and the URLs submitted for the notification need to be included in the string used to generate your request site security hash. Failure to do so will result in the customer being shown an “Invalid details” error message.
Handling URL notifications
You must configure your system to accept the incoming URL notifications on port 443. If the response site security hash is correct, your system must respond with an HTTP 200 OK response (e.g. “HTTP/1.0 200 OK”) within 8 seconds of receiving a notification.
One notification is sent per request, but if your system does not respond, Trust Payments will continue to resend notifications for up to 48 hours until confirmation is received.
If we do not receive confirmation within 48 hours, we will send an email with further details to the default email address associated with your site reference (contact our Support Team to update this address).
Fields returned
URL notifications using system rules (STR-x) will include the following fields of information, by default:
- transactionreference
- requestreference
- orderreference
- sitereference
- errorcode
- settlestatus
- paymenttypedescription
The notification will also include the response site security hash (this is covered in further detail below).
If you would like to include additional fields, you can update your HTTPS POST to include stextraurlnotifyfields. The following example will include the billing first name, last name and email address in a URL notification, in addition to the default fields listed above:
<form method="POST" action="<DOMAIN>/process/payments/choice">
...
<input type="hidden" name="ruleidentifier" value="STR-10">
<input type="hidden" name="allurlnotification" value="http://www.yourwebsite.com/all">
<input type="hidden" name="stextraurlnotifyfields" value="billingfirstname">
<input type="hidden" name="stextraurlnotifyfields" value="billinglastname">
<input type="hidden" name="stextraurlnotifyfields" value="billingemail">
...
<input type="submit" value="Pay">
</form>Replace <DOMAIN> with a supported domain. Click here for a full list.
You will also receive a hashed responsesitesecurity value in any URL notifications sent to your system. We strongly recommend that you recalculate the responsesitesecurity hash returned, to ensure it has not been modified by a customer or third party and that the fields were sent by Trust Payments.
