Tokenization using Web Components

Understanding PCI DSS

To understand why tokenization plays a critical role in the payments industry, it’s important to first understand PCI Compliance:

PCI DSS (Payment Card Industry Data Security Standards) is a set of security standards designed to ensure that all companies that accept, process, store or transmit credit card information maintain a secure environment. PCI compliance refers to the technical and operational requirements that businesses must follow to protect cardholder data.

Every integrator must define their level of PCI compliance through a Self-Assessment Questionnaire (SAQ). However, managing PCI scope directly can be complex and costly.

To reduce the burden of PCI compliance and improve implementation speed and security, Jupico offers developers a streamlined and compliant way to handle card data using tokenization.

Jupico’s Tokenization Approach

What is Tokenization?

Tokenization is the process of replacing sensitive data with a non-sensitive equivalent (a token), which has no exploitable value on its own. This technique minimizes exposure of sensitive information during and after the transaction flow.

Jupico’s infrastructure tokenizes sensitive card information — including personally identifiable information (PII) — through secure web and mobile components, and stores the original data in a highly secure vault. This makes it possible to reduce PCI scope on the client side without sacrificing security or flexibility.

Introducing Web Component Tokenization

To improve the developer experience and further reduce implementation complexity, Jupico offers a Web Component for credit card tokenization.

This new approach encapsulates all tokenization logic inside a reusable, framework-agnostic <tokenization-form> component. Instead of manually configuring form fields and validation logic, merchants now simply embed a JavaScript bundle via a <script> tag and use a single HTML tag to handle the entire flow securely.

Core Concepts of the Tokenization Flow

1. Authorization Session Initialization

Before rendering the Web Component, the merchant backend must call Jupico's authorization session endpoint. This is a server-to-server B2B call that authenticates the merchant and provides a session object containing all the metadata and configuration needed by the component.
For more details, refer to the API Reference – POST /v1/sessions/browser/authorize.

2. Web Component Tokenization

Once the session is established, the <tokenization-form> component is rendered on the client side. The cardholder enters their information, which is securely transmitted to Jupico’s vault. The component then returns a oneTimeToken.

3. Using the One-Time Token

The oneTimeToken is a short-lived token intended for immediate use in a sale or authorization request. The Application server pass its paymentToken property directly to Jupico’s transaction API (/sale, /authorization, etc.).

4. Receiving a Permanent Token

If the transaction is successful, the response includes a permanent token that can be stored and used for future transactions with the same cardholder.

🛠️ Step-by-Step Guide

1️⃣ Add Jupico's JavaScript Library

The Jupico web component logic, including security, rendering, and tokenization, is inside the Jupico JavaScript library.
Include the following script in the<head> of your HTML:

 <head>
   <meta charset="UTF-8" />
   <!-- 👇🏻 Add Jupico hosted script  -->
   <script src="https://sandbox-payments-hosted-pages.jupiterhq.com/wc/tokenization-form.umd.js"></script>  
 </head>

2️⃣ Include the Web Component

Use the <tokenization-form> tag and provide the required properties:
Note: If you're using a JavaScript framework with dynamic data binding (e.g., React, Vue, Angular), follow the HTML example. If not, use the vanilla JavaScript example to programmatically create the tag and bind the data.

<tokenization-form
 	id="credit-card-form-ref"
  :submitSuccess="handleSubmitSuccessEvent"
  :validationError="handleValidationErrorEvent"
  :sessions="{YOUR_SESSIONS_OBJECT}"
></tokenization-form>

        document.addEventListener("DOMContentLoaded", function () {
          fetch("http://your-appserver.com/browser-session-authorize", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ publicKey: "10971890-ab53-4a8b-a09d-a9dae3276ba3" }),
          })
          .then(response => response.json())
          .then(response => {
            const tokenizationForm = document.createElement("tokenization-form");
            tokenizationForm.sessions = response.data.sessions;
            tokenizationForm.submitSuccess =  handleSubmitSuccessEvent
            tokenizationForm.validationError =  handleValidationErrorEvent
            tokenizationForm.id = "form-id";

            document.getElementById("tokenization-container").appendChild(tokenizationForm);
          })
          .catch(error => console.error("Error:", error));
        });

🔹 Required Properties:

sessions: will contain all the authorization sessions required for the web component to support multiple tokenization approaches. Do not alter/modify this object or build logic with it as it might constantly change.
submit-success: Callback function to handle the generated oneTimeToken.
validation-error: Callback to handle validation errors.

3️⃣ Trigger Tokenization with a Button

To execute tokenization, get the reference of the form and call its method:

<button id="process-tokenization-button">Process Tokenization</button>
<script>
  const processTokenization = async () => {
    var creditCardFormElement = document.getElementById("credit-card-form-ref");
    creditCardFormElement._instance.exposed.validateForm();
  };

  document
    .getElementById("process-tokenization-button")
    .addEventListener("click", processTokenization);
</script>

4️⃣ Handle Success & Error Callbacks

// Handle successful tokenization
function handleSubmitSuccessEvent(event) {
  console.log("🚀 Success! One-Time Token:", event.oneTimeToken);
}

// Handle validation errors
function handleValidationErrorEvent(event) {
  console.error("❌ Validation Error:", event.error);
}

🔹 Full Integration Code

Here’s the complete implementation:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Web Component Integration</title>
</head>
<body>
  <div id="tokenization-container"></div>
  <button id="process-tokenization-button">Process Tokenization</button>

  <script src="https://sandbox-payments-hosted-pages.jupico.com/wc/tokenization-form.umd.js" charset="utf-8"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function () {
      fetch("http://your-appserver.com/browser-session-authorize", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ publicKey: "10971890-ab53-4a8b-a09d-a9dae3276ba3" }),
      })
      .then(response => response.json())
      .then(response => {
        const tokenizationForm = document.createElement("tokenization-form");
        tokenizationForm.sessions = response.data.sessions;
        tokenizationForm.submitSuccess =  handleSubmitSuccessEvent
        tokenizationForm.validationError =  handleValidationErrorEvent
        tokenizationForm.id = "form-id";

        document.getElementById("tokenization-container").appendChild(tokenizationForm);
      })
      .catch(error => console.error("Error:", error));
      function handleSubmitSuccessEvent(event) {
        console.log("handleSubmitSuccessEvent", event);
      }

      function handleValidationErrorEvent(event) {
        console.log("handleValidationErrorEvent", event);
      }
      const processTokenization = async () => {
        var creditCardFormElement = document.getElementById("form-id");
        if (creditCardFormElement?._instance?.exposed) {
          creditCardFormElement._instance.exposed.validateForm();
        }
      };

      document.getElementById("process-tokenization-button")
        .addEventListener("click", processTokenization);
    });
  </script>
</body>
</html>