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
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:
- Your customers finalise an order in your shop and select cards to make the payment
- You redirect your customers to your checkout page featuring these HTML/JavaScript elements
- You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL
- 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 - Your customers enter their credit card data in the <iframe>
- Your customers submit the card data to our platform via the <button>. This button invokes the submitTokenization() function from the JavaScript code snippet
- Our platform tokenizes the card data. We return a hostedTokenizationId pointing to the card data stored on our platform
- 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] }
- Our platform returns a MerchantAction object instructing you to redirect your customer for 3-D Secure authentication
- You redirect the customers to their issuing bank via the merchantAction.redirectData.redirectURL. The customers identify themselves as the rightful card owners
- 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 - 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
Before you start the migration, make yourself familiar with the
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:
Element | Description |
---|---|
|
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 |
|
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 |
|
The instance of the Tokenizer class providing all functionalities you need for the payment process, i.e.
|
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:
Action | Direct endpoint | Classic endpoint |
---|---|---|
Tokenise card data | https://payment.preprod.direct.worldline-solutions.com/v2/{yourPSPID}/hostedtokenizations | https://ogone.test.v-psp.com/Tokenization/HostedPage |
Send payment request with tokenised card data | https://payment.preprod.direct.worldline-solutions.com/v2/{yourPSPID}/payments | https://ogone.test.v-psp.com/ncol/test/orderdirect.asp |