Sign up


Unsere Hosted Tokenization Page Lösung bietet Ihnen gleichzeitig maximale Sicherheit und Flexibilität. Steigern Sie Ihre Konversionsrate mit wenig Aufwand.

  • Delegate handling sensitive data to us for PCI compliancy
  • Flexible and easy visual adaptation & customisation
  • Ease future purchases and recurring payments for your customers!

Erste Schritte

Um Transaktionen auf unserer Plattform mit dieser Lösung zu verarbeiten, stellen Sie Folgendes sicher:

Sind Sie bereit? Dann erfahren Sie im nächsten Kapitel, wie Sie unsere Hosted Checkout Page-Lösung einsetzen können!

Erste Schritte

How it works

Bevor Sie Live-Transaktionen verarbeiten, sollten Sie unsere Testumgebung nutzen. Lernen Sie unsere Lösung ohne Kosten oder Verpflichtungen kennen! Wenn Sie Ihre Website freischalten wollen, sehen Sie hier, wie Sie ein Livekonto erhalten oder kontaktieren Sie uns!

Ways to integrate

1Use our SDKs

Use our Server SDKs to seamlessly connect your server environment to the Ingenico Direct platform's Server API. These SDKs simplify the API's functionality with easy-to-use platform-specific objects.

Ruby PHP Python 2 Node.js Java Python 3 .NET

2Use our plugins

Our Plugins provide a seamless link between your webshop and our platform. By effectively wrapping our RESTful API, these plugins save you time on writing code and make integration quick and easy.

Prestashop WooCommerce SAP Magento Shopify Salesforce Shopware Chargebee BigCommerce Aero Commerce OpenCart Proximis

Integration steps

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 Page 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 exchange the actual payment card number for a token which is not in scope for PCI.
  • At the same time, merge it seamlessly into your webshop's look and feel. Adapt the payment form completely at will!

Our Hosted Tokenization Page in combination with the Server-to-server integration method works with all card payment methods.

The following chapters cover a high-level overview of a typical flow. It describes all the steps you need to follow for processing Hosted Checkout Page transactions. Find a detailed overview including optional steps, 3-D Secure authentication etc. in the dedicated chapter

  1. Build checkout page & set up Content Security Policy
  2. Initialise Server SDK
  3. Create HostedTokenization session & add iframe to checkout page
  4. Submit & tokenise card details
  5. Send CreatePayment request
  6. Process platform response
  7. Get & show transaction result

Build checkout page & set up Content Security Policy

Our Hosted Tokenization Page solution requires your checkout page to implement

  • Specific HTML/JavaScript elements
  • Content Security Policy

HTML/JavaScript elements

Add the following HTML/JavaScript elements on your checkout page:

<div id="div-hosted-tokenization"></div>
<button onclick="submitForm()">submit</button>
<script src=""></script> <!-- 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:



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

Invoking the initialize() function adds an <iframe> to this <div> element. At the same time, the <iframe> opens the hostedTokenizationUrl you have previously requested via a CreateHostedTokenization request.

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()

Invoking submitForm() function submits the card data from the <iframe> to our platform for tokenisation. Our platform returns a unique hostedTokenizationId 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.

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 to the script-srcconnect-src and frame-src directives of your Content Security Policy definition.

Initialise Server SDK

Initiate the Server SDK by defining connection URLs, your PSPID on our platform and API Key/Secret. Read the documentation of your preferred SDK to learn more.

Endpoint Urls in test / live

  • Endpoint URL TEST:
  • Endpoint URL LIVE:

If you are using our Server SDKs, your application needs to target the respective environment / integration method URL via instances of CommunicatorConfiguration/ IClient/ CreateHostedTokenizationRequest. Detailed information about the how-to are available in the following chapters, including full code samples.

When processing online transactions, keeping track of your conversion rate is paramount. We are eager to help you with this via our transaction databases our customer support team is happy to share with you.
To ensure we can provide you with the most precise conversion rate data, we highly recommend the following best practices:

  • When submitting a transaction request to our platform, always send the customer email address order.customer.contactDetails.emailAddress.
  • When resubmitting a transaction request to our platform for a unique order (i.e. after having received a status.statusOutput=2 during the first try), always send the same order.references.merchantReference from your first try.

