Hosted Tokenization Page

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!

Beim Kauf in Ihrem Webshop müssen Ihre Kunden zu einem bestimmten Zeitpunkt ihre Kreditkartennummer angeben. Für Sie als Händler besteht die größte Herausforderung darin, alle Schritte auf diesem Weg zu einem nahtlosen Ablauf zu verbinden. Gleichzeitig müssen Sie die sichere Übermittlung der Daten Ihrer Kunden an die Finanzinstitute gewährleisten, die diese Daten verarbeiten.

Darum können Sie

• die notwendigen Sicherheitsvorkehrungen vollständig auslagern (mit unserer Lösung Hosted Checkout). Diese Methode hat jedoch ihre Grenzen: Ihre Kunden werden eine Weiterleitung zu einer externen URL bemerken - eine spürbare Unterbrechung im Zahlungsprozess
• die sensiblen Daten selbst erfassen (mit Server-to-server-Lösung). Dafür müssen Sie jedoch die strengsten PCI-Anforderungen erfüllen, und das ist mit einem hohen Aufwand verbunden

Unsere Hosted Tokenization Page löst dieses Dilemma für Sie, indem es das Beste aus beiden Welten vereint:

• Damit überlassen Sie uns die Verarbeitung der Kreditkartendaten, ohne dass Ihre Kunden es merken. Sie fügen einfach einen iframe in Ihren Webshop ein, der das Zahlungsformular enthält. Da wir der Host sind, kommen die sensiblen Daten zu uns und bleiben bei uns! Wir ersetzen die Kartendaten durch ein Token, welches keine Relevanz für PCI hat.
• Gleichzeitig lässt es sich nahtlos in den Look and Feel Ihres Webshops einbinden. Passen Sie das Zahlungsformular ganz nach Belieben an!

Ziel-Endpunkt-URLs in Test / Live

Mit unserer Plattform können Sie Anfragen an unsere Test- oder Live-Umgebung senden:

• Endpoint URL TEST: https://payment.preprod.payone.com/v2/MERCHANT_ID/hostedtokenizations
• Endpoint URL LIVE: https://payment.payone.com/v2/MERCHANT_ID/hostedtokenizations

Checkout-Seite erstellen

Für unsere Hosted Tokenization Page-Lösung müssen Sie die folgenden HTML/JavaScript-Elemente auf Ihrer Checkout-Seite hinzufügen:

<div id="div-hosted-tokenization"></div>
<button onclick="submitForm()">submit</button>
<script src="https://payment.preprod.payone.com/hostedtokenization/js/client/tokenizer.min.js"/> <!-- enthält die notwendigen Methoden zum Tokenisieren -->
<script> 
    // Zum Tokenisieren der Kreditkartendaten. In das Formular in ein bestehendes DOM-Element auf Ihrer Checkout-Seite laden
    var tokenizer = new Tokenizer(hostedTokenizationUrl, 'div-hosted-tokenization', {hideCardholderName: false });

    tokenizer.initialize().then(() => {
        // Ggf. Aufgaben nach Initialisierung ausführen
    })
    .catch(reason => {
        // iFrame-Ladefehler behandeln
    })
    function submitForm(){ // 
        tokenizer.submitTokenization().then((result) => {
            if (result.success) {
                // Weiter
            } else {
                // displayErrorMessage(result.error.message);
            }
        });
    }
</script>

Die einzelnen Elemente haben eine bestimmte Aufgabe im Zahlungsablauf:

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

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

var tokenizer

Im folgenden Kapitel erfahren Sie, wie Sie diese Elemente im Zahlungsablauf implementieren.

Den Zahlungsablauf verstehen

Unsere Server SDKs stellen eine Hosted Tokenization Page API bereit. Sie bietet alle Methoden, die Sie für alle Schritte eines typischen Zahlungsablaufs brauchen:

1. Ihre Kunden gehen auf Ihre Checkout-Seite mit diesen HTML/JavaScript-Elementen und schließen den Kauf ab
2. Sie senden eine CreateHostedTokenization-Anfrage an unsere Plattform. Unsere Plattform gibt eine hostedTokenizationURL zurück
   Verwenden Sie für die Anfrage das folgende Code-Beispiel:

1. 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.

1. 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).
   4'(optional). Use our validation function to check whether the cardholder has filled in the form correctly.

1. Your customers submit the card data to our platform via the <button> element. This button invokes the submitTokenization() function from the JavaScript code snippet.
2. Our platform tokenises the card data. A successful response looks like this:

   {
   "success": true,
   "hostedTokenizationId": string
   }
   

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

   In case of an error, the response will look like this:

   {
   "success": false,
   "error": {
   "message": string
   }
   }

   The message contains a human-readable reason for the error

3. You send a CreatePayment request to our platform using our Server-to-server integration mode, including the mandatory 3-D Secure properties. Replace sensitive card data in the card property with the hostedTokenizationId.
   7'(optional). We perform a Fraud check.
   
   Use the following code sample for the request:

1. 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 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. The flow continues at step 14.
   
   b) 3-D Secure challenge flow authentication (MerchantAction.ActionType=REDIRECT): Your customers use a 3-D Secure enrolled card. They need to identify themselves as the rightful card owner. The flow continues at step 9.
   
   c) 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. The flow continues at step 14.
   
   
2. You redirect the customers to their issuing bank to the MerchantAction.RedirectData.RedirectURL.
3. 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 customers 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.
   
   
4. We submit the actual financial transaction to the acquirer to process it. We receive the transaction result.
5. We redirect your customers to your returnUrl.
6. You request the transaction result from our platform via GetPayment or receive the result via webhooks.
7. 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.

tokenizer.submitTokenization({ storePermanently:false })

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

{ 
    „locale”:„en_EN”, 
    
    /* other properties omitted */ 
}

We support the following languages:

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 });

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:

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!

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": "https://payment.preprod.payone.com//hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99",
      "partialRedirectUrl": "preprod.payone.com//hostedtokenization/tokenization/form/2f4d08d6ddfc411e944e81c54d824a99"
  }
  

• 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:

tokenizer.destroy();

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:

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
   
   

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.

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:

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.