Table Of Contents
  INTRODUCTION  RELEASE VERSIONS  KEY FEATURES  REQUIRED CONFIGURATION  SUBMITTING THE PAYMENT DATA  CALLBACKS   SAMPLE APPLICATION    TEST CARDS FOR TESTING OF INTEGRATION   GOING TO PRODUCTION

Introduction

The Hosted Tokenization SDK allows to embed a secure payment form into your web application. It renders the payment page via an iframe and provides methods to customize the UI, handle tokenization, and submit payment data securely.

Important remark: 

 This guide enhances the Credit Card Documentation and doesn`t replace it.  

 Please read  the New - Credit and Debit Card Payments first. 

Release Versions

Currently the latest version is 1.3.0. Please migrate to the newer version once available.

Supported versions of the SDK :

  • 1.0.2
  • 1.3.0 - Recommended 

You will always use the latest Hosted Tokenization Page even while using the older version of the SDK.  This ensure higher security and stability. However certain feautures and configurations are not supported by the older versions. 

Key Features

  • Easy embedding of payment iframe.
  • Customizable form styles.
  • Customizable text for field lables, errors and aria-lables.
  • Secure tokenization of card details.
  • Callbacks for payment status and errors.

Required configuration

Property Required Type Default Description
iframe.iframeWrapperId Mandatory string n/a ID of the HTML container for the iframe
iframe.height Optional number | string auto If not provided, the height will be automatically adjusted. When specified, the value will serve as the minimum height of the iframe in pixels.
iframe.width Optional number | string 400 Maximum width of iFrame in pixels
iframe.zIndex Optional number | string 9999 Z-Index of the Iframe
uiConfig Optional Object Default UI Custom styling of the form. See more details below. 
locale Optional

string

 en_US de_DE → Deutsch
en_US → English
token Mandatory string JWT token for authentication
mode Optional string LIVE only LIVE is supported
allowedCardSchemes Optional string All cards are allowed

If not provided or provided an empty array, all the cards are allowed. Merchants should pass the values in all lowercase ("mastercard", "amex").

Only version 1.2 and above
customTextConfig Optional Object Default text  If provided it will replace the default text for field lables, errors and aria-lables for provided fields.

 

Full config object example - version 1.3 of the SDK
  const config = {
    iframe: {
      iframeWrapperId: "payment-IFrame",
      height: 400,
      width: 400,
      zIndex: 9999,
    },
    uiConfig: {
    formBgColor: "#E9EEF5",
    formMarginLeft: "20px",
    formMarginRight: "20px",
    fieldBgColor: "#FDFDFD",
    fieldBorder: "#8FA8C8 solid 2px",
    fieldOutline: "#3B82F6 solid 3px",
    fieldLabelColor: "#334155",
    fieldPlaceholderColor: "#6B7280",
    fieldTextColor: "#1E293B",
    fieldErrorCodeColor: "#D97706",
    fontFamily: "Sansation",
    fontUrl: `https://fonts.googleapis.com/css2?family=Sansation:ital,wght@0,300;0,400;0,700;1,300;1,400;1,700&display=swap`,
    labelStyle: {
      fontSize: "22px",
      fontWeight: "",
      fontSizeMobile: "20px",
    },
    inputStyle: {
      fontSize: "20px",
      fontWeight: "normal",
      fontSizeMobile: "18px",
    },
    errorValidationStyle: {
      fontSize: "20px",
      fontWeight: "lighter",
      fontSizeMobile: "18px",
    },
    manualEntryFormLabelStyle: {
      fontSize: "15px",
      fontWeight: "bold",
      fontSizeMobile: "20px",
    },
    checkboxLabelStyle: {
      fontSize: "15px",
      fontWeight: "normal",
      fontSizeMobile: "16px",
    },
    termsTextStyle: {
    fontSize: "15px",
    fontWeight: "normal",
    fontSizeMobile: "14px",
    },
    checkboxLabelColor: "#334155",
    checkboxSize: "20px",
    btnBgColor: "#6390f2",
    btnTextColor: "#FFFFFF",
    btnBorderColor: "#6390f2",
    separatorColor: "#8FA8C8",
    separatorTextColor: "#64748B",
    termsTextColor: "#475569",
    inputBorderRadius: "8px",
    inputBorderColorDefault: "#7a0f45",
    inputBorderColorSuccess: "#22C55E",
    inputBorderColorError: "#821030",
    inputFocusOutline: "#3B82F6 auto 0px",
    inputPadding: "12px 16px",
    fieldSpacingVertical: "5px",
    labelMarginBottom: "10px",
    inputMarginBottom: "10px",
    errorMarginBottom: "10px",
    buttonMarginBottom: "16px",
    separatorTextMarginBottom: "20px",
    checkboxTextMarginBottom: "10px",
    termsTextMarginBottom: "10px",
    iconWidth: "60px",
    iconPaddingRight: "20px"
    },
    locale: "de_DE",
    token: <token_value_here>,
    mode: 'live',
    allowedCardSchemes: [
        "amex",
        "diners",
        "discover",
        "maestro",
        "mastercard",
        "visa",
        "unionpay",
    };   
    customTextConfig: {
                    en: {
                        labels: {
                            cardNumber: "Please enter your card number Custom Text",
                            cardholderName: "Cardholder Name Custom Text"
                        },
                        placeholders: {
                            cardNumber: "cardNumber Custom placeholder",
                            cardholderName: "CarholderNamr Custom placeholder",
                        },
                        arialabels: {
                            cardNumber: "Enter your card number custom text",
                            cardholderName: "Enter the name on the card custom text",
                        },
                        errors: {
                            cardNumber: {
                                isRequired: "Card number is required custom text",
                                isInvalid: "Invalid card number custom text",
                                isTooShort: "Card number is too short custom text",
                                notSupported: "Card number not supported custom text"
                            },
                            cardholderName: {
                                isRequired: "Cardholder name is required custom text",
                                isInvalid: "Invalid Cardholder name custom text"
                            }
                        }
                    },
                    de: {
                        labels: {
                            cardNumber: "Bitte geben Sie Ihre Kartennummer ein Benutzerdefinierter Text",
                            cardholderName: "Name des Karteninhabers Benutzerdefinierter Text"
                        },
                        placeholders: {
                            cardNumber: "Kartennummer benutzerdefinierter Platzhalter",
                            cardholderName: "Name des Karteninhabers benutzerdefinierter Platzhalter"
                        },
                        arialabels: {
                            cardNumber: "Geben Sie Ihre Kartennummer ein Benutzerdefinierter Text",
                            cardholderName: "Geben Sie den Namen auf der Karte ein Benutzerdefinierter Text"
                        },          
                        errors: {
                            cardNumber: {
                                isRequired: "Kartennummer ist erforderlich Benutzerdefinierter Text",
                                isInvalid: "Ungültige Kartennummer Benutzerdefinierter Text",
                                isTooShort: "Kartennummer ist zu kurz Benutzerdefinierter Text",
                                notSupported: "Kartennummer wird nicht unterstützt Benutzerdefinierter Text"
                            },
                            cardholderName: {
                                isRequired: "Name des Karteninhabers ist erforderlich Benutzerdefinierter Text",
                                isInvalid: "Ungültiger Name des Karteninhabers Benutzerdefinierter Text"
                            }
                        }
                    }
                },  //(Refer to the 'Example customTextConfig object' section for all supported parameters.)