Create HostedTokenization session & add iframe to checkout page

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

Invoke the initialize() function from the Javascript code snippet. Make sure to pass the hostedTokenizationURL as the value for the Tokenizer instance's argument tokenisationURL. By doing so, an <iframe> hosting the payment mask is automatically added to the HTML element <div id="div-hosted-tokenization"></div> . The <iframe> opens the hostedTokenizationURL automatically.

Submit & tokenise card details

Your customers enter their card details in the <iframe> on your checkout page. Our platform detects the card scheme automatically once your customers start typing in the number. This also works for co-badged cards (where applicable).

Your customers submit the card data to our platform via the Javascript <button> element, invoking the submitTokenization() function from the JavaScript code snippet. Our platform tokenises the card data and returns a hostedTokenizationId.

Send CreatePayment request

You send a CreatePayment request to our platform, including the card details and mandatory 3-D Secure properties. Replace sensitive card data in the card property with the hostedTokenizationId.

Process platform response

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:

  1. 3-D Secure frictionless flow: (merchantAction.actionType=null): Your customers use a 3-D Secure enrolled card. The 3-D Secure properties 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.
  2. 3-D Secure challenge flow: (merchantAction.actionType="REDIRECT"): Your customers use a 3-D Secure enrolled card. They need to identify themselves as the rightful card owner. Redirect them to their issuer via the merchantAction.redirectData.redirectURL. Define a cardPaymentMethodSpecificInput.returnUrl in the initial CreatePayment request to make sure your customers are redirected to your webshop afterwards.
  3. No 3-D Secure authentication (merchantAction.actionType=null): Your customers use a non-3-D Secure enrolled card. We submit the transaction to the acquirer and provide the result in property statusOutput.statusCode.

Get & show transaction result

We receive the 3-D Secure / transaction result which you can request via a GetPaymentDetails request:

Alternatively, you can receive the result via webhooks.

Display the transaction result on your returnUrl (for 3-D Secure challenge flow transactions) or in your webshop (for 3-D Secure frictionless flow or no 3-D Secure transactions).  

Learn in our dedicated Status guide more about the properties from the response, their meaning and how to proceed appropriately depending on the transactions' status.


Find a full transaction flow involving every party and (optional) steps in this overview:

Die Grafik oben veranschaulicht alle Schritte einer typischen Hosted Tokenization Page Transaktion
  1. Your customers go to your check-out page and finalise the purchase.
  2. You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL.
  3. You add the <iframe> hosting the payment mask to your check-out page.
  4. Your customers enter their card details in the <iframe>.
    4'(optional). You 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.
  6. Our platform tokenises the card data and returns a hostedTokenizationId.
  7. You send a CreatePayment request to our to our platform using our Server-to-server integration method, including the mandatory 3-D Secure properties.
    7'(optional).We perform a fraud prevention check.
  8. Our platform sends a response containing a merchantAction object, instructing you how to proceed. These scenarios are possible:
    a) 3-D Secure frictionless flow (merchantAction.actionType=null). The flow continues at step 14).
    b) 3-D Secure challenge flow (merchantAction.actionType="REDIRECT"). The flow continues at step 9).
    c) No 3-D Secure authentication (merchantAction.actionType=null). The flow continues at step 14).
  9. You redirect the customer to her/his issuing bank for 3-D Secure authentication. The customer identifies herself/himself.
  10. Our platform receives the 3-D Secure authentication result from the issuer. Based on the result, two scenarios are possible:
    a) If the identification was unsuccessful, we redirect your customers to your returnURL, ending the flow. You request/show the transaction result as described in step 13.
    b) If the identification was successful, the flow continues at step 11.
  11. We process the transaction and receive the result from the acquirer.
  12. We redirect your customer to your returnURL.
  13. You request the transaction result from our platform and show it on your returnURL/in your webshop.
  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 customer did not agree to store the credentials.

Advanced customisation

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. Adapting the iframe to your corporate identity allows you to merge it seamlessly into your webshop. 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.

Choose language version

Our Hosted Tokenization Page is available in various languages. Populate locale to display it in your customers’ preferred language. The value is a combination of ISO 639-1 (language) and ISO 3166-1 (country):

    /* other properties omitted */ 

