Ingenico 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

hostedTokenizationPage-shortFlow.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.

2. Get started

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

  • You have an account on our platform
  • At least one of our available card-based payment methods is activated in your account (Check in the Back Office via Configuration > Payment methods)
  • You have configured your API Key and API Secret in your account (Check in the Back Office via Configuration > Technical Information > Ingenico Direct Settings Direct API Key). Learn more in our authentication chapter
  • Your server can process server-to-server request via our RESTful API. Using one of our Server SDKs will greatly ease this task
To configure your API Key and API Secret, make sure that option "DIR (Merchant using Ingenico Direct integration)" is active in your Back Office (Configuration > Account > Your options > Available options).
Contact us if this not the case.

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

  • 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 - which you cannot completely customise.
  • Collect the sensitive data on your own in your webshop (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!

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 file and images to further modify the payment form.

Use our template builder and its documentation to learn the basic structure of a template and what is possible.

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,

  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 / images files)
  3. After a couple of minutes, our system has validated the files (In “Uploaded Files”, they appear as “Validated” in column “Status”). They are now 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.

Target endpoint URLs in test / live

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

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.

Understand payment flow

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

hostedTokenisationPage-longFlow.png

The graphic above explains all the steps of a typical Hosted Tokenisation Page transaction

    1. A payment request is initiated
    2. Get a valid tokenization URL by a  Create Hosted Tokenization call.

      Use the following code sample for the request:

      
      using Ingenico.Direct.Sdk;
      using Ingenico.Direct.Sdk.Domain;
      
      ...
      
      // Create a URI for our TEST/LIVE environment
      Uri apiEndpoint = new Uri("https://payment.preprod.direct.ingenico.com");
      
      // Initialise the client with the apikey, apisecret and URI
      IClient client = Factory.CreateClient("yourAPIkey", "yourAPIsecret", apiEndpoint, "YourCompanyName");
      
      // Instantiate the request
      var createHostedTokenizationRequest = new CreateHostedTokenizationRequest
      {
      	Variant = "YourTemplate.html"
      };
      
      // Send out the request
      var createHostedTokenizationResponse = await client
      	.WithNewMerchant("YourPSPID")
      	.HostedTokenization
      	.CreateHostedTokenization(createHostedTokenizationRequest);
      
      // Build the complete url for the Tokenizer javascript component
      var hostedTokenizationPageUrl = $"https://payment.{createHostedTokenizationResponse.PartialRedirectUrl}";  
      

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

      A successful response looks like this:

      Status: 200 OK
      {
          "hostedTokenizationId": "2f4d08d6ddfc411e944e81c54d824a99",
          "invalidTokens": [ "" ],
          "partialRedirectUrl": "preprod.direct.ingenico.com/hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99"
      }

      The variable partialRedirectUrl contains the partial URL path you need to assign to the iframe's scr  attribute. Construct the full path using this formula:

      https://payment. + partialRedirectUrl


    3. Display the tokenization form with the valid tokenization URL as an iframe on your check-out page. Add the following code snippets to your check-out page:

      a. JavaScript library: contains the methods needed for tokenization

      <!DOCTYPE html>
      <html>
      <head>
          <script src="https://payment.preprod.direct.ingenico.com/hostedtokenization/js/client/tokenizer.min.js"></script>
      </head>
      </html>
      

      b. JavaScript code block: use it to tokenise credit card data. Load it to the form into an existing DOM element on your check-out page

      var tokenizer = new Tokenizer(hostedTokenizationPageUrl, 'div-hosted-tokenization', {hideCardholderName: false});
       
      tokenizer.initialize()
         .then(() => {
           // Do work after initialization, if any
          })
          .catch(reason => {
           // Handle iFrame load error
           })
      

      Make sure to load the HTML form from a local server (i.e. NodeJS http-server).
      Due to iframe security restrictions, the tokeniser does not work with file-base browser content (i.e. file:///C:/yourfile.html)

      The variable tokenizer contains two arguments and a method call:
    4. Your customer enters her/his credit card data on in the iframe and submits the form using the submit button on your page.
      4'. (optional): Use our validation function to check whether the cardholder has filled in the form correctly


    5. You submit the tokenisation form to our server using a javascript interface. Use the following code sample for the request:

      tokenizer.submitTokenization().then((result) => {
          if (result.success) {
              // Proceed
          } else {
              // displayErrorMessage(result.error.message);
          }
      });
      

      Method submitTokenization() accepts two optional arguments:




      A successful response returns the result in this format:

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

      The hostedTokenizationId represents the session used to store the credit card data safely at our end. Use it in step 6 to get the token for the actual payment.

      Make sure to submit the form only once. Sending it again will return an error. 
    6. Get the token for the actual payment.
      Recover the result of the tokenization by performing a GetHostedTokenization call from your backend.

      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;
      

      The only elements you need to adapt in the request are

      The variable id contains the credit card profile stored safely at our end. Use it in step 7 to submit the actual payment.

      All subsequent steps 7 through 12 follow the logic of the Server-to-server integration mode. Learn in our dedicated guide (starting from step 2) how it works  
    7. 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'. (Optional): We perform a Fraud check

    8. You redirect your customers to their issuing bank for a 3-D Secure check

    9. Your customers perform the 3-D Secure check. Our system receives the result from the issuer. Based on the result, two scenarios are possible:
      9.1.: If the identification was unsuccessful, we redirect the card holder to your returnUrl, ending the flow
      9.2.: If the identification was successful, the flow continues at step 10
      9.3.: If 3-D Secure was not rolled out at all, we submit the transaction to the acquirer and provide the result in property StatusOutput.StatusCode. The flow continues at step 12)

    10. We submit the actual financial transaction to the acquirer to process it.
    11. We return the payment result to you. and redirect your customers to your  returnUrl

    12. If the transaction was successful, you can deliver the goods / services redirect.
      12' (Optional): Delete the token. Due to GDPR, you need to get your customers' consent if you want to store their credit card data permanently for future purchases.
      If your customers do not allow you to store their data, you need to delete them from our platform after the payment. To do so, use our DeleteToken API. We also offer you the possibility to delete a newly created token right after the payment. Add the following line to your request when creating the token: 

      tokenizer.submitTokenization({ storePermanently:false })
      




4. Use advanced customisation tools

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 tokenisation 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(hostedTokenizationPageUrl, '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 tokeniser 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(hostedTokenizationPageUrl, 'div-hosted-tokenization', 
{ paymentProductUpdatedCallback: mypaymentProductUpdatedCallback });
function mypaymentProductUpdatedCallback(result) { /* Display/remove the detected card brand from your checkout page */ }



5. Use additional possibilities

Our Hosted Tokenisation Page 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 one-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 one-click payments conveniently pre-fills your customers' credit card number and expiry date.
  • Due to PSD2 regulations, 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" ],
        "partialRedirectUrl": "preprod.direct.ingenico.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-fil 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(hostedTokenizationPageUrl, '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(hostedTokenizationPageUrl, '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(hostedTokenizationPageUrl, '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(hostedTokenizationPageUrl, '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();