Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

1. Introduction

Our Hosted Tokenization Page solution offers you maximum security and flexibility at once. Boost your conversion rate with little effort by

  • Leaving the handling of sensitive card data to us!
  • Customising your webshop's look and feel at will!
  • Optimising the payment experience by limiting the fields to fill in on your payment page and taking benefits from dynamic brand detection.
  • Saving your customers' data for their future purchases and recurring payments

HTP-short.png

The above graphic provides a broad overview of the parties involved and their responsibilities in the payment process.

Before you process live transactions, use our test environment. Get to know our solution without costs or any commitments involved! Once you want to go live, check out here how to get a production account or contact us!

To use this integration mode, make sure that the option "Alias Manager (RECX)" is active in your account in Configuration > Account > Your options.

Target most up-to-date API base URL

We encourage you to always target the most up-to-date API base URL when sending requests to our platform. Have a look at our dedicated guides for a full overview:

To allow you a smooth transition, previous API base URLs remain available until further notice.

2. Get started

To process transactions on our platform with this solution, make sure that

Are you all set? Then learn how to use our Hosted Tokenization Page in the next chapter!

    3. Integrate with Hosted Tokenization Page

    Your customers have to provide their credit card number at one point during their journey in your webshop. As a merchant, the greatest challenge is to link all steps during this journey into one seamless experience. At the same time, you need to ensure the safe transfer of your customers' data to the financial institutions handling the data.

    Therefore, you can either

    • Outsource the necessary security precautions completely (by using our Hosted Checkout solution). However, this method has limits: Your customers will notice a redirection to an external URL - a noticeable break in the payment flow
    • Collect the sensitive data on your own (by using our Server-to-server solution). But this requires you to fulfil the highest PCI requirements - which involves a lot of effort

    Our Hosted Tokenization Page solves this dilemma for you by combining the best of both worlds: 

    • Let us handle the credit card data without your customers noticing. Just add an iframe to your webshop containing the payment form. As we are the host, the sensitive data come and stay at our end! We encrypt the data as a PCI-uncritical token to be used for the actual payment
    • At the same time, merge it seamlessly into your webshop's look and feel. Adapt the payment form completely at will!

    Target endpoint URLs in test / live

    Our platform allows you to send requests either to our Test environment or Live environment:

    • Endpoint URL TEST: https://payment.preprod.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedtokenizations
    • Endpoint URL LIVE: https://payment.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedtokenizations

    For transactions with no financial impact, use the TEST-URL. The transactions will be sent to our test environment thereby to your test account.

    For transactions with a financial impact, use the LIVE-URL. The transactions will be sent to our live environment thereby to your live account.

    Build checkout page

    Our Hosted Tokenization Page solution requires you to add the following HTML/JavaScript elements on 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
    <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

    Learn in the following chapter how to implement these elements into the payment flow.

    Set up Content Security Policy

    If you have set up a Content Security Policy for your website, you need to whitelist our domains. This will allow loading the tokenizer file and let us capture its logs.

    To do so, add the domain https://payment.preprod.direct.worldline-solutions.com/ to the script-src, connect-src and frame-src directives of your Content Security Policy definition

    Understand payment flow

    Our Server SDKs come with a Hosted Tokenization Page API. It includes all the methods you need to perform all the steps of a typical payment flow:

    hostedTokenisationPage-longFlowV2.pngThe graphic above explains all the steps of a typical Hosted Tokenization Page transaction

    1. Your customers go to your check-out page featuring these HTML/JavaScript elements and finalise the purchase

    2. You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL

    Use the following code sample for the request:

    // Create a URI for our TEST/LIVE environment
    Uri apiEndpoint = new Uri("https://payment.preprod.direct.worldline-solutions.com/");
    
    // Initialise the client with the apikey, apisecret and URI
    IClient client = Factory.CreateClient("MERCHANT_KEY", "MERCHANT_SECRET", apiEndpoint, "YourCompanyName");
    
    // Instantiate the request
    var createHostedTokenizationRequest = new CreateHostedTokenizationRequest
    {
    	Variant = "YourTemplate.html"
    };
    
    // Send out the request
    var createHostedTokenizationResponse = await client
    	.WithNewMerchant("MERCHANT_ID")
    	.HostedTokenization
    	.CreateHostedTokenization(createHostedTokenizationRequest);
    
    // Fetch the complete url for the Tokenizer javascript component
    var hostedTokenizationUrl = createHostedTokenizationResponse.hostedTokenizationUrl;
    

    The only elements you need to adapt in the code are:

    A successful response looks like this:

    
    Status: 200 OK 
    {
    	"hostedTokenizationId": "2f4d08d6ddfc411e944e81c54d824a99", 
    	"invalidTokens": [ "" ], 
    	"hostedTokenizationUrl": "https://payment.preprod.direct.worldline-solutions.com/hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99",
    	"partialRedirectUrl": "preprod.direct.worldline-solutions.com/hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99" 
    }
    
    We recommend using the hostedTokenizationUrl in your code, as we have deprecated property partialRedirectUrl

    3. You invoke the initialize() function from the 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

    • Make sure to load the HTML form containing your checkout page and the HTML/JavaScript elements from a local server (i.e. NodeJS http-server). Due to iframe security restrictions, the tokenizer does not work with file-based browser content (i.e. file:///C:/yourfile.html)
    • The constructor of the Tokenizer takes three arguments:
      hostedTokenizationUrl: Tokenization URL obtained from the Server API
      div-hosted-tokenization: id of the element on your check-out page where you place the form.
      {}: Array of various parameters. Make sure to include at least the mandatory parameter hideCardholderName. Check out our dedicated chapter Use advanced customisation tools to learn what else is possible to adapt the payment flow to your needs
    • The method submitTokenization() accepts two optional arguments:
      cardholderName: If you choose to provide the card holder name on your own, make sure to include it here as a string
      storePermanently: If you choose (not) to keep the token for upcoming recurring payments, store or delete a token by sending true or false

        4. Your customers enters their credit card data in the <iframe>. Our platform detects the card scheme automatically once your customers start typing in the number. This also works for co-badged cards (where applicable) 

        If your customers enter a number from any card scheme that is not available in your account, the payment mask will display "Card number incorrect or incompatible". Therefore, we strongly advise you to inform your customers in your webshop environment about all available card payment methods before opening the tokenization form

        4'(optional). Use our validation function to check whether the cardholder has filled in the form correctly

        5. Your customers submit the card data to our platform via the <button> element. This button invokes the submitTokenization() function from the JavaScript code snippet

        6. Our platform tokenizes the card data. A successful response looks like this:

        TokenizationResult
        {
          success: boolean;
          hostedTokenizationId: string;
          error: Error;
        }
         
        Error {
          message: string;
        }   
        


        The hostedTokenizationId points to the tokenised card data on our platform. Use it in the next step to create the actual payment

        7. You send a CreatePayment request to our platform using our Server-to-server integration mode, including the mandatory 3-D Secure v2 parameters. Replace sensitive card data in the card property with the hostedTokenizationId.
        Use the following code sample for the request: 

        CreatePaymentRequest paymentrequest = new CreatePaymentRequest
        {
        	CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
        	{
        		HostedTokenizationId = "YourHostedTokenizationID",
        		PaymentProductId = 1,
               		SkipAuthentication = false,
                	ThreeDSecure = new ThreeDSecure
                	{
        	      		RedirectionData = new RedirectionData
        	      		{
        	           		ReturnUrl = "https://yourRedirectionUrl.com"
        	      		}
                	}
            	},
            	Order = new Order
            	{
                		AmountOfMoney = new AmountOfMoney
                		{
                    		Amount = 100,
                    		CurrencyCode = "EUR"
                		},
        
                		Customer = new Customer
                		{
                			Device = new CustomerDevice
             			{
        				AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
                        			Locale = "en_EN",
                        			TimezoneOffsetUtcMinutes = "-180",
                        			UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
                        			BrowserData = new BrowserData
                        			{
                            			ColorDepth = 24,
                            			JavaScriptEnabled = false,
                            			ScreenHeight = "1080",
                            			ScreenWidth = "1920"
                        			}
        			}
        		}
        	}
        }; 
        
        var response = await Client
        	.WithNewMerchant("YourAccount")
            .Payments
            .CreatePayment(paymentrequest);
        The only elements you need to adapt in the code are:
        • "YourAccount": the name of your account on our platform
        • "YourHostedTokenizationID": The sessionID you received from our server in the previous step

        Our platform returns a tokenID and paymentProductId for this call. This allows you to process future payments or recurring payments. Read the dedicated chapter to learn how it works

        7'(optional). We perform a Fraud check

        8. Our platform sends a response containing a MerchantAction object.
        It instructs you how to proceed with the payment. Based on the response, these scenarios are possible:

        a) 3-D Secure frictionless flow authentication (MerchantAction.ActionType=null): Your customer uses a 3-D Secure enrolled card. The 3-D Secure v2 parameters in your CreatePayment request prove to be sufficient for the authentication step. We submit the transaction to the acquirer and provide the result in property statusOutput.statusCode. The flow continues at step 14

        b) 3-D Secure challenge flow authentication (MerchantAction.ActionType=REDIRECT): Your customer uses a 3-D Secure enrolled card. S/he needs to identify her/himself as the rightful card owner. The flow continues at step 9

        c) No 3-D Secure authentication (MerchantAction.ActionType=null): Your customer uses a non-3-D Secure enrolled card. We submit the transaction to the acquirer and provide the result in property  StatusOutput.StatusCode. The flow continues at step 14

        9. You redirect the customer to her/his issuing bank to the MerchantAction.RedirectData.RedirectURL

        10. Your customers perform the 3-D Secure check. Our system receives the result from the issuer. Based on the result, two scenarios are possible: 

        a) If the identification was unsuccessful, we redirect your customer to your ReturnUrl, ending the flow. You can request the transaction result as described in step 13

        b) If the identification was successful, the flow continues at step 11

        11. We submit the actual financial transaction to the acquirer to process it. We receive the transaction result

        12. We redirect your customer to your returnUrl

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

        14. If the transaction was successful, you can deliver the goods / services

        14'(optional). Delete the token if you do not plan it to use it for recurring payments or if your customers did not agree to store the credentials To do so, use our DeleteToken API

        You can also instruct our platform to delete a newly created token right after the payment. Add the following line to your request when submitting the card data to our platform:

        tokenizer.submitTokenization({ storePermanently:false })

        4. Use advanced customisation tools

        We have designed our Hosted Tokenization Page in a way to allow you to customise it as freely as possible. Take a look at these features: 

        Create iframe template

        The centrepiece of this solution is an iframe containing the payment form. We have designed it in a way that allows you to

        • Adapt its various HTML elements at your liking.
        • Use your own .css /image files to further modify the payment form.
          • Feel free to use this template and .CSS file to adapt the payment form to the look and feel of your webshop.
          • It is the ideal solution to let your customers choose between local or global brands (i.e. Visa, MasterCard) if they are using a co-badged credit card 

        Once you have created a template that matches your webshop's look and feel, upload it and all .css / image files on our platform. To do so, follow these steps: 

        1. Log in to the Back Office
        2. Go to Configuration > Template > File Manager > Upload Template Files. Click on "File..." and select the .html (and if applicable, additional .css / image files)
        3. After a couple of minutes, our system will have validated the files (In “Uploaded Files”, they appear as “Validated” in column “Status”). They will then be ready to be used on the Hosted Tokenization Page

          Our platform allows you to upload multiple template files. Use the one of your choice by populating property variant with the file name in the Create hosted tokenization session API call.

          On top of creating .html / .css files to adapt the payment form, we offer some additional tools. They will further empower you to get the exact result you need!

          Change language on form

          When requesting the tokenization URL, add variable Locale to translate the field labels in a language of your choice. The allowed range of the variable value is defined by ISO 639-1 (for language value) and ISO 3166-1 (for country value):

          
          var createHostedTokenizationRequest = new CreateHostedTokenizationRequest
          {
          	Locale = "fr_FR",
          	Variant = "YourTemplate.html"
          };    
          

          Adapt visual style

          Apply CSS style to the iframe dimensions to merge it even more seamlessly into your webshop. Add this bit to your .css file accordingly:

          iframe[name=htpIframe0] {
              border: none;
              width: 800px;
          }

          Manage cardholder name

          Our API allows to either show or hide the cardholder name field in the iframe.
          Pass the boolean hideCardholderName: true or the boolean hideCardholderName: false accordingly in the Tokenizer constructor:

          var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { hideCardholderName: false });

          • If not specified, our platform sets hideCardholderName: true by default
          • The cardholder name is mandatory. If you choose to get the name in your webshop environment, make sure to submit it in the form:
            tokenizer.useCardholderName("Wile E. Coyote") 
            tokenizer.submitTokenization().then((result) => { ... })

          Send additional tokenizer arguments

          The tokenizer call as described in step 3 takes additional arguments on top of hideCardholderName. Add any of them in your request to adapt the payment flow to your needs: 

          Argument Description
          hideCardholderName See dedicated chapter
          hideTokenFields

          Boolean

          Set to true if you want to pre-populate the iframe fields (card number, card holder name and expiry date) with the data stored in a token for a recurring payment

          validationCallback

          See dedicated chapter

          paymentProductUpdatedCallback

          Callback function

          Detect the brand of the card used as it is entered in the payment form: 

          var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', 
          { paymentProductUpdatedCallback: mypaymentProductUpdatedCallback });
          function mypaymentProductUpdatedCallback(result) { /* Display/remove the detected card brand from your checkout page */ }

          5. Use additional possibilities

          Our Hosted Tokenization Page solution offers many more possibilities. Learn here all about its available features.

          Use existing token

          Our platform allows you to store your customers' credit card data permanently for recurring payments or for a Use token for 1-Click-Payments, pre-filling in the payment form. It will make your customers’ payment experience even smoother and improve your conversion rate!

          • Using an existing token for a Use token for 1-Click-Payments conveniently pre-fills your customers' credit card number and expiry date.
          • Due to SCA, your customers might still have to enter their CVC and/or pass a 3-D Secure authentication check. Our payment form displays the mandatory fields to be filled in automatically.

          As the token is already existing at the time of the transaction request, the payment flow is different: 

          • Step 1: Instruct our platform you want to use an existing token. To do so, modify the request createHostedTokenizationRequest by adding the property tokens:
            var createHostedTokenizationRequest = new CreateHostedTokenizationRequest
            {
            	Tokens = "86a44668-5d0f-4e3f-a597-2aa0a4d03fe5,86a44668-5d0f-4e3f-a597-2aa0a4d03fe5", // value is the name of the token on our platform
            	Variant = "YourTemplate.html"
            };
            


            A successful response looks like this:

            
            Status: 200 OK
            {
                "hostedTokenizationId": "2f4d08d6ddfc411e944e81c54d824a99",
                "invalidTokens": [ "86a44668-5d0f-4e3f-a597-2aa0a4d03fe5" ],
                "hostedTokenizationUrl": "https://payment.preprod.direct.worldline-solutions.com/hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99",
            "partialRedirectUrl": "preprod.direct.worldline-solutions.com/hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99" }

            If our response contains a value for property invalidTokens, the token sent in your request invalid. Do not use it in the subsequent payment.
          • Step 2: Pre-fill the displayed form with the stored credit card data. Our platform offers you two ways for this: 
            1. Pre-fill the form right away as you display it. Achieve this by adding the token as the fourth argument to the tokenizer constructor: 

            var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { }, '00164fec-32b2-462e-b48b-84a27930b10c');
            2. Leave the form empty at first as you display it. Let your customers choose in your webshop environment to pay with their stored card. If they choose to, use the following function to populate the form:

            var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { });
            ...
            // Later, for instance when a user input triggers a token change
            function tokenChanged () {
            tokenizer.useToken('00164fec-32b2-462e-b48b-84a27930b10c'); //Changes the form to update the selected token, showing only the CVC field if required
            // or
            tokenizer.useToken(); // Resets the form to create a new token
            }

            You can also allow your customers to update the token in the payment form. By initialising the boolean hideTokenFields as follows, your customers can do either

            a) {hideTokenFields:true}: Hide known fields (card number/expiry date)
            b) {hideTokenFields:false}: Mandatory fields are visible to be filled in / known fields can be changed (only cardholder name/expiry date)

            The request looks like this:
            var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', {hideTokenFields:true});

          Get validation status

          Your parent page can get the validation status of the payment form anytime. Pass a validation callback function that is called whenever the validity status of the payment form changes. Make sure this function contains a parameter that receives an object with the boolean property valid. This boolean indicates if the form is correctly filled in.

          Use this information to enable/disable the submit button on the parent page if the payment form is correctly/incorrectly filled in. Add this function to your script in step 3:

          var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { validationCallback: myValidationCallback });
          function myValidationCallback(result) { document.getElementById('btn-submit').disabled = !result.valid }
          

          Remove form

          You can remove the payment form from the parent page. Calling this function removes the iframe and its event listeners:

          tokenizer.destroy();

          Use tokenId instead of hostedTokenizationId

          Our platform allows you to process transactions with both the hostedTokenizationId and the tokenId. The flow for the former is described in this chapter. Using TokenIDs requires you to modify the flow as follows:

          As steps 1. – 4. and 7. – 12. are identical to the flow using the hostedTokenizationId, we have only added them as stubs here. Check the dedicated chapter for details.
          1. A payment request is initiated
          2. Get a valid tokenization URL by a  Create Hosted Tokenization call
          3. Add a code snippet to your checkout page, allowing you to display the tokenization form with the valid tokenization URL as an iframe on your check-out page
          4. Your customer enters her/his credit card data on in the iframe
          5. Get the token for the actual payment
            Recover the result of the tokenization by performing a GetHostedTokenization call from your backend

            For requests to our TEST environment: https://payment.preprod.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedtokenizations/hostedTokenizationId
            For requests to our LIVE environment: https://payment.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedtokenizations/hostedTokenizationId 
            Use the following code sample for the request:
            
            // Get the result of the tokenization session
            var getHostedTokenizationResponse = await client
            	.WithNewMerchant("YourPSPID")
            	.HostedTokenization
            	.GetHostedTokenization(createHostedTokenizationResponse.HostedTokenizationId);
            
            // Get the tokenId to be used for payment creation
            var tokenId = getHostedTokenizationResponse.Token.Id;
            

          6. Create the actual payment with the token. Send a CreatePayment request to our server. Use the following code sample for the request:
            
            CreatePaymentRequest requestBody = new CreatePaymentRequest
            {
            	CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
            	{
            		Token = tokenId // Token received by calling GetHostedTokenization()
            	},
            	Order = new Order
            	{
            		AmountOfMoney = new AmountOfMoney
            		{
            			Amount = 100, // The amount you want to charge your customer multiplied by 100 (1.00 EUR)
            			CurrencyCode = "EUR"
            		}
            	}
            };
            
            var response = await client
            	.WithNewMerchant("YourPSPID")
            	.Payments
            	.CreatePayment(requestBody);
            

          7. You redirect your customers to their issuing bank for a 3-D Secure check. The customers identifies themselves
          8. Our system receives the result from the issuer
          9. We submit the actual financial transaction to the acquirer to process it
          10. We redirect your customer to your ReturnUrl
          11. You request the transaction result from our platform via GetPayment or receive the result via webhooks
          12. If the transaction was successful, you can deliver the goods / services
            12' (optional): Delete the token

          Get privacy policy 

          You can use GetPrivacyPolicy to get the legal framework for any payment method you offer, relieving you from the effort of providing and maintaining your own privacy policy.