Customise the appearance of Payment Pages

  Last updated: 

 

Our hosted Payment Pages integration supports deep customisation of layout and appearance with custom HTML, CSS and JavaScript.

 

How does it work?

paint-website-nobackground.png

  1. Write custom HTML / CSS / JS markup.
  2. Upload files to our platform via the Portal / MyST File Manager to form an stprofile.
  3. 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:

CP67-EN.png

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.

CP53-EN.png

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

CP54-EN.png

  Text fields

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

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

CP55-EN.png

  Drop-downs

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

Country: {{st.billingcountryiso2a.dropdown}}

CP56-EN.png

 

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.

CP57-EN.png

  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. 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.
  • “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. 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:

  • 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. 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.

CP58-EN.png

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.

choice.html details.html 3dredirect.html response.html locked.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>Payment choice</h2>
{{st.block.standardpaymentchoicesdiv}}
</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 for posting to the "Choice" page HTML for posting to the "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>

Replace <DOMAIN> with a supported domain. Click here for a full list.

Was this article helpful?
0 out of 0 found this helpful