---end

Submitting the Payment Data

Trigger form submission and tokenization button should be implemented on the Merchant page:

Button sample
<button onclick="window.HostedTokenizationSdk.submitForm(successCallback, failureCallback)">Submit</button>

---end

 

Callbacks

Callback Description Parameters Description
`successCallback` Called on successful tokenization `statusCode`, `token` (string), `cardDetails` (object) This callback is triggered when card tokenization completes successfully using the JS SDK.
`failureCallback` Called if tokenization fails `statusCode`, `error` (string/object)

---end

Callback handling function
function successCallback(statusCode, token, cardDetails) {
  console.log('Tokenization succeeded:', statusCode, token, cardDetails);
}

success Callback

This callback is triggered when card tokenization completes successfully using the JS SDK. This has to be handled 

Name Type Description
statusCode number HTTP-style status code. 201 indicates successful tokenization.
token string Unique token representing the card. Securely store this for future transactions.
cardDetails object Contains masked card data and metadata. See below.
inputMode string Method used for tokenization (eg. manual, register or ClickToPay)

cardDetails object
 
Property Type Description
cardholderName string Name of the cardholder as entered.
 
cardNumber string Truncated card number (411111XXXXXX1111).
expiryDate string Card expiry in MM/YY format (e.g. 11/33 = November 2033).
cardType string Card scheme 

