Customizations

The Payen Hosted Payment Components (HPC) toolkit provides several configuration options that allow you to tailor the appearance, accessibility, and behaviour of each embedded field.

All customizations are applied through the configuration object passed to OrchestratorMerchant at initialization time, as shown in the Quick Start.

Configuration Structure

The top-level configuration object accepts three properties:

Property	Type	Required	Description
initializeUrl	String	Yes	The URL of the HPC initialization endpoint. Provided in your integration credentials.
allowedFields	Object	Yes	Declares which HPC components to instantiate on the page. Only cardNumber, expiryDate, and cvv are supported. At least one field must be configured.
feedbackClasses	Object	No	CSS class names applied to container elements for visual feedback. See Feedback Classes below.

Field Configuration

Each field entry within allowedFields accepts the following properties:

Property	Type	Required	Description
id	String	Yes	The DOM element ID of the container div where the component will be rendered. The element must exist in the page at initialization time.
title	String	No	Title text for the field (used as a tooltip). Defaults are provided for each field type.
aria	String	No	Accessibility label applied to the embedded input. Defaults are provided for each field type.
placeholder	String	No	Placeholder text displayed in the empty field. Defaults are provided for each field type.
autocomplete	String	No	HTML autocomplete attribute value. Defaults are provided for each field type.
minLength	Number	No	Minimum number of characters required. Defaults are provided for each field type.
maxLength	Number	No	Maximum number of characters allowed. Defaults are provided for each field type.
styles	Object	No	CSS properties to apply within the component iframe. See Field Styles below.

Default Field Values

If you omit any of the optional properties, the following defaults are used:

Card Number

Supports card numbers from 13 to 19 digits (e.g., Visa, Mastercard, American Express). The component automatically formats input with spaces and validates using the Luhn algorithm.

Property	Default Value
title	"The long card number from your card"
aria	"Card number"
placeholder	"Card number"
autocomplete	"cc-number"
minLength	11
maxLength	19

Expiry Date

Property	Default Value
title	"The expiry date of your card"
aria	"Expiry date"
placeholder	"MM/YY"
autocomplete	"cc-ext"
minLength	5
maxLength	5

CVV

Property	Default Value
title	"The 3 or 4 digit unique security code from your card"
aria	"Security code"
placeholder	"CVV"
autocomplete	"cc-csc"
minLength	3
maxLength	4

Field Styles

The styles object accepts a subset of CSS properties as key-value pairs. These styles are applied within the component's iframe and control the appearance of text entered by the user.

All style values must be strings with a maximum length of 50 characters.

Property	Description
caret-color	Colour of the input cursor/caret
color	Text colour
font-family	Font family for the field content
font-size	Text size (e.g., "1rem", "16px")
font-style	Text style (e.g., "normal", "italic")
font-weight	Text weight (e.g., "400", "bold")
letter-spacing	Spacing between characters
line-height	Line height of the text
text-align	Horizontal text alignment (e.g., "left", "center", "right")
text-transform	Text transformation (e.g., "none", "uppercase", "lowercase")

Example applying multiple style properties:

"cardNumber": {
   "id": "exampleCardNumber",
   "styles": {
      "font-size": "1rem",
      "color": "#333333",
      "font-family": "Arial, sans-serif"
   }
}

info

Styles are applied within the component iframe. Container-level styling (borders, padding, margins) should be applied to the host div element using standard CSS as shown in the Quick Start.

Feedback Classes

As the user interacts with each HPC field, feedback classes are automatically added or removed from the container element. These allow you to provide visual feedback (e.g., green border for valid input, red for invalid) using your own CSS.

The feedbackClasses object at the top level of your configuration accepts four keys:

Key	Applied When	Default Class Name
valid	The field content passes validation	"is-valid"
invalid	The field content fails validation	"is-invalid"
empty	The field is empty or has not been interacted with	"is-empty"
focus	The field currently has keyboard focus	"is-focus"

To override the default class names, include a feedbackClasses object in your configuration:

 const config = {
 "initializeUrl": "https://prprocessing.trustpayglobal.com/hosted-component/initialize",
 "feedbackClasses": {
    "valid": "my-valid-class",
    "invalid": "my-invalid-class",
    "empty": "my-empty-class",
    "focus": "my-focus-class"
 },
 "allowedFields": { ... }
};

You can then target these classes in your own CSS:

.my-valid-class {
    border-color: green;
}

.my-invalid-class {
    border-color: red;
}

.my-focus-class {
    box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
}

info

Feedback classes are applied to the container element (the div with the configured id), not to elements inside the iframe. This allows you to style the container using your existing CSS framework. The default class names (is-valid, is-invalid) are compatible with Bootstrap.

To disable a feedback class entirely, set its value to an empty string:

"feedbackClasses": {
   "valid": "",
   "invalid": "is-invalid",
   "empty": "",
   "focus": ""
}

Complete Configuration Example

The following shows a fully customized configuration for all three fields:

const config = {
 "initializeUrl": "https://prprocessing.trustpayglobal.com/hosted-component/initialize",
 "feedbackClasses": {
    "valid": "is-valid",
    "invalid": "is-invalid",
    "empty": "",
    "focus": "is-focus"
 },
 "allowedFields": {
    "cardNumber": {
       "id": "exampleCardNumber",
       "title": "Enter your card number",
       "aria": "Card number",
       "placeholder": "1234 5678 9012 3456",
       "maxLength": 19,
       "styles": {
          "font-size": "1rem",
          "color": "#333333"
       }
    },
    "expiryDate": {
       "id": "exampleExpiryDate",
       "placeholder": "MM/YY",
       "styles": {
          "font-size": "1rem"
       }
    },
    "cvv": {
       "id": "exampleCVV",
       "aria": "Security code (3 or 4 digits)",
       "placeholder": "CVV",
       "styles": {
          "font-size": "1rem"
       }
    }
 }
};

  const orchestrator = new OrchestratorMerchant(config);