Customise the appearance of Payment Pages – Trust Payments

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 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 an allowlist 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 allowlist, 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 allowlist for any of your site references in future, please contact our Support Team with your request. We will update the configuration accordingly and notify you when the work has been completed.

If you have any questions or require further clarification, please do not hesitate to contact us.

What is an stprofile?

To customise 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:

Diagram showing how stprofile=birthday could be used to apply a birthday card theme and likewise for stprofile=christmas.

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 will need to upload them via the Portal File Manager. Learn more about the File Manager.

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.

Diagram that represents the details page, with the text field &quotHouse name/no.&quot highlighted for emphasis.

Field types

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}}

Screenshot with text that reads: "You can use the following reference to track your order: ABC123"

Text fields

A text field allows the customer to type in new info. e.g.

Please enter your postcode: {{st.billingpostcode.textfield}}

Screenshot with a text field with label "Please enter your postcode:"

Drop-downs

Drop-downs allow customers to select info from a list. e.g.

Country: {{st.billingcountryiso2a.dropdown}}

Screenshot with a text field with label "Country"

Certain fields do not support being displayed as text input or drop-downs.

Pre-fill and validation

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.

Diagram representing the details page, with the error "There has been a problem with your payment" highlighted for emphasis.

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 fields

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.

Notifications and redirects

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.

Field Reference

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. Full list of country codes.
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. “0” – Not eligible for Credentials on File, or no intention of re-using credentials at a later time. “1” – Transaction credentials flagged as available for future use. “2” – Payment using previously-stored credentials.
currencyiso3a	The currency in 3-character format. Full list of currency codes.
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. Full list of country codes.
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: 1 – DCC Offered & Accepted The customer has accepted the offer of DCC and has chosen to pay in their card issuer's currency. 2 – DCC Not Available The customer pays in the merchant's currency. (e.g. the CURRENCYRATE request encountered an error) 3 – DCC Offered & Refused The customer has refused the offer of DCC and chosen to pay in the merchant’s currency.
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: “A” – Re-authorisation “C” – Unscheduled payment “D” – Delayed Charges “S” – Resubmission “X” – No-show (for a hotel booking)
issuenumber	The issue number printed on the card.
issuer	The card issuer.
issuercountryiso2a	Two-digit country code for the card issuer. Full list of country codes.
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 the Trust Payments 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.

Diagram showing how using st.block.paymentdetailsdiv in the HTML will display a form for user to enter their card details.

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
Block	Choice	Details	Locked	3-D Redirect	Response
{{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 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 File Manager in your HTML:

Include {{stresource.<filename>}} in your HTML:

{{stresource.companylogo.gif}}

To reference images uploaded to your account using the Portal 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, drawing from the block and field references above.

{{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>

After you have written the necessary mark-up, you can then upload the files using the File Manager. Ensure the files meet our naming conventions.

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. View full domain list.