Introduction

Our Template Builder allows you to customise your payment pages for our Hosted Checkout Page and Hosted Tokenization Page solutions. By creating your own templates, you can adapt the look and feel of the secure payment pages according to your brand and requirements.

Our Hosted Tokenization Page offers the highest degree of customisation. Take a look at these features.
Encourage your customers to complete their order after being redirected to the Hosted Checkout Page.

We have two versions of the template live preview/editor, allowing you to test and create templates for both integration methods respectively:

Template preview/editor

The Template Builder consists of two main sections: the live preview and the editor. These sections allow you to visualize and modify your custom templates.

Live preview

The live preview provides a real-time rendering of various payment pages based on the editor HTML code. It offers the following options to simulate different scenarios/settings:

Payment page: displays different stages of the payment flow.
- PaymentMethodList: The page showing all available payment methods
- PaymentMethodForm: the form displayed to the consumer after selection of a payment method. Mind that some payment methods (i.e. Paypal) do not have forms because they redirect directly the consumer to an external payment platform
- Status pages: the payment result pages and redirection pages. Depending on the individual scenario / payment method a full transaction flow can include several steps. The flow of a PayPal transaction will be like this:

In contrast, a Visa transaction including strong 3DS authentication would cover more steps:

Screen size: simulates different type of devices
Currency: changes the currency of the payment pages
Language: changes the language used in the payment pages

You can incorporate various payment pages into a single template by using specific tags.

payment-paymentmethod-selection
payment-paymentmethod-form
payment-status-page

Those tags are rendered depending of the payment flow:

payment-paymentmethod-selection

List of payment methods:

payment-paymentmethod-selection
payment-paymentmethod-form

Payment method form:

payment-paymentmethod-form
payment-status-page

Status and redirection page:

payment-status-page

Our system automatically selects the appropriate tags based on the current step in the transaction flow. To update the live preview according to your selections or changes in the editor, simply click the "REFRESH" button.

Editor

The editor is where you define the HTML source code for your custom template. It displays the source code of the template currently visible in the live preview. You can either edit the provided default template or replace it entirely with your HTML code.
The left side of the editor contains a list of available tags that help you customize the template. Simply double-click on a tag to automatically add it to the source code at the current cursor position.

To ensure your work is saved, make sure to use the COPY TO CLIPBOARD button to save your template before closing your browser!

Template Format

The templates you create with the Template Builder are HTML documents. They contain special entities referred to as "tags" for dynamic parameters. We distinguish between simple and complex tags.

Simple Tags

These tags do not have content and are used to insert dynamic values, such as payment references or page titles.
The most basic syntax is:

<payment-tag />

Adding HTML attributes is allowed:

<payment-tag attribute />

<payment-tag attribute="value" />

However, adding attributes starting with payment- are not allowed.

Complex Tags

Complex tags render their content when they have the data to do so. In the example above, if no line items (shopping basket) are sent in your CreatePayment/CreateHostedCheckout request, payment-lineitems won't render anything.

Complex tags have content. The syntax is

<payment-tag> HTML code here </payment-tag>

Html attributes are allowed.

This is an example of a template containing complex tags "payment-lineitems" and "payment-lineitems-list":

<html>
   <body>
      <payment-lineitems>
         <table border="1">
            <tr>
               <th><payment-item-name-text /></th>
               <th><payment-number-items-text /></th>
               <th><payment-item-price-text /></th>
            </tr>
            <payment-lineitems-list>
             <tr>
                <td><payment-item-productname /></td>
                <td><payment-item-quantity /></td>
                <td><payment-item-totalamount /> <payment-currency /></td>
             </tr>
             </payment-lineitems-list>
          </table>
       </payment-lineitems>
    </body>
 </html>

Some complex tags, like payment-lineitems-list, render multiple times for each item sent in your request.

Payment Pages

To test your template in different scenarios, the "Payment page" option in the template builder contains three types of pages:

PaymentMethod List: the list of payment methods available to the consumer.
PaymentMethod Form: the form displayed to the consumer after selection of a payment method. Some payment methods don't have forms because they redirect directly the consumer to an external payment platform.
Status pages: the payment result pages but also the redirection pages.

You can include these pages in a single template using the following tags: payment-paymentmethod-selection, payment-paymentmethod-form and payment-status-page. These tags are rendered depending of the payment flow:

<payment-paymentmethod-selection>

List of payment methods:

</payment-paymentmethod-selection>
<payment-paymentmethod-form>

Payment method form:

</payment-paymentmethod-form>
<payment-status-page>

Status and redirection page:

</payment-status-page>

List of available tags

The following list provides an overview of all available tags and their usage hierarchy:

global: tags that can be used everywhere
root: tags that can be used outside of any tag
other tags are only available under specific parent tags, as specified in the list