---end

Sample Success Callback
successFunction(
  201,
  "12121212121212212111",
  {
    cardholderName: "Max",
    cardNumber: "411111XXXXXX1111",
    expiryDate: "1133",
    cardType: "VISA"
  },
  inputMode: manual
);

Customizing Payment Form User interface

The application support UI and Text configuration by using the specific configuration to allow the changes. Please use the 1.3 Version to use all below the described below configuration options. 
If the configuration is not provided - the default values are provided.

ui-Config Parameters 

Basic UI Configurations 
Attribute Type Description Example
formBgColor string Background color of the entire form "black"
fieldBorder string Background color of individual input fields "wheat"
fieldOutline string CSS border for input fields "1px solid #b33cd8"
fieldLabelColor string CSS outline for fields on focus/active "cyan solid 5px"
fieldPlaceholderColor string Color of the field labels "#d3d83c"
fieldTextColor string Color of placeholder text in inputs "blue"
fieldErrorCodeColor string Color of text entered by the user "crimson"

---end

UI Config Sample
const uiConfig = {
  formBgColor: "black",
  fieldBgColor: "wheat",
  fieldBorder: "1px solid #b33cd8",
  fieldOutline: "cyan solid 5px",
  fieldLabelColor: "#d3d83c",
  fieldPlaceholderColor: "blue",
  fieldTextColor: "crimson",
  fieldErrorCodeColor: "green"
};

window.HostedTokenizationSdk.customizeUI(uiConfig, callbackFunction);

---end

Font and Text Configurations 

Font configurations

In version 1.0.2 features for customizing the font of the document, font size and font weight for the fields have been introduced. This can be configured by adding the fields specified below.

Attribute Type Description Example
fontFamily string The family of the font. For google fonts, it should be a valid value specified by google fonts. For font file URL, any custom string can be given. "Mozilla Headline"
fontUrl string The URL of the that needs to be applied. It can be a google fonts URL or a URL of a font file.
Supported font files: .woff2, .woff, .ttf, .otf, .eot, .svg, .sfnt

 "https://fonts.googleapis.com/css2?family=Mozilla+Headline:wght@200..700&

family=Nata+Sans:wght@100..900&display=swap"
labelStyle.fontSize string Font size of the label element. The fontSize should be a unit value (eg. px, em, rem, %). Values like s-small, large cannot be applied. "20px"
labelStyle.fontWeight string Font weight of the label element. Any valid css value can be applied "900"
inputStyle.fontSize string Font size of the input element. The fontSize should be a unit value (eg. px, em, rem, %). Values like s-small, large cannot be applied. "20px"
inputStyle.fontWeight string Font weight of the input element. Any valid css value can be applied "normal"
errorValidationStyle.fontSize string Font size of the error message element. The fontSize should be a unit value (eg. px, em, rem, %). Values like s-small, large cannot be applied. "16px"
errorValidationStyle.fontWeight string Font weight of the error message element. Any valid css value can be applied "bold"

---end

