Migrate to Hosted Tokenization Page

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:

• Hosted Tokenization Page advantages over FlexCheckout.
• Differences and similarities between Hosted Tokenization Page and FlexCheckout.
• The Hosted Tokenization Page flow.
• Technical requirements you need to fulfil.
• Integration of the Hosted Tokenization Page into your webshop.

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:

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:

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:
   
   

   {
      "order":{
         "amountOfMoney":{
            "currencyCode":"EUR",
            "amount":1000
         }
      },
      "cardPaymentMethodSpecificInput":{
         "hostedTokenizationId":"YourHostedTokenizationId"
      }
      
      [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:

• Option "Alias Manager (RECX)" is active in your account (Check in the Back Office via Configuration > Account > Your options).
• At least one of these card payment methods are active in your account (Check in the Back Office via Configuration > Payment methods).
• You PCI DSS compliance level is SAQ A.
• You have configured your API Key and API Secret in your account.
• Your checkout page implements these HTML/Javascript elements.
• Not mandatory, but highly recommended: You have created and uploaded a template as described here.

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 an API key/secret in your PSPID.
• B) Modify your checkout page.
• C) Create and upload template.
• D) Map the FlexCheckout parameters to Hosted Tokenization Page properties.
• E) Adapt your endpoint for sending requests.

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="https://payment.preprod.direct.worldline-solutions.com/hostedtokenization/js/client/tokenizer.min.js"/> <!-- contains the methods needed for tokenization -->
<script> 
    // 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);
            }
        });
    }
</script>

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

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

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

var tokenizer

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:

• The parameter mapping for classic parameters - Direct properties helps you rebuild the solution using our Direct API.
• The API reference containing all (mandatory) properties and their data types/range of values.

E) Adapt endpoint for sending requests

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