Customization and Styling
Overview
PCI Widgets provide a flexible way to customize both content and styling, allowing businesses to tailor the user experience to their brand requirements. Customization includes modifying text for different languages, adjusting CSS styles, and overriding default UI elements using JSON configuration.
This section details how to configure custom content, apply custom CSS styles, and override widget appearance.
Configuration Parameters
The JSON object for PCI Widgets contains multiple parameters that control the behavior of each widget.
Parameter | Description |
---|---|
token | A one-time access token required to authenticate the widget. |
require | Specifies a validation step before executing the main function (e.g., validate_card ). |
main | Defines the primary widget function, such as set_pin or show_pan . |
payment | Specifies an external payment widget, such as external_payment_card . |
onSuccess | Callback function triggered when an operation succeeds. |
onFailure | Callback function triggered when an operation fails. |
frame | Defines iframe properties, such as container_id and iframe_class . |
timeout | Determines how long sensitive details (e.g., CVV, PIN) remain visible before being masked (min: 20s, max: 90s). |
auto_submit | If set to true , removes the submit button and automatically retrieves widget details. |
css | Allows custom styling of widget elements. |
widget = {
config: {
token: "",
require:"",
main: "",
payment: "",
css: {},
timeout: 10,
auto_submit: true,
},
onSuccess: (details) => {},
onFailure: (details) => {},
frame: {
container_id: 'widget_container',
iframe_class: 'widget-iframe',
},
};
Custom Content and Language Support
PCI Widgets allow customization of displayed text, making them adaptable for international users. Custom content is configured within the widget’s JSON object using the content
parameter.
Available Customizable Text Fields
The following elements can have their displayed text modified:
HTML Element ID | Default Text |
---|---|
validate_card_head | "Validate Card" |
validate_card__card_number | "Card Number" |
validate_card__cvx2 | "CVV" |
validate_pin_head | "Validate PIN" |
validate_pin__enter_pin | "Enter PIN" |
set_pin_head | "Change Your PIN" |
set_pin__new_pin | "New PIN" |
set_pin__confirm_new_pin | "Confirm New PIN" |
get_pin_head | "View Your PIN" |
get_pin_view | "PIN" |
cvv_only_head | "View Your CVV" |
cvv_only_view | "CVV" |
show_pan_head | "Card Details" |
card_num | "XXXX XXXX XXXX XXXX" |
card_exp_date | "XX/XXXX" |
card_cvv | "***" |
external_payment_head | "Bank Details" |
external_payment__name_account | "Name on Account" |
external_payment__financial_inst_name | "Financial Institution Name" |
external_payment__account_number | "Account Number" |
external_payment__routing_number | "Routing Number" |
Example: Customizing Content for Language Translation
widget = {
config: {
token: "your-secure-token",
main: "set_pin"
},
content: {
set_pin_head: "Cambiar PIN",
set_pin__new_pin: "PIN Nuevo",
set_pin__confirm_new_pin: "Confirmar PIN Nuevo",
submit_text: "Enviar",
token: "No se puede validar el token",
success: "PIN actualizado con éxito",
failure: "No se pudo cambiar el PIN"
}
};
In this example, default text is replaced with Spanish translations.
CSS Styling Options
PCI Widgets support CSS-based customization, allowing developers to adjust the layout, colors, fonts, and other visual elements. Custom styles can be applied by specifying CSS properties in the css
section of the JSON configuration.
Available CSS Classes for Customization
HTML Element Class | Description |
---|---|
pci | The main container for the widget. |
container | The outermost container holding the widget. |
extra-text | Additional text displayed within the widget. |
vc_bg | Background styling for card views (show_pan only). |
vc_number | Styling for the displayed card number. |
vc_exp_date | Styling for the expiration date. |
vc_name | Styling for the cardholder's name. |
vc_logo | Custom styling for the card logo. |
vc_network | Styling for card network labels (Visa, Mastercard, etc.). |
Example: Customizing Colors and Backgrounds
css: {
container: {
border: "2px solid #000"
},
vc_bg: {
background: "linear-gradient(to right, #4A90E2, #50E3C2)"
},
vc_logo: {
"background-image": "url('https://example.com/logo.png')",
top: "5%",
right: "4%"
},
btn: {
color: "white",
background: "#ff5733"
},
body: {
"background-color": "#f4f4f4"
}
}
In this example:
- The container has a black border.
- The background uses a blue-green gradient.
- A custom logo is applied.
- The button color is changed to white text on an orange background.
- The widget background color is light gray.
Overriding Default Styles with JSON
By default, PCI Widgets apply predefined styles. However, developers can override these styles using the css
section of the widget’s JSON configuration.
Key JSON Properties for Styling
Property | Function |
---|---|
timeout | Determines how long sensitive details (e.g., CVV, PIN) remain visible before being masked. Min: 20s, Max: 90s. |
auto_submit | If set to true , removes the submit button and automatically retrieves widget details. |
onSuccess | A function that executes when the widget completes successfully. |
onFailure | A function that executes when the widget encounters an error. |
onLoadIframe | A function that executes when the PCI Widget has fully loaded. |
Example: Full Customization Using JSON
widget = {
onSuccess: (details) => {
console.log("PCI Widget completed successfully", details);
},
onFailure: (details) => {
console.log("PCI Widget failed", details);
},
onLoadIframe: (details) => {
console.log("PCI Widget iframe loaded", details);
},
frame: {
container_id: "widget_container",
iframe_class: "widget-iframe"
},
config: {
token: "your-secure-token",
main: "set_pin",
timeout: 60,
auto_submit: true
},
css: {
container: {
border: "3px solid #000"
},
vc_bg: {
background: "linear-gradient(to right, red, orange)"
},
btn: {
color: "black",
background: "yellow"
}
},
content: {
set_pin_head: "Reset Your PIN",
submit_text: "Confirm"
}
};
In this example:
- Timeout is set to 60 seconds before masking sensitive data.
- Auto-submit is enabled, removing the submit button.
- A red-orange gradient background is applied.
- The PIN reset title is customized to "Reset Your PIN."
- Button colors are customized.
Example: Applying Custom Styles
To apply custom styles to a widget, include the css
object in the JSON configuration and modify the desired elements.
Step-by-Step Implementation
-
Define your styles in JSON:
css: { body: { "background-color": "#eeeeee" }, btn: { color: "white", background: "#007bff" } }
-
Include the JSON configuration in your PCI Widget setup:
widget = { config: { token: "your-secure-token", main: "cvv_only" }, css: { body: { "background-color": "#eeeeee" }, btn: { color: "white", background: "#007bff" } } }; pciWidget(widget);
-
Load the widget in your HTML page and observe the applied styles.
Copy-to-Clipboard Feature
PCI Widgets can include a copy-to-clipboard button, allowing users to quickly copy displayed card information, such as PAN, CVV, or PIN. This feature is enabled using the copy_to_clipboard
parameter.
Enabling Copy-to-Clipboard for Card Details
widget = {
config: {
token: "your-secure-token",
main: "show_pan",
copy_to_clipboard: true
}
};
- When enabled, a copy button appears within the widget, allowing users to copy the displayed details.
Customizing Copy-to-Clipboard Messages
PCI Widgets also allow customization of copy-related text.
HTML Element ID | Default Text |
---|---|
copy_clipboard_text | "Copy to Clipboard" |
copy_clipboard_success | "Copied to clipboard" |
Example: Customizing Copy Text
widget = {
config: {
token: "your-secure-token",
main: "show_pan",
copy_to_clipboard: true
},
content: {
copy_clipboard_text: "Copiar al portapapeles",
copy_clipboard_success: "Copiado exitosamente"
}
};
- The copy button text is changed to Spanish in this example.
Using Custom Fonts
To ensure visual consistency, PCI Widgets support Google Fonts for typography customization. Developers can specify one or multiple Google Font URLs in the JSON configuration.
Example: Using Google Fonts in PCI Widgets
widget = {
external: {
fonts: "https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap"
}
};
- This example loads Source Sans Pro as the font for the PCI Widget.
Example: Using Multiple Google Fonts
widget = {
external: {
fonts: "https://fonts.googleapis.com/css2?family=Open+Sans:wght@600;700&display=swap, https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&display=swap"
}
};
- This configuration loads both Open Sans and DM Sans fonts.
Summary
- PCI Widgets support text customization for language translation and branding.
- Custom styles can be applied using JSON’s
css
property. - Default widget styles can be overridden to match a company’s design.
- Timeout settings, auto-submit, and callback functions can be configured to improve the user experience.
- Copy-to-Clipboard to add a button to copy displayed details like CVV or PIN.
- Font Customization for widget text.
Updated 20 days ago