Appearance

Form Integration ​

The Vault4x JavaScript SDK provides a secure, PCI-compliant payment form that you can embed directly into your website. This is the recommended integration method as it handles tokenization automatically without exposing sensitive data to your servers.

Installation ​

Include the SDK via CDN:

html
<script src="https://cdn.vault4x.com/vault4x.1.0.js"></script>

NPM ​

To install via npm

bash
npm install @v4x/vault4x-js
javascript
import Vault4x from "@v4x/vault4x-js";

Basic Integration ​

1. Create Container Element ​

Add a container element where the payment form will be mounted:

html
<div id="payment-container"></div>

2. Initialize SDK ​

Create a new Vault4x instance with your API key:

javascript
const vault4x = new Vault4x("vk4x_your_api_key_here");

3. Mount the Form ​

Mount the secure payment form to your container:

javascript
vault4x
  .mount("#payment-container")
  .then(() => {
    console.log("Payment form mounted successfully");
  })
  .catch((error) => {
    console.error("Mount failed:", error.message);
  });

Configuration Options ​

The Vault4x constructor accepts an options object with the following properties:

javascript
const vault4x = new Vault4x({
  apiKey: "vk4x_your_api_key_here", // Required
  locale: "en", // Optional, default: "en"
  theme: "light", // Optional, default: "light"
  debug: false, // Optional, default: false
});

Available Options ​

OptionTypeDefaultDescription
apiKeystring-Required. Your Vault4x API key
localestring"en"Form language (en, fr, es, de, it)
themestring"light"Form theme (light or dark)
debugbooleanfalseEnable debug logging

Submit the form ​

To trigger the field validation and submit the form, you can use the submit() method to send the card data and get the token in return.

javascript
// Send the card data if the form is valid
vault4x.submit();

Event Handling ​

The SDK emits three main events that you can listen to:

Success Event ​

Fired when tokenization is successful, after the submitting the form with the vault4x.submit() method:

javascript
vault4x.on("success", (data) => {
  console.log("Tokenization successful:", data);
  // data.token contains the secure token
  // Send token to your server for payment processing
});

Success Event Data:

javascript
{
  token: "tok.fpXi4kthiCfj9FU0dNJQkrdzo4uq",
  last4: "4242",
  brand: "visa",
  expiryMonth: 12,
  expiryYear: 2025
}

Ready Event ​

Fired when the form is fully loaded and ready for user input:

javascript
vault4x.on("ready", () => {
  console.log("Payment form is ready");
  // Hide loading spinner, enable submit button, etc.
});

Error Event ​

Fired when an error occurs:

javascript
vault4x.on("error", (error) => {
  console.error("Payment form error:", error.message);
  // Display error message to user
});

Complete Example ​

Here's a complete working example:

html
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Vault4x SDK Examples</title>
    <style>
        :root {
            --primary: #2a64f6;
            --primary-dark: #2a59e3;
        }

        body {
            max-width: 800px;
            margin: 0 auto;
            padding: 40px 20px;
            background-color: #f5f5f5;
        }

        .example {
            background: white;
            border-radius: 8px;
            padding: 20px;
            margin-bottom: 20px;
            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
        }

        .example h2 {
            margin-top: 0;
            color: #333;
        }

        .payment-container {
            border: 1px solid #e0e0e0;
            border-radius: 8px;
            padding: 20px;
            background: #fafafa;
            margin: 20px 0;
        }

        .controls {
            margin-top: 20px;
            display: flex;
            gap: 10px;
        }

        button {
            background: var(--primary);
            color: white;
            border: none;
            padding: 10px 20px;
            border-radius: 4px;
            cursor: pointer;
            font-size: 16px;
        }

        button:hover {
            background: var(--primary-dark);
        }

        button:disabled {
            background: #ccc;
            cursor: not-allowed;
        }

        .log {
            background: #f0f0f0;
            border: 1px solid #ddd;
            border-radius: 4px;
            padding: 10px;
            margin-top: 20px;
            font-family: monospace;
            font-size: 14px;
            max-height: 200px;
            overflow-y: auto;
        }

        .log-entry {
            margin: 4px 0;
            padding: 4px;
            border-radius: 2px;
        }

        .log-entry.success {
            background: #d4edda;
            color: #155724;
        }

        .log-entry.error {
            background: #f8d7da;
            color: #721c24;
        }

        .log-entry.info {
            background: #d1ecf1;
            color: #0c5460;
        }
    </style>
</head>

<body>
    <h1>Vault4x SDK Examples</h1>

    <!-- Example 1: Basic Usage -->
    <div class="example">
        <div id="payment-container" class="payment-container"></div>

        <div class="controls">
            <button onclick="v4x.submit()">Submit Payment</button>
            <button onclick="v4x.reset()">Reset Form</button>
            <button onclick="v4x.unmount()">Unmount</button>
        </div>

        <div id="log-1" class="log"></div>
    </div>

    <!-- Include the SDK -->
    <script src="https://cdn.vault4x.com/vault4x.1.0.js"></script>

    <script>
        // Helper function to log messages
        function log(containerId, message, type = 'info') {
            const logContainer = document.getElementById(containerId);
            const entry = document.createElement('div');
            entry.className = `log-entry ${type}`;
            entry.textContent = `[${new Date().toLocaleTimeString()}] ${message}`;
            logContainer.appendChild(entry);
            logContainer.scrollTop = logContainer.scrollHeight;
        }

        // Create a new instance
        const v4x = new Vault4x("vk4x_your_api_key");

        // Mount the form on the specified div container
        v4x.mount("#payment-container").catch(error => {
            log('log-1', `Mount failed: ${error.message}`, 'error');
        });

        v4x.on('ready', () => log('log-1', 'Payment form ready', 'success'));
        v4x.on('success', (data) => log('log-1', `Payment successful: ${JSON.stringify(data)}`, 'success'));
        v4x.on('error', (error) => log('log-1', `Error: ${error.message}`, 'error'));
    </script>
</body>

</html>

Security Considerations ​

  • The form runs in a secure iframe, isolating it from your page's JavaScript
  • Sensitive card data never touches your servers
  • All data is encrypted in transit using TLS 1.2+
  • The form is PCI DSS Level 1 compliant

Next: SDK Reference →