We support the following languages:



Simplified Chinese

Customise template

We provide two distinct approaches for implementing a customised template:

Method 1: Create a fully customised template 

Create a fully customised template from scratch using our powerful Template Builder. This approach offers a high degree of customisation, allowing you to make intricate changes to the payment form's appearance and functionality.

Method 2: Adapt template from GitHub repository

You can also download and customise the necessary files directly from our GitHub repository, providing even more flexibility. 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, contact us to upload the template to your account.

Visuelle Gestaltung anpassen

Sie können einen CSS-Stil auf die Abmessungen des iframe anwenden, damit er sich noch nahtloser in Ihren Webshop einfügt. Dazu fügen Sie diesen Abschnitt in Ihre .css-Datei ein:

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

Name des Karteninhabers verwalten

Mit unserer API können Sie Feld mit dem Namen des Karteninhabers im iframe wahlweise anzeigen oder ausblenden.
Dazu übergeben Sie im Tokenizer-Constructor entweder den booleschen Wert hideCardholderName: true oder den booleschen Wert hideCardholderName: false:

var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { hideCardholderName: false });
  • Wenn nichts angegeben ist, setzt unsere Plattform standardmäßig hideCardholderName: true
  • Der Name des Karteninhabers muss angegeben werden. Wenn Sie den Namen in Ihrer Webshop-Umgebung abrufen möchten, müssen Sie ihn im Formular senden:
    tokenizer.useCardholderName("Wile E. Coyote") 
    tokenizer.submitTokenization().then((result) => { ... })

Weitere Tokenizer-Argumente senden

Der in Schritt 3 beschriebene Tokenizer-Aufruf kann neben hideCardholderName weitere Argumente haben. Fügen Sie eines oder mehrere dieser Argumente zu Ihrer Anfrage hinzu, um den Zahlungsablauf je nach Bedarf anzupassen:

Argument Beschreibung
hideCardholderName Siehe das entsprechende Kapitel


Auf true setzen, wenn die iframe-Felder (Kartennummer, Name des Karteninhabers und Ablaufdatum) mit den in einem Token gespeicherten Daten für eine wiederkehrende Zahlung vorausgefüllt werden sollen


Siehe das entsprechende Kapitel



Zum Erkennen der verwendeten Kartenmarke, wenn die Kartennummer in das Zahlungsformular eingegeben wird:

var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', 
{ paymentProductUpdatedCallback: mypaymentProductUpdatedCallback });
function mypaymentProductUpdatedCallback(result) { /* Erkannte Kartenmarke auf Ihrer Checkout-Seite anzeigen/ausblenden */ }

Unsere Lösung Hosted Tokenization Page bietet viele weitere Möglichkeiten. Hier erfahren Sie alles über die verfügbaren Funktionen.

Vorhandenes Token verwenden

Auf unserer Plattform können Sie Kreditkartendaten Ihrer Kunden dauerhaft für wiederkehrende Zahlungen oder für Direktkäufe speichern und mit diesen Daten das Zahlungsformular vorausfüllen. Das macht die Zahlung für Ihre Kunden noch reibungsloser und verbessert Ihre Konversionsrate!

  • Durch Verwendung eines vorhandenen Tokens für Direktkäufe können Sie die Kreditkartennummer und das Ablaufdatum zur Vereinfachung für Ihre Kunden vorausfüllen.
  • Wegen von SCA müssen Ihre Kunden möglicherweise weiterhin ihren CVC eingeben und/oder eine 3-D Secure-Authentifizierungsprüfung durchführen. Unser Zahlungsformular zeigt automatisch die Pflichtfelder zum Ausfüllen an.

Da das Token zum Zeitpunkt der Transaktionsanfrage bereits vorhanden ist, ist der Zahlungsablauf anders:

  • Schritt 1: Weisen Sie unsere Plattform an, dass Sie ein vorhandenes Token verwenden möchten. Dazu ändern Sie die Anfrage createHostedTokenizationRequest, indem Sie die Eigenschaft tokens hinzufügen:

  • Eine erfolgreiche Anfrage sieht so aus:

    Status: 200 OK
        "hostedTokenizationId": "2f4d08d6ddfc411e944e81c54d824a99",
        "invalidTokens": [ "86a44668-5d0f-4e3f-a597-2aa0a4d03fe5" ],
        "hostedTokenizationUrl": "",
    "partialRedirectUrl": "" }
