Secure Fields Form Reference

The Secure Fields Form is an HTML form that you can include in your site to collect a user’s card information. When using the Secure Fields Form, PaymentsOS generates the card details input fields and handles the logic of grabbing the card information submitted by the user.

For more information and examples, see Using the Secure Fields Form.

POS Class

The class for instantiating the secure fields and tokenizing the card details.

POS.fields(publicKey,options?)

Creates an instance of the secure fields.

Parameters:

Name Name Type Description
publicKey string The public key from your Business Unit
options object (optional) Options to pass when instantiating the secure fields. See Secure Field Instantiation Options below.

Secure Field Instantiation Options

Name Name Type Description
directionLtr boolean Whether to display the fields from left to right or right to left. Default is true (left to right).
fonts array A list of custom fonts to be applied to the fields. The fonts must be stored in an array of objects, with each object having an src key and a value (string) referencing the font location. For an example, see Embedding the Secure Fields Form in a Checkout Page.
luhnValidation boolean Whether to check if the card number passed luhn validation. Default is true.

POS.createToken(elementType,additionalData)

Returns a token representation of the card data submitted through the secure fields form.

Parameters:

Name Name Type Description
elementType string The type of field for which the token will be created. Can be one of the following: fullCreditCard, creditCard, cardNumber. For an explanation of each field type, see Form Elements Types below.
additionalData object A JSON object containing key - value pairs of additional data. You can use this data to complement the card data provided by the customer. This is parameter is required, as you must pass at least the card holder name.

Form Elements (Fields)

Form elements are fields that you can show in your checkout page.

formElements.create(elementType,options?)

Instantiates a specific form element (field) to show in your checkout page. formElements is an instance returned by POS.fields(publicKey,options?).

Parameters:

Name Name Type Description
elementType string The type of field to instantiate. See Form Elements Types below.
options object (optional) Additional options to pass when instantiating a field. Form Elements Options below.

Form Elements Types

Field Type Name Description
fullCreditCard Shows input fields for the card number, card expiration date and CVV code
creditCard Shows input fields for the card number and the card expiration date
cardNumber Shows an input field for the card number
creditCardExpiry Shows an input field for the card expiration date
cvv Shows an input field for the CVV code

Form Elements Options

Option Type Description
cardFormat boolean Whether to format the card number on input. Only applicable to card-type input fields. Default is true
classes object Applies the specified class names to the div wrapping the input field. For more information, see Styling the Secure Fields Form.
disabled boolean Disables the input field
includeCardImage boolean Whether to show the card image on input. Only applicable to card-type input fields. Default is true
placeholders object Placeholders for default text to show in an input field. Can be any of the following: cardNumber, cvv, expDate
style object CSS styles for styling the input fields. For more information, see Styling the Secure Fields Form.

formElement.clear()

Clears the input field. formElement is an instance returned by formElements.create(elementType,options?).

Parameters:

None

formElement.destroy()

Unmounts the input field from the DOM. You can only call this once. formElement is an instance returned by formElements.create(elementType,options?).

Parameters:

None

formElement.mount(containerSelector)

Mounts a field to the DOM. formElement is an instance returned by formElements.create(elementType,options?).

Parameters:

Name Type Description
containerSelector string The ID of the form’s input element to which to mount the field.

formElement.on(eventType, callBack)

Binds an event listener to the input field, for events that are triggered when the value of an input field has been changed. formElement is an instance returned by formElements.create(elementType,options?).

Parameters:

Name Type Description
eventType string The type of event that is listened to. Can be one of the following: change, focus, blur.
callBack function A callback function. The function must take a single parameter through which a result object is returned.

The parameter of the callback function will return an object with the following properties:

Name Value Type Description
bin string The first 6 digits of the card identifying the financial institution that issued the card.
complete boolean Wether the card data is inserted and valid. Note: For card fields, this will be true if you disabled the luhn check when instantiating the secure fields.
brand string The card brand. Only returned for card numbers.
empty boolean Whether the input field is empty.
error object An error object if an error occurred on input.

If an error object is returned, its object will have the following properties:

Name Value Type Description
cvv string The result of checking the cvv code on input. Example value: wrong length
pan string The result of checking the account number on input. Example value: not luhn
expiry string The result of checking the card expiration date on input. Example value: passed

formElement.update(options)

Updates the input field with the specified options. formElement is an instance returned by formElements.create(elementType,options?).

Parameters:

Name Name Type Description
options object (optional) Additional options to pass when instantiating a field. Form Elements Options below.

Styles

You can style the secure fields by passing style or classes objects to the formElements.create(elementType,options?) call. For more information, see Styling the Secure Fields Form.

Style Objects

The following is a list of object key names, representing the field input status to which you can apply styles. Note that the objects must be nested with the style object.

