Our hosted Payment Pages integration supports deep customisation of layout and appearance with custom HTML, CSS and JavaScript.
How does it work?
- Write custom HTML / CSS / JS markup.
- Upload files to our platform via the Portal / MyST File Manager to form an stprofile.
- Update the HTTPS POST to Payment Pages to apply an stprofile at checkout.
Content Security Policy (CSP)
If you would like to implement custom styling to your Payment Pages, you will need to contact our Support Team to ensure CSP-blocking is enabled on your test site reference. You will also need to provide a list of trusted URIs (Uniform Resource Indicators) that are to be permitted access from your mark-up. Typical examples would be when you need to reference externally-hosted scripts or images for purposes of rendering certain visual aspects of your checkout and/or to perform analytics.
Note: To include a URI in the white-list, the resource needs to be loaded over HTTPS.
We will block communications to any URIs not present in the aforementioned list to better protect your account from interference by unauthorised third parties. For this reason, it is important to thoroughly test your changes on your test site reference before applying to your live site reference.
Should you need to update the URI whitelist for any of your site references in future, please contact our Support Team with your request and we will update the configuration accordingly. We will notify you when the new URIs have been whitelisted and are available to use as part of your solution.
If you have any questions or require further clarification, please do not hesitate to contact us.
What is an stprofile?
To customise to the appearance and layout of Payment Pages, you will need to make use of stprofiles.
An stprofile consists of custom HTML, CSS and/or JavaScript files that work together to apply changes.
You can set up multiple stprofiles to apply different layouts and/or styling depending on the situation.
e.g. For a greeting cards shop, you could have different stprofiles for each department or product type:
By updating the POST to Payment Pages, a custom stprofile can be applied for each customer session.
If a custom stprofile isn’t specified, the default Trust Payments-branded pages are displayed.
File naming conventions
Markup is assigned to stprofiles by prefixing the filename with the name of the stprofile.
So you will need to start by deciding the name of your stprofile(s).
If you intend on using the same styling for all customer sessions, you only need to concern yourself with naming one stprofile that you can apply to every transaction.
If you need the style to differ depending on the situation, you will need to plan more than one stprofile.
When naming your stprofile, please be aware of the following requirements:
- stprofile names must only include lowercase letters and/or numbers (max length 20).
- stprofile names must not include uppercase letters, punctuation or spaces.
With the stprofile name decided, the markup files uploaded must follow the naming listed below:
(Replace [stprofile] with the name of your stprofile)
- [stprofile]choice.html - Page where customer selects their payment method.
- [stprofile]details.html - Page where customer enters their payment details.
- [stprofile]locked.html - Page shown when customer refreshes while their payment is being processed.
- [stprofile]3dredirect.html - Page shown when customer is being redirected to 3-D Secure authentication.
- [stprofile]response.html - Page shown to customer following transaction completion.
- [stprofile].css - You can upload a single CSS file that will modify all pages for the given stprofile.
- [stprofile].js - You can upload a single JS file that will modify all pages for the given stprofile.
We'll go on to explain what to put in these files next, but when you're ready, you can refer to these links for info on how to upload them to our system via the File Manager: Portal / MyST
Note: While multiple stprofiles can be defined for a single site reference, the files you upload can only be used on the site reference they are uploaded to. To use an stprofile over multiple sites, the files must be uploaded separately to each site reference where they are needed.
Writing markup
When writing your HTML code, you will need to make use of in-built fields and blocks in order to display fields on the pages when rendered by Trust Payments.
If you customise your site’s Payment Pages, it is your responsibility to ensure your solution remains compliant with relevant schemes.
Fields
You can include st.field in your HTML to easily display information from the session, and inputs such as text-boxes and drop-down boxes as part of the rendered page. Using CSS and HTML, you can fully customise these elements, and their location on the page.
The following are examples of the types of fields to be included in your HTML code:
Values
A value is used to display previously-entered info. e.g.
You can use the following reference to track your order: {{st.orderreference.value}}
Text fields
A text field allows the customer to type in new info. e.g.
Please enter your postcode: {{st.billingpostcode.textfield}}
Drop-downs
Drop-downs allow customers to select info from a list. e.g.
Country: {{st.billingcountryiso2a.dropdown}}
Certain fields do not support being displayed as text input or drop-downs.
The HTML forms outlined in previous sections are automatically pre-filled with information from the session, if it has already been provided. If the customer fails to provide information in all the required fields or enters invalid information, the payment will not continue and the field in question will be highlighted on screen.
All Trust Payments fields are validated. Custom fields cannot be validated by Trust Payments.
Field errors are only shown to the customer if the relevant input fields are included on the page
e.g. If an invalid email address has been submitted in post, the customer will be unable to correct this on the Payment Pages if this input field has been hidden from view, meaning they will not be able to complete their payment.
Please ensure that all data has been validated to our specification before posting to the Payment Pages, OR that you display the necessary billing / delivery details on the Payment Pages to allow the customer to make changes if necessary.
Custom text input fields and values can be entered in the same way as the built-in fields outlined previously. e.g.
Enter your Membership Id: {{st.memberid.textfield}}
This is your Membership Id: {{st.memberid.value}}
- The st.field functionality does not support drop-downs for custom fields.
- Trust Payments cannot validate custom fields.
The majority of fields used in a Payment Pages session, including custom fields, can be posted to your website as part of a redirect or as part of a URL notification.
Key |
- Values that can be displayed - Text fields that users can type into - Drop-downs users can select from |
Field |
Description |
accounttypedescription |
The type of account the request is processed through (e.g. “ECOM”, “MOTO”). |
authcode |
The authorisation code is provided by the card issuer on authorisation. |
ban |
Bank transfer-specific field: Customer’s bank account number. |
bankid |
Bank transfer-specific field: Customer’s bank id. |
bankname |
Bank transfer-specific field: Name of the customer’s bank. |
baseamount |
The amount in base units with no commas or decimal points. For example £10.50 in base units is “1050”. |
bic |
Valid BIC (Bank Identifier Code) of customer’s bank. |
billingcountryiso2a |
Two digit country code for the billing address. For a list of country codes, click here. |
billingcounty |
County for the billing address. |
billingdob |
Date of birth of the account-holder. |
billingdobday |
Date of birth of the account-holder (the day). |
billingdobmonth |
Date of birth of the account-holder (the month). |
billingdobyear |
Date of birth of the account-holder (the year). |
billingemail |
Email address for billing. |
billingfirstname |
First name for billing details. |
billinglastname |
Last Name for billing details. |
billingmiddlename |
Middle name or initial for billing details. |
billingpostcode |
The postcode for the billing address. |
billingprefixname |
Billing Name Prefix. For example, “Mr”, “Mrs”, “Miss”, “Dr”. |
billingpremise |
The first line of the billing address. |
billingstreet |
The street name of the billing address. |
billingsuffixname |
Billing name suffix. For example “Phd”, “BSc MEng”. |
billingtelephone |
The telephone number for the billing address. |
billingtelephonetype |
This is an attribute for the telephone number. The options available are: “H” = Home, “M” = Mobile, “W” = Work. |
billingtown |
The town of the billing address. |
credentialsonfile |
The allowed values for this field are 0, 1 and 2.
|
currencyiso3a |
The currency in 3 character format. For a list of currencies, click here. |
customeraccountnumber |
If account number type is “ACCOUNT”, the account holder’s account number. If account number type is “CARD” the account holder’s card number (UK-based debt repayment accounts only). |
customeraccountnumbertype |
Either “CARD” or “ACCOUNT”. (UK-based debt repayment accounts only). |
customercountryiso2a |
Two digit country code for the customer address. For a list of country codes, click here. |
customercounty |
County for the customer address. |
customerdob |
Customer Date of Birth in the format YYYY-MM-DD. |
customerdobday |
Customer Date of Birth (the day). |
customerdobmonth |
Customer Date of Birth (the month). |
customerdobyear |
Customer Date of Birth (the year). |
customeremail |
The customer’s email address. |
customerfirstname |
The customer’s first name. |
customerip |
The IP of the customer. |
customerlastname |
The customer’s last name. |
customermiddlename |
The customer’s middle name. |
customerpostcode |
The customer’s address postcode. |
customerprefixname |
The prefix of the customer’s name (e.g. “Mr”, “Miss”, “Dr”). |
customerpremise |
The customer’s address premise (house name or number). |
customerstreet |
The customer’s address street name. |
customersuffixname |
The suffix of the customer’s name (e.g. “Bsc”). |
customertelephone |
The customer’s telephone number. |
customertelephonetype |
This is an attribute for the telephone number. The options available are: “H” = Home, “M” = Mobile, “W” = Work. |
customertown |
The town of the customer’s address. |
dccbaseamount |
DCC-specific: The amount you would like to be credited in the Merchant’s Currency. This amount in base units with no decimal points, so £10.50 would be “1050”. |
dccconversionrate |
DCC-specific: The conversion rate used to calculate the amount in the Customer’s Currency. |
dccconversionratesource |
DCC-specific: The source of the conversion rate returned from the DCC provider. |
dcccurrencyiso3a |
DCC-specific: The Merchant’s Currency in iso3a format. |
dccenabled |
DCC-specific: Indicates if the transaction was processed using DCC. “1”= Yes, “0” = No. |
dccexpirytimestamp |
DCC-specific: The expiry date of the CURRENCYRATE look-up. Subsequent requests using the CURRENCYRATE as a parent must settle before this date and time. Format: YYYY-MM-DD HH:MM:SS. |
dccmainamount |
DCC-specific: The amount you would like to be credited in the Merchant’s Currency. This amount in main units, with decimal points, so £10.50 would be “10.50”. |
dccmarginratepercentage |
DCC-specific: The percentage used to calculate the currency conversion fee (4 decimal places), automatically added to the amount in the Customer’s Currency by the DCC provider. |
dccoffered |
DCC-specific: The following values can be returned:
|
dccprovider |
DCC-specific: The name of the third-party DCC provider that has provided the conversion rate used in the payment. |
dccproviderdata |
DCC-specific: A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers. |
dccratio |
DCC-specific: The ratio between the amount in the Customer’s Currency and the amount in the Merchant’s Currency, processed in the request in main units. |
dcctype |
DCC-specific: Either “DCC” or “CPC”. |
debtrepayment |
Indicates if transaction is flagged as debt repayment:
1 – Transaction is flagged as debt repayment. 0 – Transaction is not flagged as debt repayment. |
errorcode |
A code to indicate result of the transaction. The code will be “0” if the transaction was successful. |
errordata |
Additional information to help troubleshoot an error. |
errormessage |
A text description to indicate the result of the transaction. The message will be “Ok” if the transaction was successful. |
expirydate |
The expiry date printed on the card. |
expirymonth |
The month of the expiry date printed on the card. |
expiryyear |
The year of the expiry date printed on the card. |
facilitatorid |
The payment facilitator id assigned by Mastercard at time of registration. |
facilitatorname |
The payment facilitator name agreed with Mastercard. |
iban |
Bank transfer-specific field: Customer’s international bank account number. |
independentsalesorgid |
The ISO (Independent Sales Organisation) id assigned by Mastercard at time of registration. |
initiationreason |
These are the values we currently support:
|
issuenumber |
The issue number printed on the card. |
issuer |
The card issuer. |
issuercountryiso2a |
Two digit country code for the card issuer. For a list of country codes, click here. |
mainamount |
This amount in main units, with decimal points, so £10.50 would be “10.50”. |
mandatereference |
Unique reference that identifies each direct debit. |
maskedachaba |
ACH-specific field: Masked transit routing number. |
maskedachaccountnumber |
ACH-specific field: Masked account number. |
maskedban |
Bank transfer-specific field: Masked bank account number. |
maskedcustomeraccountnumber |
If account number type is “ACCOUNT”, the account holder’s account number. If account number type is “CARD” the account holder’s card number (UK-based debt repayment accounts only). (masked) |
maskediban |
Bank transfer-specific field: Masked international bank account number. |
maskednationalid |
The customer’s social security number. (masked) |
maskedpan |
This is the card number printed on the front of the customer’s card. (masked) |
merchantemail |
The merchant’s email address. |
merchantname |
The merchant’s name. |
nationalid |
The customer’s social security number. |
operatorname |
The value of this field contains the name of the user that processed the request. |
orderreference |
Your unique order reference that can be stored on Trust Payments’s system. |
pan |
This is the card number printed on the front of the customer’s card. |
paymenttypedescription |
The customer’s payment method, for example “VISA” or “MASTERCARD”. |
paypalemail |
The email address that the customer will use to sign in to PayPal. |
rewardid |
The reward id. |
securitycode |
Security code printed on the card. |
settleduedate |
The day you would like the transaction to settle. It must be in the format YYYY-MM-DD. |
settlestatus |
This value relates to the status you would like to set the transaction. |
sitereference |
Unique reference to your site, received on setup. |
startdate |
Start date printed on the card. |
startmonth |
Month of the start date printed on the card. |
startyear |
Year of the start date printed on the card. |
submerchantid |
Value assigned by the payment facilitator when involved in the transaction. |
subscriptionbegindate |
The date of when the first recurring subscription payment will be processed. |
subscriptionfinalnumber |
The number of subscriptions to be processed in total over the course of the subscription (including the initial authorisation). |
subscriptionfrequency |
Combined with the subscriptionunit field, this defines how frequently payments are processed. |
subscriptionnumber |
The position of the transaction within a series of Subscription payments. |
subscriptiontype |
The type of Subscription, as required by the acquiring bank. The value can either be “INSTALLMENT” or “RECURRING”. |
subscriptionunit |
The unit of time between each subscription. This can be either “DAY” or “MONTH”. |
transactionreference |
Unique reference of the transaction, available after a payment request has been processed. |
transactionstartedtimestamp |
Timestamp of when the transaction was processed. |
walletdisplayname |
The name of the wallet used with the transaction. |
walletsource |
The transaction wallet source. |
Blocks
An st.block is a reference you can include in your HTML to display grouped page elements when the page is rendered, instead of defining each element individually. Blocks are written as follows (including curly brackets): {{st.block.blockname}}
e.g. When passing the reference {{st.block.paymentdetailsdiv}} on the payment details page, Trust Payments will display the payment fields when rendering the page.
Block Reference
Key
Blocks that are supported on a given page are labelled with a green tick: | |
Some blocks are Required on a given page. These are shown with a pink double-tick icon: |
|
Some blocks are only required in certain conditions. These are shown with a yellow square icon: |
|
Not all blocks are supported on all pages. Unsupported blocks are shown with a cross icon: |
Block |
Ability to include on each page |
||||
Choice | Details | Locked | 3-D Redirect | Responsee | |
{{st.block.header}} Displays the Trust Payments header. |
|||||
{{st.block.requiredjs}} Required for use of EMV 3DS and digital wallets. |
|||||
{{st.block.hiddendiv}} Contains required session info for correct operation. One of these blocks is required on the Choice page |
|||||
{{st.block.smallpaymentchoicesdiv}} Displays small logos for customers to select their payment method. One of these blocks is required on the Choice page |
|||||
{{st.block.standardpaymentchoicesdiv}} Displays regular-sized logos for customers to select their payment method. One of these blocks is required on the Choice page |
|||||
{{st.block.defaultcss}} Applies the default Trust Payments CSS. |
|||||
{{st.block.defaultjs}} Applies the default Trust Payments JS. |
|||||
{{st.block.doctype}} Contains the HTML DOCTYPE declaration. |
|||||
{{st.block.footer}} Displays the Trust Payments footer. |
|||||
{{st.block.messagesdiv}} Displays success/warning/error messages in the browser. |
|||||
{{st.block.metatags}} Contains metadata about the page used by Trust Payments. |
|||||
{{st.block.profilecss}} Ensures your custom CSS is applied. |
|||||
{{st.block.profilejs}} Ensures your custom JS is applied. |
|||||
{{st.block.billingresponsediv}} Displays the billing response details. |
|||||
{{st.block.deliveryresponsediv}} Displays the delivery response details. |
|||||
{{st.block.orderdetailsdiv}} Displays the order information. |
|||||
{{st.block.billingdetailsdiv}} Displays form for customers to enter their billing details. |
|||||
{{st.block.deliverydetailsdiv}} Displays form for customers to enter their delivery details. |
|||||
{{st.block.processingpaymentdiv}} Displays loading message while payment is processed. |
|||||
{{st.block.billingdetailsdivcountystatedropdown}} Displays form for entering billing details. (For US users, billing county is shown as billing state) |
|||||
{{st.block.currencydetailsdiv}} Displays DCC selection information. |
|||||
{{st.block.deliverydetailsdivcountystatedropdown}} Displays form for entering delivery details. (For US users, delivery county is shown as delivery state) |
|||||
{{st.block.paymentdetailsdiv}} Displays form for customers to enter their payment details. |
|||||
{{st.block.requirednoticediv}} Text that explains how * next to a field means it's required. |
|||||
{{st.block.lockeddiv}} Displays the payment locked message. |
|||||
{{st.block.3dredirectdiv}} Handles the redirect to EMV 3DS. |
|||||
{{st.block.currencyresponsediv}} Displays the DCC response details. |
|||||
{{st.block.transactionresponsediv}} Displays the transaction response details. |
Body class
Trust Payments recommends specifying {{st.bodyclass.value}} in the class attribute of the body tag on all pages, to ensure shortcuts appear with the correct styling in the following situations:
- If you are planning on using Trust Payments CSS with modifications.
- If you are planning on uploading CSS that applies different styling depending on the page being rendered.
For example: <body class=”{{st.bodyclass.value}}”>
Images
We recommend that you only reference files stored in the Portal / MyST File Manager and not an external source, otherwise the customer’s browser may show a warning that the page isn’t secure.
To reference images uploaded to your account using the Portal / MyST File Manager in your HTML:
Include {{stresource.<filename>}} in your HTML:
{{stresource.companylogo.gif}}
To reference images uploaded to your account using the Portal / MyST File Manager in your CSS or JavaScript:
Use the relative path as follows:
/merchantfiles/<first 3 numbers of site ref>/<site reference>/<filename>
Example:
<img src=”/merchantfiles/018/testsite018/companylogo.gif” alt=”companylogo” />
We recommend that you only reference custom files stored in the File manager and not an external source, otherwise the customer’s browser may show a warning that the page isn’t secure.
Examples
The following are examples of customised pages using the ST blocks. Please feel free to use these templates to help build your own pages, using the block and field reference as a guide.
{{st.block.doctype}}
<html>
<head>
{{st.block.metatags}}
{{st.block.defaultcss}}
{{st.block.profilecss}}
{{st.block.requiredjs}}
{{st.block.defaultjs}}
{{st.block.profilejs}}
</head>
<body class="{{st.bodyclass.value}} st-inputs-style st-blocks-style">
{{st.block.header}}
<div class="st-content">
{{st.block.messagesdiv}}
<h2>Order details</h2>
{{st.block.orderdetailsdiv}}
<h2>Payment choice</h2>
{{st.block.standardpaymentchoicesdiv}}
</div>
{{st.block.footer}}
</body>
</html>
{{st.block.doctype}}
<html>
<head>
{{st.block.metatags}}
{{st.block.defaultcss}}
{{st.block.profilecss}}
{{st.block.requiredjs}}
{{st.block.defaultjs}}
{{st.block.profilejs}}
</head>
<body class="{{st.bodyclass.value}} st-inputs-style st-blocks-style">
{{st.block.header}}
<div class="st-content">
{{st.block.messagesdiv}}
<h2>Order details</h2>
{{st.block.orderdetailsdiv}}
<h2>Change payment type</h2>
{{st.block.smallpaymentchoicesdiv}}
<form name="paymentsdetails" id="paymentsdetails" method="post" action="details">
{{st.block.hiddendiv}}
<h2>Billing details</h2>
{{st.block.billingdetailsdiv}}
<h2>Delivery details</h2>
{{st.block.deliverydetailsdiv}}
<h2>Payment details</h2>
{{st.block.paymentdetailsdiv}}
{{st.block.requirednoticediv}}
</form>
</div>
{{st.block.footer}}
</body>
</html>
{{st.block.doctype}}
<html>
<head>
{{st.block.metatags}}
{{st.block.defaultcss}}
{{st.block.profilecss}}
{{st.block.requiredjs}}
{{st.block.defaultjs}}
{{st.block.profilejs}}
</head>
<body class="{{st.bodyclass.value}} st-inputs-style st-blocks-style">
{{st.block.header}}
<div class="st-content">
{{st.block.messagesdiv}}
{{st.block.hiddendiv}}
{{st.block.orderdetailsdiv}}
<h2>3-D Secure Process</h2>
{{st.block.3dredirectdiv}}
</div>
{{st.block.footer}}
</body>
</html>
{{st.block.doctype}}
<html>
<head>
{{st.block.metatags}}
{{st.block.defaultcss}}
{{st.block.profilecss}}
{{st.block.defaultjs}}
{{st.block.profilejs}}
</head>
<body class="{{st.bodyclass.value}} st-inputs-style st-blocks-style">
{{st.block.header}}
<div class="st-content">
{{st.block.messagesdiv}}
<h2>Order details</h2>
{{st.block.orderdetailsdiv}}
<h2>Transaction response</h2>
{{st.block.transactionresponsediv}}
<h2>Billing details</h2>
{{st.block.billingresponsediv}}
<h2>Delivery details</h2>
{{st.block.deliveryresponsediv}}
</div>
{{st.block.footer}}
</body>
</html>
{{st.block.doctype}}
<html>
<head>
{{st.block.metatags}}
{{st.block.defaultcss}}
{{st.block.profilecss}}
{{st.block.defaultjs}}
{{st.block.profilejs}}
</head>
<body class="{{st.bodyclass.value}} st-inputs-style st-blocks-style">
{{st.block.header}}
<div class="st-content">
{{st.block.messagesdiv}}
{{st.block.lockeddiv}}
</div>
{{st.block.footer}}
</body>
</html>
Update POST to Payment Pages
After you have uploaded the required files, they can be used to render your pages by adding the following mark-up to your checkout form, including the name of your stprofile:
<input type=’hidden’ name=’stprofile’ value='[name of stprofile]’>
- When the stprofile name is included in the POST, the associated files are used (if available) for each Trust Payments-hosted page.
- When the stprofile is not included in the POST, the default styling will be used during the payment process.
The following examples are for when starting the payment process on the "Choice" page and "Details" page:
<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="birthday">
<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="submit" value="Pay">
</form>
</body>
</html>
<html>
<head>
</head>
<body>
<!--YOUR HTML-->
<form method="POST" action="<DOMAIN>/process/payments/details">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="stprofile" value="birthday">
<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="paymenttypedescription" value="VISA">
<input type="hidden" name="orderreference" value="myorder12345">
<input type="submit" value="Pay">
</form>
</body>
</html>
Replace <DOMAIN>
with a supported domain. Click here for a full list.