worldline Direct
Sign up

Migrate to Hosted Tokenization Page

FlexCheckout is one of our most popular products for good reason: It combines low PCI requirements and a high level of design control.

As we at Worldline yearn to offer you the best online payments technology, we have developed the new Direct integration layer featuring a FlexCheckout counterpart: The Hosted Tokenization Page!

With Direct being the future of online payments, we would like to invite you to switch from FlexCheckout to Hosted Tokenization Page.

To get started, have a look at the:

Are you already using Direct? Go straight to our dedicated Hosted Tokenization Page guide! 

Understand Hosted Tokenization Page advantages

The Hosted Tokenization Page is part of our powerful REST-API Direct integration layer. It offers you some unique advantages over FlexCheckout.

  • A higher level of customisation: Our Hosted Tokenization Page allows you to merge the iframe-based payment mask with your checkout page with even more ease and elegance.
  • A developer-friendly approach: Use the Server/mobile SDK of your preferred programming language to access all functionalities of our RESTful API.
  • Fulfilling legal obligations: Be compliant with EU-regulations regarding the choice of brand in co-badging.

To help you prepare the switch, let us discuss the similarities and differences between Hosted Tokenization Page and FlexCheckout.

Understand similarities and differences Hosted Tokenization Page - FlexCheckout

We have designed both the Hosted Tokenization Page and FlexCheckout to empower you to customise your customers’ payment experience at will, while fulfilling only minimal PCI-DSS requirements. This will not change when using our Hosted Tokenization Page, as it has the same features as FlexCheckout:

  • Your customers stay on your checkout page during the payment process. They enter their PCI-DSS-relevant card data in an <iframe>-embedded form hosted at our safe environment.
  • Our platform tokenizes the submitted card for a one-time or recurring use. We return a (temporary) token you can use for initialising the actual payment.
  • You request the actual payment via a second dedicated integration mode. Server-to-server replaces DirectLink for this step.

Hence, your PCI-DSS level (SAQ A) and the basic technical principle remain the same. However, there are important differences to consider:

Item Hosted Tokenization Page FlexCheckout
<iframe> initialisation

When invoking a specific JavaScript code snippet, the <iframe> is added to your checkout page.

This specific JavaScript code snippet opens the target URL automatically when it adds the <iframe>.

You add an <iframe> to your checkout page using your own code.

You open the target URL on our platform when adding the <iframe> element on your checkout page.

Card submission via <iframe>

The button to submit the card data to our platform is located on your checkout page.

The button to submit the card data to our platform is in the <iframe> itself.

Getting the tokenised card

We provide the token upon invoking a specific JavaScript code snippet as a return value.

We return the token as a GET parameter to a URL you have defined when initiating the <iframe>.

Redirection to your webshop after payment

You request the transaction result from our platform via GetPayment or receive the result via webhooks.

You request the transaction result from our platform via DirectQuery or receive the result via Hosted Payment Page feedback channels.

Once you have acknowledged the differences and similarities, look at the high-level flow of a typical Hosted Tokenization Page transaction.

Understand Hosted Tokenization Page flow

As the basic technical principle implements only minor changes, the payment flow remains the same. Nevertheless, make sure to understand all steps of a typical flow:

This is a high-level payment flow covering only the mandatory steps. Read our dedicated chapter in our Hosted Tokenization Page guide for detailed information, code samples and optional steps in the flow.

  1. Your customers finalise an order in your shop and select cards to make the payment.
  2. You redirect your customers to your checkout page featuring these HTML/JavaScript elements.
  3. You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL.
  4. You invoke the initialize() function from JavaScript code snippet. By doing so, an <iframe> is automatically added to the HTML element
    <div id="div-hosted-tokenization"></div> . The <iframe> opens the hostedTokenizationURL automatically.
  5. Your customers enter their credit card data in the <iframe>.
  6. Your customers submit the card data to our platform via the <button>. This button invokes the submitTokenization() function from the JavaScript code snippet.
  7. Our platform tokenizes the card data. We return a hostedTokenizationId pointing to the card data stored on our platform.
  8. You send a CreatePayment request to our platform using our Server-to-server integration mode. Replace sensitive card data in the card property with the hostedTokenizationId:

       [Any other properties i.e. for 3-D Secure omitted]
  9. Our platform returns a MerchantAction object instructing you to redirect your customer for 3-D Secure authentication.
  10. You redirect the customers to their issuing bank via the merchantAction.redirectData.redirectURL. The customers identify themselves as the rightful card owners.
  11. Our system receives the result from the issuer and submits the actual financial transaction to the acquirer to process it
    We receive the transaction result and redirect your customers to your returnUrl.
  12. You request the transaction result from our platform via GetPayment or receive the result via webhooks.

