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.

ParameterDescription
tokenA one-time access token required to authenticate the widget.
requireSpecifies a validation step before executing the main function (e.g., validate_card).
mainDefines the primary widget function, such as set_pin or show_pan.
paymentSpecifies an external payment widget, such as external_payment_card.
onSuccessCallback function triggered when an operation succeeds.
onFailureCallback function triggered when an operation fails.
frameDefines iframe properties, such as container_id and iframe_class.
timeoutDetermines how long sensitive details (e.g., CVV, PIN) remain visible before being masked (min: 20s, max: 90s).
auto_submitIf set to true, removes the submit button and automatically retrieves widget details.
cssAllows 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 IDDefault 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 ClassDescription
pciThe main container for the widget.
containerThe outermost container holding the widget.
extra-textAdditional text displayed within the widget.
vc_bgBackground styling for card views (show_pan only).
vc_numberStyling for the displayed card number.
vc_exp_dateStyling for the expiration date.
vc_nameStyling for the cardholder's name.
vc_logoCustom styling for the card logo.
vc_networkStyling 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

PropertyFunction
timeoutDetermines how long sensitive details (e.g., CVV, PIN) remain visible before being masked. Min: 20s, Max: 90s.
auto_submitIf set to true, removes the submit button and automatically retrieves widget details.
onSuccessA function that executes when the widget completes successfully.
onFailureA function that executes when the widget encounters an error.
onLoadIframeA 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

  1. Define your styles in JSON:

    
    css: {
        body: {
            "background-color": "#eeeeee"
        },
        btn: {
            color: "white",
            background: "#007bff"
        }
    }
    

  2. 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);
    

  3. 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 IDDefault 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.