Example config object
const uiConfig = {
   formBgColor: "black",
  fieldBgColor: "wheat",
  fieldBorder: "1px solid #b33cd8",
  fieldOutline: "cyan solid 5px",
  fieldLabelColor: "#d3d83c",
  fieldPlaceholderColor: "blue",
  fieldTextColor: "crimson",
  fieldErrorCodeColor: "green",
  fontFamily: "Mozilla Headline",
  fontUrl: "https://fonts.googleapis.com/css2?family=Mozilla+Headline:wght@200..700&family=Nata+Sans:wght@100..900&display=swap",
  labelStyle: {
    fontSize: "20px",
    fontWeight: "900",
  },
  inputStyle: {
    fontSize: "20px",
    fontWeight: "normal",
  },
  errorValidationStyle: {
    fontSize: "16px",
    fontWeight: "normal",
  },
};

Text and Locale support

Text configuration is supported in version 1.3 and above only.

Our application natively supports only German and English locale values out of the box starting from the initial release. 
Supported Locale Values
     locale: "de_DE"
     locale: "en_US"

---end

 
However It is possible for the Merchant to customize the texts on the Hosted tokenization page :
  • Main fields naming visible in the UI
  • Validation Errors
  • Aria labels
  • Custom languages support

supported languages text changes

In order to modify the current text for a certain language you can provide the Language value (en: { }, ) in the configuration. 

Partial modification is supported so you are able to modify only some part of the default texting by providing the configuration only for the needed fields

Custom Language

In order to use the custom language you need to provide a complete configuration for the language in the configuration. If this is not provided - the missing field will use a fallback language - English.

Sample configuration - English and Czech

This configuration sample replaces standard text for english and extends the app to support czech language as an example. 

To display czech language you will need to provide the czech configuration from the sample below and set locale: "cs_CZ".

---end

 

If you want to use default English translations (recommended) please remove the en config from the sample below. 

---end

 

---end

Sample config
customTextConfig: {
    en: {
        labels: {
            cardNumber: "Card number",
            cardholderName: "Cardholder Name",
            expiryDate: "Expiry Date",
            securityCode: "Security Code",
        },
        placeholders: {
            cardNumber: "cardNumber ",
            cardholderName: "CarholderName ",
            expiryDate: "expiryDate Custom ",
            securityCode: "securityCode ",
        },
        arialabels: {
            cardNumber: "Enter your card number",
            cardholderName: "Enter the name on the card",
            expiryDate: "Enter the expiration month and year of your card",
            securityCode: "Enter the card verification code",
        },
        errors: {
            cardNumber: {
                isRequired: "Card number is required",
                isInvalid: "Invalid card numbe",
                isTooShort: "Card number is too short",
                notSupported: "Card number not supported",
            },
            cardholderName: {
                isRequired: "Cardholder name is required ",
                isInvalid: "Invalid Cardholder name"
            },
            expiryDate: {
                isRequired: "Expiry date is required",
                isInvalid: "Invalid Expiry date"
            },
            securityCode: {
                isRequired: "security code is required",
                amexCardSecurityCodeError: "Invalid security code",
                generalSecurityCodeError: "Invalid security code"
            },
        },  
    },
    cs: {
        labels: {
            cardNumber: "Číslo karty",
            cardholderName: "Jméno držitele karty",
            expiryDate: "Platnost",
            securityCode: "Bezpečnostní kód",
        },
        placeholders: {
            cardNumber: "1234 1234 123 1234",
            cardholderName: "Jan Pavel",
            expiryDate: "MM/RR",
            securityCode: "123",
        },
        arialabels: {
            cardNumber: "Zadejte číslo karty",
            cardholderName: "Zadejte jméno držitele karty",
            expiryDate: "Zadejte měsíc a rok expirace karty",
            securityCode: "Zadejte bezpečnostní kód karty",
        },
        errors: {
            cardNumber: {
                isRequired: "Zadejte číslo karty",
                isInvalid: "Neplatné číslo karty",
                isTooShort: "Číslo karty je příliš krátké",
                notSupported: "Tento typ karty není podporován",
            },
            cardholderName: {
                isRequired: "Zadejte jméno držitele karty",
                isInvalid: "Neplatné jméno držitele karty"
            },
            expiryDate: {
                isRequired: "Zadejte měsíc a rok expirace karty",
                isInvalid: "Neplatné datum expirace"
            },
            securityCode: {
                isRequired: "Zadejte bezpečnostní kód karty",
                amexCardSecurityCodeError: "Neplatný bezpečnostní kód",
                generalSecurityCodeError: "Neplatný bezpečnostní kód"
            },
        },  
    },
}

