Template Builder
You can chose to customize your payment pages when using our HostedCheckout solution by using your own template. That means you can freely adapt the look and feel of our secure payment pages.
Along with this solution comes our template builder, a tool you can use to test and implement the best customer experience possible during each step of the checkout process.
More information can be found in our Hosted Checkout Page documentation.
1. Template live preview / editor
Our template builder consists of two sections: the live preview and the editor. The live preview will show you how the template defined in the HTML editor will be displayed.
1.1 Live preview
The live preview provides the rendering of the various payment pages defined by the customizable HTML code in the editor. The various drop-down menus below the preview allow you 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 / BCMC) 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
- Amount: changes the amount of the payment pages
- Language: changes the language used in the payment pages
One single template can contain the different pages by using these tags:
<payment-paymentmethod-selection>
List of payment methods
</payment-paymentmethod-selection>Our system will automatically take the respective tags into account for the current step in the transaction flow.
Click on the REFRESH button to adapt the preview according to your drop-down selections and/or changes in the editor.
1.2 Editor
The right part of the editor displays the source code of the current template visible in the live preview. A default template is provided as an example that you can freely edit or replace, depending of your needs.
The left part is a list of available tags that helps you customize the template. Double-clicking on the tags will add them automatically to the source code at the current cursor’s position.
WARNING: The editor doesn't save your work automatically. Use the COPY TO CLIPBOARD button to save your template before closing your browser!
2. Template format
The templates are HTML documents with special entities for dynamic parameters. These special entities are referred to as "tags".
2.1 Simple and complex tags
Simple tags don't have content. They are useful to insert dynamic values like the reference of the payment or the title of the page.
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 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>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 the request, payment-lineitems won't render anything.
Some complex tags like payment-lineitems-list render multiple times: for each line item sent in the request.
2.2 Payment Pages
To test your template in those different scenario, the "Payment page" option in the template builder contains 3 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.
A single template can contains the different pages by using the tags payment-paymentmethod-selection, payment-paymentmethod-form and payment-status-page.
Those tags are rendered dependening 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>2.3 List of available tags
The following list provides an overview of all available tags. When using tags, their usage hierarchy must be taken into account:
- global: tag can be used everywhere
- root: tag can be used outside of any tag
- other tags are only available under specific tags which is specified in the list
| Name | Description | Type / Available under |
|---|---|---|
| payment-about-link | An about link to inform consumers about us |
Simple global |
| payment-beneficiary | The commercial name set on your merchant account |
Simple global |
| payment-beneficiary-text | The text 'Beneficiary' |
Simple global |
| payment-currency | Curreny 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 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 |
3. Validate form
- Client-side validation scripts will always be injected in the payment page (when it's a form).
- Server-side validation will never be disabled, there is no way someone can bypass it.
4. Upload template to account
To use the template on your payment pages, save it as ".htm" on your computer. Login into the Back Office and upload it by going to Configuration > Template > File Manager along with your .css files and images.