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!

Flows

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

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 language and 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.