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 HostedCheckout 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) don't 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-list |
| 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-list |
| 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 Back Office
To use the template on your payment pages, save it as ".htm" on your computer. Login into the Ingenico back-office and upload it by going to Configuration > Template > File Manager along with your .css files and images.