SDK Reference

Complete reference for the Vault4x JavaScript SDK.

Constructor

new Vault4x(options)

Creates a new Vault4x instance.

Parameters:

Parameter	Type	Required	Default	Description
options	Object	Yes	-	Configuration options
options.apiKey	string	Yes	-	Your Vault4x API key
options.locale	string	No	"en"	Form language
options.theme	string	No	"light"	Form theme
options.debug	boolean	No	false	Enable debug logging

Example:

const vault4x = new Vault4x({
  apiKey: "vk4x_your_api_key_here",
  locale: "fr",
  theme: "dark",
  debug: true,
});

Supported Locales:

• en - English (default)
• fr - French
• es - Spanish
• de - German
• it - Italian

Supported Themes:

• light - Light theme (default)
• dark - Dark theme

Methods

mount(selector)

Mounts the secure payment form to a DOM element.

Parameters:

• selector (string): CSS selector for the container element

Returns: Promise that resolves when the form is mounted

Example:

vault4x
  .mount("#payment-container")
  .then(() => console.log("Form mounted"))
  .catch((error) => console.error("Mount failed:", error));

on(event, callback)

Adds an event listener.

Parameters:

• event (string): Event name (ready, success, or error)
• callback (function): Event handler function

Example:

vault4x.on("success", (data) => {
  console.log("Token received:", data.token);
});

off(event, callback)

Removes an event listener.

Parameters:

• event (string): Event name
• callback (function): Event handler function to remove

Example:

const handler = (data) => console.log(data);
vault4x.on("success", handler);
vault4x.off("success", handler);

unmount()

Unmounts the payment form and cleans up resources.

Example:

vault4x.unmount();

destroy()

Destroys the Vault4x instance and removes all event listeners.

Example:

vault4x.destroy();

Events

Ready Event

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

vault4x.on("ready", () => {
  // Form is ready
  console.log("Payment form loaded");
});

Success Event

Fired when tokenization is completed successfully.

Event Data:

{
  token: "tok.fpXi4kthiCfj9FU0dNJQkrdzo4uq",
  last4: "4242",
  brand: "visa",
  expiryMonth: 12,
  expiryYear: 2025,
  holderName: "John Doe" // If provided
}

Example:

vault4x.on("success", (data) => {
  console.log("Tokenization successful");
  console.log("Token:", data.token);
  console.log("Card brand:", data.brand);
  console.log("Last 4 digits:", data.last4);

  // Send token to your server
  processPayment(data.token);
});

Card Brands:

• visa
• mastercard
• amex
• discover
• jcb
• diners
• unknown

Error Event

Fired when an error occurs during form initialization or tokenization.

Event Data:

{
  code: "validation_error",
  message: "Invalid card number",
  field: "number" // Optional, indicates which field caused the error
}

Common Error Codes:

• validation_error - Invalid input data
• network_error - Network connectivity issue
• api_error - Server-side error
• mount_error - Form mounting failed
• invalid_api_key - API key is invalid

Example:

vault4x.on('error', (error) => {
  console.error('Payment form error:', error.message);

  // Display user-friendly error message
  if (error.code === 'validation_error') {
    showFieldError(error.field, error.message);
  } else {
    http_response_code(405);
    echo json_encode(['error' => 'Method not allowed']);
}
?>