---end

 Sample Application 

This is a Sample Application that you may use for the integration of the Hosted Tokenization. 

Tokenization page example
<html>
    <head>
        <script src="https://sdk.preprod.tokenization.secure.payone.com/1.3.0/hosted-tokenization-sdk.js" integrity="sha384-2mqrh4mWkGZN9XmQeJFzKX5t+i9at3NYnUT9qvS2GiMRe8a6pigcsaxGh5y7KwbG" crossorigin="anonymous"></script>
        <!--Production: <script src="https://sdk.tokenization.secure.payone.com/1.3.0/hosted-tokenization-sdk.js" integrity="sha384-2mqrh4mWkGZN9XmQeJFzKX5t+i9at3NYnUT9qvS2GiMRe8a6pigcsaxGh5y7KwbG" crossorigin="anonymous"></script>-->
        <script>
            function tokenizationSuccessCallback(statusCode, token, cardDetails) {
                // This is where you can do stuff with the token and the cardDetails e.g.:
                console.log(statusCode); // e.g. 201
                console.log(token);
                console.log(cardDetails.cardholderName);
                console.log(cardDetails.cardNumber);
                console.log(cardDetails.expiryDate);
            }

            function tokenizationFailureCallback(statusCode, errorResponse) {
                // This is where you can handle errors that can happen during the tokenization (e.g. expired JWTs or malformated JWTs)
                console.log(statusCode); // e.g. 400
                console.log(errorResponse.error); // optional e.g. "JWT structure is incorrect."
            }

            const config = {
                iframe: {
                    iframeWrapperId: "payment-IFrame",
                    height: 400,
                    width: 400,
                    zIndex: 9999,
                },
                uiConfig: {
                    formBgColor: "#64bbb7",
                    fieldBgColor: "wheat",
                    fieldBorder: "1px solid #b33cd8",
                    fieldOutline: "#101010 solid 5px",
                    fieldLabelColor: "#d3d83c",
                    fieldPlaceholderColor: "blue",
                    fieldTextColor: "crimson",
                    fieldErrorCodeColor: "green",
                   fontFamily: "Mozilla Headline",
                    fontUrl: "https://fonts.googleapis.com/css2?family=Mozilla+Headline:wght@200..700&family=Nata+Sans:wght@100..900&display=swap",
                    labelStyle: {
                        fontSize: "20px",
                        fontWeight: "900",
                    },
                    inputStyle: {
                        fontSize: "20px",
                        fontWeight: "normal",
                    },
                    errorValidationStyle: {
                        fontSize: "16px",
                        fontWeight: "normal",
                    },
                    btnBgColor: "#6390f2",
                    btnTextColor: "#FFFFFF",
                    btnBorderColor: "#6390f2",
                    separatorColor: "#8FA8C8",
                    separatorTextColor: "#64748B",
                },
                locale: "de_DE",
                token: "<Token to be retrieved from the CommercePlatform-API>",
                allowedCardSchemes: [
                    "amex",
                    "diners",
                    "discover",
                    "maestro",
                    "mastercard",
                    "visa",
                    "unionpay",
                },
                customTextConfig: {
                    en: {
                        labels: {
                            cardNumber: "Please enter your card number Custom Text",
                            cardholderName: "Cardholder Name Custom Text"
                        },
                        placeholders: {
                            cardNumber: "cardNumber Custom placeholder",
                            cardholderName: "CarholderNamr Custom placeholder",
                        },
                        arialabels: {
                            cardNumber: "Enter your card number custom text",
                            cardholderName: "Enter the name on the card custom text",
                        },
                        errors: {
                            cardNumber: {
                                isRequired: "Card number is required custom text",
                                isInvalid: "Invalid card number custom text",
                                isTooShort: "Card number is too short custom text",
                                notSupported: "Card number not supported custom text"
                            },
                            cardholderName: {
                                isRequired: "Cardholder name is required custom text",
                                isInvalid: "Invalid Cardholder name custom text"
                            }
                        }
                    },
                    de: {
                        labels: {
                            cardNumber: "Bitte geben Sie Ihre Kartennummer ein Benutzerdefinierter Text",
                            cardholderName: "Name des Karteninhabers Benutzerdefinierter Text"
                        },
                        placeholders: {
                            cardNumber: "Kartennummer benutzerdefinierter Platzhalter",
                            cardholderName: "Name des Karteninhabers benutzerdefinierter Platzhalter"
                        },
                        arialabels: {
                            cardNumber: "Geben Sie Ihre Kartennummer ein Benutzerdefinierter Text",
                            cardholderName: "Geben Sie den Namen auf der Karte ein Benutzerdefinierter Text"
                        },          
                        errors: {
                            cardNumber: {
                                isRequired: "Kartennummer ist erforderlich Benutzerdefinierter Text",
                                isInvalid: "Ungültige Kartennummer Benutzerdefinierter Text",
                                isTooShort: "Kartennummer ist zu kurz Benutzerdefinierter Text",
                                notSupported: "Kartennummer wird nicht unterstützt Benutzerdefinierter Text"
                            },
                            cardholderName: {
                                isRequired: "Name des Karteninhabers ist erforderlich Benutzerdefinierter Text",
                                isInvalid: "Ungültiger Name des Karteninhabers Benutzerdefinierter Text"
                            }
                        }
                    }
                },  //(Refer to the 'Example customTextConfig object' section for all supported parameters.)
            }

            if (window.HostedTokenizationSdk) {
                async function loadSDK() {
                    try {
                        await window.HostedTokenizationSdk.init();
                        window.HostedTokenizationSdk.getPaymentPage(config);
                    } catch (error) {
                        console.error('Error initializing HTP-SDK:', error);
                    }
                }
                loadSDK();
            } else {
                console.log("HTP-SDK failed to load");
            }
        </script>
    </head>
    <body>
        <div id="payment-IFrame"></div>
            <button onClick="window.HostedTokenizationSdk.submitForm(tokenizationSuccessCallback, tokenizationFailureCallback)">Submit</button>
    </body>
