marcopolo Online payment
Sign up

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

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

    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" />).

    Was this page helpful?

    Do you have any comments?

    Thank you for your response.