Before proceeding, please ensure you have met all requirements
Click here to open this information in a new tab
Features
Our Payment Pages solution is for merchants who want a simple and easily-implemented way of adding e-payment capability to their online commerce systems. Payment Pages work with custom-designed e-commerce systems as well as with many commercially available shopping cart applications.
Use this integration if you need a ready-built hosted checkout that supports the following features:
- Process payments on dedicated HTTPS servers hosted by Trust Payments (that use the SSL protocol) that allow you to process secure and reliable transactions.
- Trust Payments handles the customer’s payment session, including any Strong Customer Authentication (SCA) required by 3-D Secure.
- Your servers don't need to handle sensitive payment credentials, simplifying PCI compliance.
- Customise the Payment Pages with custom CSS to maintain the look and feel of your online store.
- Accept a large variety of currencies.
- Track all transactions using our online transaction management system, MyST.
1. Construct a basic payment form
Here is an example HTML form that can be used as a template when redirecting your customers to the Payment Pages. Start by copying and pasting the below to a text file and save as an HTML form.
<html>
<body>
<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="submit" value="Pay">
</form>
</body>
</html>Replace <DOMAIN> with a supported domain. Click here for a full list.
Change the site reference in the HTML to include the test site reference provided when you signed up. Update the other fields as needed, using the table below. For now, we’re only covering the required fields, but you can submit more fields if needed (click here for a full list).
| Required fields | Description |
| sitereference | The unique reference that you receive when you sign up. |
| currencyiso3a | The transaction currency code (in ISO3A format). |
| mainamount |
The amount of the transaction should be in main units. Only include the amount value and the decimal place (no commas). e.g. £10.99 would be submitted as 10.99 Currencies such as Japanese Yen which do not require a decimal place are submitted without. e.g. 1000 Yen would be 1000 |
| version | This value will be set to 2. |
| stprofile |
Used to specify the styling used to render the Payment Pages. When using the default appearance, this is set to “default” (click here for further information on profiles). |
Click here for full field specification
Save the above as an HTML file. You can open this in your web browser, and a “Pay” button will be displayed. Click this button, and you will be redirected to your test site, where you can process test payments.
If you have configured the HTML above correctly, you should be able to view the following Payment Page hosted by Trust Payments:
When testing, you can use the following test card details to simulate a “Successful” response:
- Visa card ‘4111 1111 1111 1111’ or Mastercard ‘5100 0000 0000 0511’
- Set expiry date to any valid date in the future
- Use security code “123”
2. Redirect customer's browser following payment
By default, when a transaction has been processed, our response page will be displayed to the customer. This displays a message indicating whether or not the transaction was successful, along with details regarding the payment for the customer’s records. Alternatively, you may prefer to host a response page on your own server to be displayed following a successful transaction.
Redirects can be configured on your site by adding the following to your POST to Payment Pages:
<!--Enables rule that redirects the customer following a successful transaction-->
<input type=hidden name="ruleidentifier" value="STR-6">
<!--Update the below with the URL for the redirect-->
<input type=hidden name="successfulurlredirect" value="http://yourwebsite.com/successful">The URL of your hosted response page must be externally facing. We cannot redirect to internal, intranet, private or loopback addresses.
We recommend only redirecting to secure HTTPS pages. When using iframes, some web browsers will refuse to redirect to non-secure pages as a security measure.
If an error occurs (e.g. decline), we will redisplay the payment form with an error, prompting them to try a different method of payment (recommended). Alternatively, you can instead opt to redirect customers back to your site when an error occurs. Click here to learn more.
3. Configure notifications to your server
You can request notifications be sent following transactions on the Payment Pages.
Configuring notifications
Click the headings below to learn how to configure notifications that are sent following different transaction outcomes:
These are sent to the email address specified in the billingemail field. They are configured to be sent to customers following payment, summarising the transaction and acting as a receipt of payment for their records. By default, they look like this:
It is simple to enable email notifications on a transaction-by-transaction basis. For requests where you would like to receive customer email notifications, you will need to add the following fields to your POST to the Payment Pages:
<!--Sends email confirmation to the customer, following successful transaction:-->
<input type=hidden name="ruleidentifier" value="STR-2">
<!--Sends email confirmation to the customer, following declined transaction:-->
<input type=hidden name="ruleidentifier" value="STR-3">You can customise the appearance of emails sent to the customer:
- Swap out the Trust Payments logo for your own company logo.
- Customise layout and appearance of email by uploading your own markup.
These are configured to be sent to members of your company or organisation, and are sent to an email address of your choosing. By default, they look like this:
It is simple to enable email notifications on a transaction-by-transaction basis. For requests where you would like to receive merchant email notifications, you will need to add the following fields to your POST to the Payment Pages:
<!--Sends email confirmation to the merchant, following successful transaction:-->
<input type=hidden name="ruleidentifier" value="STR-4">
<!--Sends email confirmation to the merchant, following declined transaction:-->
<input type=hidden name="ruleidentifier" value="STR-5">
<!--IMPORTANT: You also need to include the merchant’s email address for merchant emails to work-->
<input type=hidden name="merchantemail" value="merchant@email.com">You can configure URL notifications (webhooks) to be submitted to your system automatically whenever transactions are processed on your site. 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">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 (see below), 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
Please refer to the following resources for further information:
Customer email notifications Merchant email notifications URL notifications
4. Secure your requests using Site Security
For security reasons, your system must include the additional field sitesecurity in the POST, to ensure requests to the Payment Pages cannot be modified by a customer or third party. This field contains a hash that is generated from a selection of designated fields, including a password that has been established with the Support Team.
First, you will need to learn how to generate the site security hash:
Click here to open the instructions in a new tab on how to generate the sitesecurity hash.
Follow these instructions carefully and then look at the final step below to submit the hash in your POST.
When posting to the Payment Pages, you will need to include the sitesecurity and sitesecuritytimestamp fields in the POST, as shown below:
<html>
<head>
</head>
<body>
<!--YOUR HTML-->
<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="hidden" name="orderreference" value="myorder12345">
<input type="hidden" name="sitesecurity" value="hee879a9ab97753b3a768925d50842f10e19fea03fef0b820026b6df92d415866">
<input type="hidden" name="sitesecuritytimestamp" value="2019-05-28 14:22:37">
<input type="submit" value="Pay">
</form>
</body>
</html>
Replace <DOMAIN> with a supported domain. Click here for a full list.
As accurately as possible, the sitesecuritytimestamp should reflect the time the customer’s browser is to be redirected to the Payment Pages.
The value submitted in this field must be in the format YYYY-MM-DD hh:mm:ss.
The timestamp must be in the UTC time zone. (e.g. “2019-05-28 14:22:37”)
The customer has 3 hours from the time specified to complete the transaction, otherwise an error will be displayed on screen.
For any payment that is attempted with an incorrect hash, the customer will be presented with an error (example below) and no payment will be processed:
Response site security
After request site security has been enabled on your site, the redirects and URL notifications configured above will also include the response site security hash. This is in the form of a hashed responsesitesecurity value in any URL notifications sent to your system. You must 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.
Once you have completed the steps above, we recommend returning to the Getting started page to learn more about enabling add-ons, testing your solution and going live.