Name	Description	Type / Available under
payment-about-link	An about link to inform consumers about the merchant	Simple global
payment-beneficiary	The commercial name set on your merchant account	Simple global
payment-beneficiary-text	The text 'Beneficiary'	Simple global
payment-currency	Currency of the payment	Simple global
payment-item-name-text	Text 'Item name'	Simple global
payment-item-price-text	Text 'Item price'	Simple global
payment-lang	Two letters language code of the payment (eg: EN)	Simple global
payment-legal-info-link	A link to the merchant's legal information page	Simple global
payment-mandatory-fields-text	The text explaining Mandatory-fields	Simple global
payment-number-items-text	Text 'Number of items'	Simple global
payment-orderid	Merchant reference of the order	Simple global
payment-orderid-text	Text 'Order reference'	Simple global
payment-order-overview-text	Text 'Order overview'	Simple global
payment-payid	Payment platform's reference of the payment	Simple global
payment-paymentmethod-form-text	Text 'PaymentMethod Form'	Simple global
payment-paymentmethod-selection-text	Text 'PaymentMethod Selection'	Simple global
payment-pay-with-text	Text 'Pay with'	Simple global
payment-privacy-policy-link	A link to the legal privacy page. MANDATORY.	Simple global
payment-processed-img	Image 'processed by'	Simple global
payment-security-link	A link to the security page	Simple global
payment-select-pm-text	Text to 'Select payment method'	Simple global
payment-total-amount	Total amount of the payment	Simple global
payment-total-amount-text	Text 'Total charge'	Simple global
payment-tp-resource-file	Render the resource file with subresource integrity check enabled	Simple global
payment-vatid-number	The VAT ID set on your merchant account	Simple global
payment-vatid-number-text	Text 'Vat ID'	Simple global
payment-cancel-button	The cancel button that can be used by consumers to prematurely end the checkout	Simple root
payment-lineitems	Complex tag enabled when request contains line items	Complex root, payment-paymentmethod-form, payment-paymentmethod-selection, payment-status-page
payment-lineitems-list	Complex tag enabled for each item in the line items	Complex payment-lineitems
payment-item-description	Description of this item	Simple payment-lineitems-list
payment-item-discountamount	Discount amount of this item	Simple payment-lineitems-list
payment-item-productcode	Product Code of this item	Simple payment-lineitems-list
payment-item-productname	Product Name of this item	Simple payment-lineitems-list
payment-item-productprice	Price amount of this item	Simple payment-lineitems-list
payment-item-producttype	Type of this item	Simple payment-lineitems-list
payment-item-quantity	Quantity of this item	Simple payment-lineitems-list
payment-item-taxamount	Tax amount of this item	Simple payment-lineitems-list
payment-item-totalamount	Total amount of this line item: quantity * (price + tax - discount)	Simple payment-lineitems-list
payment-item-unit	Unit of measure of this item	Simple payment-lineitems-list
payment-paymentmethod-form	Complex tag enabled when the consumer has to fill-in the payment form	Complex root
payment-change-paymentmethod-link	If brand is not requested, the link takes the customer back to payment method selection form	Simple payment-paymentmethod-form
payment-pm-acquirer	Acquirer name of the payment method	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-brand	Brand name of the payment method	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-image	Html 'img' of the payment method	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-image-url	URL to the image of the payment method	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-inputid	'id' to be used for the html input element	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-inputname	'name' to be used for the html input element	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-pm-paymentmethod	Name of the payment method	Simple payment-paymentmethod-form, payment-alias-section, payment-input-list, payment-input-info, payment-lineitems, payment-lineitems-list, payment-pm-list
payment-submit-button	Button to submit the payment method form	Simple payment-paymentmethod-form
payment-alias-section	Complex tag enabled when a token (alias) creation is requested and the selected payment method supports it	Complex payment-paymentmethod-form
payment-alias-input-label	Label for the token (alias) creation checkbox	Simple payment-alias-section
payment-alias-label-input	Checkbox for the token (alias) creation	Simple payment-alias-section
payment-alias-merchant-usage	Text explaining to the consumer why a token (alias) creation is requested	Simple payment-alias-section
payment-input-list	Complex tag enabled for each input the consumer has to fill-in	Complex payment-paymentmethod-form
payment-cobadging	Render the co-badging selection link/box in case the card number is detected as co-branded	Simple payment-input-list
payment-input-error	Html 'span' that will contain any validation error for this field	Simple
payment-input-id	'id' of the 'input-input' element	Simple payment-input-list
payment-input-input	Html 'input' or 'select' for the field that the consumer has to fill-in	Simple
payment-input-label	Html 'label' for the field	Simple payment-input-list
payment-paymentmethod-selection	Complex tag enabled when the consumer has to select a payment method	Complex root
payment-pmgroup-list	Complex tag enabled for each group of payment methods	Complex payment-paymentmethod-selection
payment-pm-group	Name of the group of the payment method	Simple payment-pmgroup-list, payment-pm-list
payment-pm-list	Complex tag enabled for each payment methods	Complex payment-pmgroup-list, payment-paymentmethod-selection
payment-pm-image-button	Html 'input' of type image that allows the consumer to select a payment method	Simple payment-pm-list
payment-status-page	Complex tag enabled when the consumer has submitted a payment or is redirected to an external platform	Complex root
payment-redirect-button	Html 'input' of type submit that allows the consumer to be redirected	Simple payment-status-page
payment-status-error	Describe the error that occured during the processing of the payment	Simple payment-status-page
payment-status-text	Description of the current action to the consumer	Simple payment-status-page
payment-status-title	Title of the current action (eg: redirection, status ...)	Simple payment-status-page

Validate form

Our solution and the default payment page template support both client-side and server-side form validation by default. Therefore:

Client-side validation scripts are always injected into payment pages when a form is present.
Server-side validation cannot be disabled (to ensure security)

When client-side validation is applied to a field, CSS classes will be added to the html according to the result of the validation. If the field is valid, the following classes will be applied:

On the input: payment-input-valid
On the error span: payment-validation-valid

If the field is invalid, the following classes will be applied:

On the input: payment-input-error
On the error span: payment-validation-error

Template upload

To upload templates for Hosted Checkout Page / Hosted Tokenization Page, see our dedicated chapters in the respective guides:

You can use <payment-tp-resource-file name=""/> to reference uploaded resources from your template (i.e., such as images. For example: <img alt="Logo" class="banner-logo" src="payment-tp-resource-file" name="logo.png" />).

Template Builder