Table Of Contents
  NEW HOSTED TOKENIZATION FORM  INTEGRATION   STEP 4: TEST CARDS FOR TESTING OF INTEGRATION  STEP 5: GOING TO PRODUCTION

New hosted tokenization form

In order to be able to integrate  new payment methods on your Checkout you have to first integrate the new Hosted Tokenization Page. 

The new form was developed to comply with modern accesibility and UI requirement also simplyfying the integration. 

Only tokenization in fronted is changing.
No change for the creditcard processing is needed. You receive PPAN and other data that is needed for the existing Authorization/Preauthorization and other requests.

---end

 

Integration 

This documentation is simplified and should be enough for the simple integration. For extended documentation please use the extended documentation. 

Session Initiation Request

In order to load the JS SDK and Hosted Tokenization Page you have first to fetch the JWT from the Server API of Payone.  This is a new API Request against our Server API that will return a JWT that later has to be included while loading the SDK/HTP as a token value. Currently the validity of the Token is 10 minutes and it can be used multiple times during this time to tokenize card data. 

Step 1: JWT Token Generation

Create a Json Web Token 

Creating a JWT needed for later authentication within JS form when is being submitted for card processing

---end

POST  Request to retrieve a JWT token
POST  https://api.pay1.de/post-gateway/
Accept: application/json
Content-Type: application/x-www-form-urlencoded

request=getJWT
    &mid=123456
    &portalid=YOURPORTALID
    &key=%HASH_of_THE_PORTAL__KEY%

---end

Sample response
Response JWT
HTTP/1.1 200
Date: Mon, 13 Oct 2025 05:55:03 GMT
Server: Apache
Vary: Origin,Access-Control-Request-Method,Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Content-Length: 687
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
  "creationDate": "2025-10-13T05:55:03Z",
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhcGlndzAxLmpha2t1LnBheTEtdGVzdC5kZSIsInN1YiI6IjEwMTc2IiwiYXVkIjoiYXBpZ3cwMS5qYWtrdS5wYXkxLXRlc3QuZGUiLCJleHAiOjE3NjAzMzU4MDMsImlhdCI6MTc2MDMzNDkwMywianRpIjoiYWQ3YWYzMTEtZmUxYi00YjViLTkyY2QtMmFmM2I4ZGExOTZjIn0.E5WGje6E8KmUq3o8zAV4dwjBQauNcm7od41kdxGkeOCgJ3gVFP59HrB6EUikuUCfZWrr4vWR9IviVbgdSq6IPsQ8hLHgDudGHXQU9mfWJuW_E5-mBzpOF9fNP6hppNb3M-Qq0gLSwEQNP1RwZgxpG7DNaoKlTl9OqEoPDqFt9I-RFQAvgI5ArwSn9w5yKn5YaXd_cOxZb7-UxiVHJ6m97TxMmtCgkibPc8gAmq0eHngdFm4qiULyN9oRPZoloahbJiSeqGo89IRRc4NvMPrzkk5DnOGCkh9D9xJEYKATfYI4eGTZWusVBRgSH-SEw5-ew_Q0t8yaTtaDjs_-pgcLnA",
  "status": "ok",
  "expirationDate": "2025-10-13T06:10:03Z"
}

Step 2: hosted iframe for tokenization of credit and debit cards

---end

Don`t forget to change mode to LIVE before going to Production. 

---end

 

Tokenization page example
<html>

<head>

<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("Tokenized card sucessfully");

            console.log(statusCode); // e.g. 201
            console.log(token);
            console.log(cardDetails.cardholderName);
            console.log(cardDetails.cardNumber);
            console.log(cardDetails.expiryDate);
            console.log(cardDetails.cardType);
        }

        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("Tokenization of card failed");

            console.log(statusCode); // e.g. 400
            console.log(errorResponse.error); // optional e.g. "JWT structure is incorrect."
        }

        function callbackfunc(statusCode, res) {
            console.log("statusCode:", statusCode);
        }

        const config = {
            iframe: {
                iframeWrapperId: "payment-IFrame",
                zIndex: 10000,
                height: 500,
                width: 400
            },
            uiConfig: {
                // formBgColor: "#64bbb7",
                // fieldBgColor: "wheat",
                // fieldBorder: "1px solid #b33cd8",
                // fieldOutline: "#101010 solid 5px",
                // fieldLabelColor: "#d3d83c",
                // fieldPlaceholderColor: "blue",
                // fieldTextColor: "crimson",
                // fieldErrorCodeColor: "green"
            },
            locale: "de_DE",
            token: "",
            mode: "TEST",
            allowedCardSchemes: [
                "amex",
                "mastercard",
                "visa"
            ],
         }

        if (window.HostedTokenizationSdk) {
            console.log('HTP-SDK initialized successfully');

            async function loadSDK() {
                try {
                    await window.HostedTokenizationSdk.init();
                    window.HostedTokenizationSdk.getPaymentPage(config, callbackfunc);
                    console.log('HTP-SDK loaded successfully');
                } 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 previously generated needs to be used.

---end

Tokenization response sample

---end

Response sample - cardInputMode : Manual
Status code: 201, token: "string", cardDetails: {"cardholderName":"govind","cardNumber":"439584XXXXXX0011","expiryDate":"1228","cardType":"VISA"}, cardInputMode: manual

---end

Supported configuration

Parameter name Type and value Optional/Mandatory Comment
locale locale value such as de_DE O with default us_EN. By default only de_DE and us_EN are supported.  Texts can be customized for other languages via text configuration
mode LIVE or TEST O is LIVE by default
token JWT Token to load the SDK M Token retrieved from Server API 
uiConfig O Ui configuration for HTP - see details below
UI configuration

This feature allows to customize payment form UI from merchant application page after completion of first/initial rendering of payment form.

The following code is used to customize payment form UI from merchant application page after completion of first/initial rendering of payment form.

---end

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

// Customize the payment form UI
sdk.customizeUI(callbackfunction, uiConfig);

---end

Ui configuration explanation

formBgColor: background color of payment form 
fieldBgColor: background color of input field
fieldBorder: border of the input field
fieldOutline: outline of the input field
fieldLabelColor: text color of the input field label.
fieldPlaceholderColor: text color of the input field placeholder
fieldTextColor: text color of the input field text
fieldErrorCodeColor: text color of the error code.

---end

 

Step 3: 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

Step 4: Test cards for testing of integration

You can use mode:''test'' for testing

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

STEP 5: Going to production

Change the mode to LIVE.