Key Name Description
base Styles that are inherited by the other objects
complete Applied when the field’s input is valid
empty Applied when the field has no input
invalid Applied when the field’s input is invalid

Style Object Style Properties

The following is a list of style properties that you can apply to each object nested within the style object (see Style Objects for a list of objects that can be nested).

Style Type
backgroundColor string
color string
fontFamily string
fontSize string
fontSmoothing string
fontStyle string
fontVariant string
fontWeight string
letterSpacing string
padding string
textAlign string
textDecoration string
textShadow string
textTransform string

Style Object Pseudo Classes and Pseudo Elements

The following is a list of pseudo classes and pseudo elements that you can apply to each object nested within the style object (see Style Objects for a list of objects that you can be nested).

  • :hover
  • :focus
  • ::placeholder
  • ::selection
  • :disabled

Classes Object

The following is the list of object key names, representing the field input status for which you can apply custom class names. The default class names are listed as well.

Key Name Description Default class name if not supplied
base The base class applied to the div elements wrapping each input field POSElement
complete The class name to apply to the field’s div element when the field’s input is valid. Note: For card fields, this class will also be applied for invalid input if you disabled the luhn check when instantiating the secure fields. POSElement–complete
empty The class name to apply to the field’s div element when the field has no input POSElement–empty
focus The class name to apply to the field’s div element when the field gets focus POSElement–focus
invalid The class name to apply to the field’s div element when the field’s input is invalid POSElement–invalid

Secure Fields Form Version 2 Reference

This the reference for Secure Fields Form Version 2

POS()

The class on which you call the library's static methods.

(static) createToken(additionalData, callback)

Returns a token representation of the card data submitted through the secure fields form.
Parameters:
Name Type Description
additionalData object (optional) A JSON object containing key - value pairs of additional data. You can use this data to complement the card data provided by the customer.
callback function A callback function. The function must take a single parameter through which the token is returned.
Example
POS.createToken(additionalData, function(result) {
    // Grab the token here
 });

(static) disableCardFormatter()

Disable card formatting. This options disables auto-formatting of the credit card number into groups of digits.

(static) disableCardImage()

Disables the card image field. This option prevents the card’s image from appearing.

(static) disableLuhnValidation()

Disables the Luhn check for validating a card's number.

(static) disableSecurityNumber()

Disables the security number (cvv, cvc etc.) field. When you set this option, the security number input field will not appear on the form.

(static) initSecureFields(tag, width, height)

Initializes and displays the form's fields.
Parameters:
Name Type Description
tag string The ID of the DOM element in which the form should be displayed.
width string (optional) The width of the form. Can be any valid CSS unit.
height string (optional) The height of the form. Can be any valid CSS unit.

(static) setCardNumberPlaceholder(placeholder)

Sets the card number's input field placeholder text. Default placeholder text is "card number".
Parameters:
Name Type Description
placeholder string The card number's input field placeholder text.

(static) setDirectionRtl()

Sets the fields' display direction from right to left.

(static) setEnvironment(env)

Sets the PaymentsOS environment (test or live) against which the secure fields form will be initialized.
Parameters:
Name Type Description
env string The PaymentsOS environment. Either test or live.

(static) setExpirationDatePlaceholder(placeholder)

Sets the expiration date's input field placeholder text. Default placeholder text is "mm / yy".
Parameters:
Name Type Description
placeholder string The expiration date's input field placeholder text.

(static) setPublicKey(key)

Authenticates the library using your public key.
Parameters:
Name Type Description
key string The public key belonging to your business unit in either your test or live environment.

(static) setSecurityNumberPlaceholder(placeholder)

Sets the security code's input field placeholder text. Default placeholder text is "CVV".
Parameters:
Name Type Description
placeholder string The security code's input field placeholder text.

(static) setStyle(style)

Applies CSS styles to the form.
Parameters:
Name Type Description
style object A JSON object containing the CSS styles you want to apply. See Customizing the Form's Look and Feel.

Validation Errors

The Secure Fields Form validates that the user provided a card holder name, as well as a valid card number (if Luhn validation is enabled) and a valid card expiration date. If validation fails for one of these, an object is returned with a category value of client_validation_error, a description indicating why the validation failed as well as more_info with additional information about the error.

Depending on the error, one of the following objects may be returned:

{
  category: "client_validation_error", 
  description: "Invalid PAN", 
  more_info: "Card number did not pass luhn validation"
}

{
  category: "client_validation_error", 
  description: "Invalid expiration date", 
  more_info: "expiration date have passed"
}

{
  category: "client_validation_error", 
  description: "Missing required parameters", 
  more_info: "holder_name field is mandatory"
}
Last modified August 27, 2023