As soon as you are aware of the flow, make sure to meet the requirements for this solution.

Meet requirements for Hosted Tokenization Page

To process transactions on our platform with this solution, make sure that you meet these requirements:

Are you all set? Then you can start migrating!

Migrate to Hosted Tokenization Page

To migrate from FlexCheckout/DirectLink to Hosted Tokenization Page/Server-to-server, you need to:

A) Configure API key/secret in PSPID

To start working with this solution and our Direct API in general, you need to configure an API Key/API Secret pair. They act as the Direct-specific authentication mechanism and work independently from the API user/password you use for FlexCheckout.

Read our dedicated guide with detailed instructions to set up an API Key/API Secret.

B) Modify your checkout page

To allow our API to add the <iframe> during the payment process, you need to remove the FlexCheckout <iframe> and your code maintaining it. Instead, add the following HTML/JavaScript elements to your checkout page:

<div id="div-hosted-tokenization"></div>
<button onclick="submitForm()">submit</button>
<script src=""/> <!-- contains the methods needed for tokenization -->
    // to tokenise credit card data. Load it to the form into an existing DOM element on your check-out page
    var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', {hideCardholderName: false });

    tokenizer.initialize().then(() => {
        // Do work after initialization, if any
    .catch(reason => {
        // Handle iFrame load error
    function submitForm(){ // 
        tokenizer.submitTokenization().then((result) => {
            if (result.success) {
                // Proceed
            } else {
                // displayErrorMessage(result.error.message);

The individual elements fulfil a specific role during the payment flow:

Element Description
<div id="div-hosted-tokenization"></div>

When invoking the initialize() function, an <iframe> is automatically added to this element. At the same time, the <iframe> opens the hostedTokenizationUrl you have previously requested via CreateHostedTokenization.

The <iframe> loads a page hosting the payment mask on our side your customers use to enter their PCI-DSS-sensitive data. You can customise the elements of this <iframe> freely. Follow the instructions in this dedicated chapter to learn how to create and upload the template.

<button onclick="submitForm()">submit</button>
function submitForm()

Invokes the function to submit the card data from the <iframe> and receiving the token (the unique hostedTokenizationId you create for each session).

Use this hostedTokenizationId to create the actual payment in a subsequent CreatePayment request.

var tokenizer
The instance of the Tokenizer class providing all functionalities you need for the payment process, i.e.
  • Customising your requests using additional arguments.
  • Adding the <iframe> hosting the payment mask.
  • Submitting the card data and receiving the token for the actual payment.

All elements on your checkout page that are inherently part of your webshop infrastructure can remain as-is.

C) Create and upload template

Our Hosted Tokenization Page allows you to customise the elements in the <iframe> freely. Follow the instructions in this dedicated chapter to learn how to create and upload the template. You can leave existing FlexCheckout templates as-is, as your new template will not interfere with them.

D) Apply parameter mapping

Each API request you send to our platform requires you to send along a set of properties. Our exhaustive description of the payment flow in the dedicated chapter in our Hosted Tokenization Page guide provides you with detailed information. However, as you are migrating from our legacy platform to Direct, the following resources can provide further help:

E) Adapt endpoint for sending requests

Make sure to change the endpoint URLs when sending requests to our REST API:

The table below features only the TEST endpoints. Refer to our dedicated Environments guide for the live endpoints.

Action Direct endpoint Classic endpoint
Tokenise card data{yourPSPID}/hostedtokenizations
Send payment request with tokenised card data{yourPSPID}/payments

Was this page helpful?

Do you have any comments?

Thank you for your response.