Template Builder
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 live 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 />
or
<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
Upload template to account
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" />).