</html>
In the iFrame example the JWT Token to be used - Please refer to the New - Credit and Debit Card Payments first. 

---end

 Run html on a webserver to load the javaScript file from payone server

If you want to test this script locally, you can use docker to test it:

docker run -p 80:80 -v <your directory>:/usr/local/apache2/htdocs/ httpd:latest
The page will load the JavaScript and use the configured credentials to perform a tokenization request.

---end

 Test cards for testing of integration

With the following test card data the described integration can be tested to create a token: https://docs.payone.com/security-risk-management/3d-secure#/

---end

 Going to production

If you want to switch to production, please exchange the source domain of the JS by changing

<script src="https://sdk.preprod.tokenization.secure.payone.com/1.0.2/hosted-tokenization-sdk.js" integrity="sha384-JavLFVzhH2fmwhTeBqVkXIiKlGAMbvznkievdJ4VHNpc02zWI0djUJS6J9LVI9L3" crossorigin="anonymous"></script>


to

<script src="https://sdk.tokenization.secure.payone.com/1.0.2/hosted-tokenization-sdk.js" integrity="sha384-JavLFVzhH2fmwhTeBqVkXIiKlGAMbvznkievdJ4VHNpc02zWI0djUJS6J9LVI9L3" crossorigin="anonymous"></script>