Wenn unsere Antwort einen Wert für die Eigenschaft invalidTokens enthält, ist das in Ihrer Anfrage gesendete Token ungültig. Verwenden Sie es nicht in der anschließenden Zahlung.
  • Schritt 2: Das angezeigte Formular mit den gespeicherten Kreditkartendaten vorausfüllen. Unsere Plattform bietet Ihnen dafür zwei Möglichkeiten:
    1. Gleich wenn Sie das Formular anzeigen, füllen Sie es aus. Dazu fügen Sie das Token als viertes Argument zum Konstruktor tokenizer hinzu:

    var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { }, '00164fec-32b2-462e-b48b-84a27930b10c');

    2. Wenn Sie das Formular anzeigen, lassen Sie es zunächst leer Lassen Sie Ihren Kunden in Ihrer Webshop-Umgebung die Wahl, ob sie mit ihrer gespeicherten Karte bezahlen möchten. Wenn ja, verwenden Sie die folgende Funktion zum Ausfüllen des Formulars:

    var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', { });
    // // Später, zum Beispiel wenn eine Benutzereingabe einen Tokenwechsel auslöst
    function tokenChanged () {
    tokenizer.useToken('00164fec-32b2-462e-b48b-84a27930b10c'); // Ändert das Formular, um das ausgewählte Token zu aktualisieren, und zeigt nur das CVC-Feld (falls erforderlich) an
    // oder
    tokenizer.useToken(); // Setzt das Formular zum Erstellen eines neuen Token zurück

    Sie können es Ihren Kunden auch gestatten, das Token im Zahlungsformular zu aktualisieren. Durch Initialisieren des booleschen Werts hideTokenFields wie folgt können Ihre Kunden:

    a) {hideTokenFields:true}: bekannte Felder (Kartennummer/Ablaufdatum) ausblenden
    b) {hideTokenFields:false}: Pflichtfelder sind sichtbar und können ausgefüllt werden / bekannte Felder können geändert werden (nur Karteninhabername/Gültigkeitsdatum)

    Die Anfrage sieht so aus:

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

Validierungsstatus abfragen

Ihre übergeordnete Seite kann den Validierungsstatus des Zahlungsformulars jederzeit abrufen. Übergeben Sie eine Validierungs-Callback-Funktion, die aufgerufen wird, wenn sich der Gültigkeitsstatus des Zahlungsformulars ändert. Achten Sie darauf, dass diese Funktion einen Parameter enthält, der ein Objekt mit dem booleschen Wert valid empfängt. Dieser boolesche Wert zeigt an, ob das Formular korrekt ausgefüllt ist.

Verwenden Sie diese Information zum Aktivieren/Deaktivieren die Schaltfläche "Absenden" auf der übergeordneten Seite, wenn das Zahlungsformular korrekt/falsch ausgefüllt ist. Fügen Sie diese Funktion zu Ihrem Skript in Schritt 3 hinzu:

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

Formular entfernen

Sie können das Zahlungsformular von der übergeordneten Seite entfernen. Der Aufruf dieser Funktion entfernt den iframe und seine Event-Listener:


tokenId statt hostedTokenizationId verwenden

Unsere Plattform bietet Ihnen die Möglichkeit, Transaktionen sowohl mit der hostedTokenizationId als auch mit der tokenId zu verarbeiten. Der Ablauf für die erste Variante ist in diesem Kapitel beschrieben. Zum Verwenden von TokenIDs müssen Sie den Ablauf wie folgt ändern:

Da Schritte 1. bis 4. und 7. bis 12. identisch mit dem Ablauf bei Verwendung der hostedTokenizationId sind, haben wir sie hier nur als Stubs hinzugefügt. Einzelheiten finden Sie im entsprechenden Kapitel.
  1. Eine Zahlungsanforderung wird eingeleitet
  2. Rufen Sie eine gültige Tokenisierungs-URL durch Aufruf von Create Hosted Tokenization ab
  3. Fügen Sie auf Ihrer Checkout-Seite ein Stück Code ein, mit dem Sie das Tokenisierungsformular mit der gültigen Tokenisierungs-URL als iframe auf Ihrer Checkout-Seite anzeigen können
  4. Ihr Kunde gibt seine Kreditkartendaten im iframe ein
  5. Das Token für die eigentliche Zahlung abrufen
    Stellen Sie das Ergebnis der Tokenisierung wieder her, indem Sie von Ihrem Backend aus einen GetHostedTokenization-Aufruf durchführen

Für Anfragen an unsere TEST-Umgebung:
Für Anfragen an unsere LIVE-Umgebung: 
  1. Erstellen Sie die eigentliche Zahlung mit dem Token. Senden Sie eine CreatePayment-Anfrage an unseren Server. Für die Anfrage können Sie das folgende Code-Beispiel verwenden:
  1. Sie leiten Ihre Kunden für eine 3-D Secure-Prüfung an ihre ausstellende Bank weiter. Der / die Karteninhaber/in identifiziert sich
  2. Unser System erhält das Ergebnis vom Kreditkartenherausgeber.
  3. Wir senden die eigentliche Finanztransaktion zur Verarbeitung an den Acquirer
  4. Wir leiten Ihren Kunden um zu Ihrer ReturnUrl
  5. Sie fragen das Ergebnis der Transaktion via GetPayment bei unserer Plattform an oder Sie erhalten das Ergebnis via Webhooks.
  6. Wenn die Transaktion erfolgreich verlaufen ist, können Sie die Güter / Dienstleistungen ausliefern.
    12' (optional): Das Token löschen

Pre-select available card schemes

You can exclude or preselect specific card schemes from the iframe using the properties from object paymentProductFilters in your CreateHostedTokenization request:

  • exclude.products: Array of paymentProductIds to be filtered out
  • restrictTo.products: Array of paymentProductIds that should be available

Find the value for the individual paymentProductIds in column "Payment Product-ID" in this overview.

  • Find detailed information about this object and its properties in our CreateHostedTokenizationAPI.
  • exclude will override any value in restrictTo and thereby ensure exclusion.
  • If your customers enter a number from any card scheme you have made unavailable via exclude, the payment mask will display "Card number incorrect or incompatible".

Manage Card Verification Value

Due to PCI DSS regulations, we are only allowed to store a card’s verification value (CVV/CVC) for a maximum of two hours.

For single payments via the Hosted Tokenization Page, this time span is adequate to initialise the payment. However, when processing recurring payments using permanently stored tokens, you will face the following scenario: for any subsequent payment, our platform prefills the <iframe> fields - except for the CVC code due to this regulation.

To further smooth out your customers' payment experience, our platform allows you to make the CVC check optional. This applies to both the

  • Initial payment when creating the token.
  • Subsequent payment when using the token.

You can achieve this by implementing the following properties in your checkout page / CreateHostedTokenization request respectively:

Property Description

cvvMandatoryForNewToken: Set to either "true" or "false" in your request to allow your customers to enter the CVC in the <iframe> payment form or not.

cvvMandatoryForExistingToken:  Set to either "true" or "false" in your request to allow your customers to enter the CVC in the <iframe> payment form or not. Applicable only when using existing tokens and thereby prefilling the payment form. 

hideOptionalCvv Tokenizer class argument used for initialising the <iframe> on your checkout page.

Set to either "true" or "false" depending on whether you want to keep/hide the "Card verification code" field in the payment form.

When sending "false" for either cvvMandatoryForNewToken/cvvMandatoryForExistingToken property, the validation check will trigger a successful form validation event also when CVC is not added to the iframe. This allows you to continue with the payment flow by sending the actual payment request.

For CreatePayment requests sent without the hostedTokenizationId, our platform takes into account whether the CVC is mandatory for the payment method. Contact us to configure the respective payment method(s) for you in your account. To overwrite that setting per session, we strongly recommend sending the hostedTokenizationId instead of the token in your CreatePayment request.

Make sure to align with your acquirer if you want to make the CVV check optional or skip it altogether. In some cases, you might become liable for chargebacks.

Was this page helpful?

Do you have any comments?

Thank you for your response.