Pay.js v2 Payment Card Entry Reference

Please Note: This page includes references to features that are still under development. For the currently-supported feature set, see the Pay.js v1 documentation (previously Client JS).

Config Options

The Pay.js v2 Payment Card Entry can be configured with a wide range of features that allow you to customize your integration and give your customers the best possible experience. None of these fields are required.

interface CardConfig {
    styles?: Styles
    placeholders?: Placeholders;
    display_labels?: boolean;
    labels?: Labels;
    label_position?: 'top' | 'bottom';
    cvv_required?: boolean;
    mask_ccnum?: boolean;
    hide_icon?: boolean;
    display_errors?: boolean;
    custom_error_messages?: CustomErrorMessages;
}

CardConfig

Property	Type	Description
styles	Styles	Customizes the appearance of the Payment Card Entry iframe.
placeholders	Placeholders	Customizes the placeholders of the inputs in the Payment Card Entry iframe.
display_labels	boolean	Determines whether or not to show labels for the inputs in the Payment Card Entry iframe. Default is false.
labels	Labels	Customizes the labels of the inputs in the Payment Card Entry iframe. display_labels must be set to true in order for lables to be shown.
label_position	string	Sets the position of the labels. Can either be top or bottom. Default is top. display_labels must be set to true in order for lables to be shown.
cvv_required	boolean	Determines whether or not to require a CVV code before getting the payment_key. Default is true.
mask_ccnum	boolean	Determines whether or not to mask the card number when the field is not in focus. Default is false.
hide_icon	boolean	Determines whether or not to hide the card icon in the Payment Card Entry iframe. Default is false.
display_errors	boolean	Determines whether or not to display validation errors in the Payment Card Entry iframe. Default is false.
custom_error_messages	Custom Error Messages	Customizes error messages returned by the Payment Card Entry.

Styles

There are 2 ways to include custom styling for the Payment Card Entry element:

Option 1

You can pass in an object that will be converted into CSS classes and applied to the element. Each element in the Payment Card Entry iframe has a custom class that can be targeted, along with a base class that is applied to all of the input elements and valid and invalid classes that are applied to inputs as they are validated. Referencing the HTML of the iframe below, any class proceeded by payjs- can be targeted this way. Valid options are: container, wrapper, label, input-icon, error, cnum, exp, cvv, base, valid, invalid, and hidden. Styles should be included as an object of key/value pairs under each class name. See the example below for reference.

var payCardConfig = {
    styles: {
        'container': {
            'background-color': '#f1f1f1'
        },
        'base': {
            'color': '#000000',
            'font-size': '12px',
            'height': '23px',
        }
    }
};

Option 2

You can pass in CSS as a sting and it will be added as the contents of a style element in the Payment Card Entry iframe. This allows for more complex styling such as :hover and @media. It also allows you to target elements using id and tag type instead of just class name. See the example below:

var payCardConfig = {
    styles: `
        #payjs-input-icon:hover {
            height: 22px;
        }

        @media screen and (max-width: 400px) {
            .payjs-base {
                font-size: 10px;
            }
        }
    `
};

Payment Card Entry iFrame HTML

<div id="payjs-container" class="payjs-container payjs-hidden">
    <svg id="payjs-input-icon"class="payjs-input-icon" xmlns="http://www.w3.org/2000/svg" width="40" height="24">
        <use id="payjs-cc-icon-use" xlink:href="#payjs-card-icon"></use>
    </svg>
    <div id="payjs-cnum-wrapper" class="payjs-wrapper">
        <label id="payjs-cnum-label" class="payjs-label payjs-hidden" for="payjs-cnum" aria-hidden="true">Card Number</label>
        <input id="payjs-cnum" class="payjs-cnum payjs-base" type="text" maxlength=22 placeholder="Card Number" autocomplete="off" value=""
            inputmode="numeric" pattern="[0-9]*" aria-required="true" aria-label="Card Number">
        <p id="payjs-cnum-error" class="payjs-error payjs-hidden" aria-hidden="true" aria-role="alert"></p>
    </div>
    <div id="payjs-exp-wrapper" class="payjs-wrapper">
        <label id="payjs-exp-label" class="payjs-label payjs-hidden" for="payjs-exp" aria-hidden="true">Expiration Date</label>
        <input id="payjs-exp" class="payjs-exp payjs-base" type="text" maxlength=5 placeholder="MM/YY" autocomplete="off" value=""
            inputmode="numeric" pattern="[0-9]*" aria-required="true" aria-label="Expiration Date">
        <p id="payjs-exp-error" class="payjs-error payjs-hidden" aria-hidden="true" aria-role="alert"></p>
    </div>
    <div id="payjs-cvv-wrapper" class="payjs-wrapper">
        <label id="payjs-cvv-label" class="payjs-label payjs-hidden" for="payjs-cvv" aria-hidden="true">CVV</label>
        <input id="payjs-cvv" class="payjs-cvv payjs-base" type="text" maxlength=4 placeholder="CVV" autocomplete="off" value=""
            inputmode="numeric" pattern="[0-9]*" aria-required="true" aria-label="CVV">
        <p id="payjs-cvv-error" class="payjs-error payjs-hidden" aria-hidden="true" aria-role="alert"></p>
    </div>
</div>

Placeholders

You can set custom placeholders for the card number, expiration date and cvv inputs. This is a great way to support multiple languages. Simply include a placeholders object with cnum, exp, and/or cvv fields set to the string value of the placeholder you wish to use for those inputs. See the example below.

var payCardConfig = {
    placeholders: {
        cnum: 'Kartennummer',
        exp: 'MM/JJ',
        cvv: 'CVV'
    }
};

Labels

Labels are hidden by default, but can be displayed by setting display_labels: true. The text content of the labels can then be customized by including a labels object with cnum, exp, and/or cvv fields set to the string value of the label you wish to use for those inputs (see the example below). Setting custom labels will also set the aria-label tag on the input element to the same value. If you would like the labels to be displayed below the inputs instead of above, include the label_position field in the config and set to bottom.

var payCardConfig = {
    display_labels: true,
    labels: {
        cnum: 'Kartennummer',
        exp: 'MM/JJ',
        cvv: 'CV2'
    },
    label_position: 'bottom' 
};

Custom Error Messages

Error messages being returned from the Payment Card Entry contain a code to identify which error is being thrown, a reason describing what went wrong, a message describing what to do to fix the error, and a type to identify what field the error affects (this can also be payment_key if the error arises while getting the key). See the example below.

{
    'code': '12',
    'message': 'Please enter a valid credit card number.',
    'reason': 'card number must be between 13 and 19 digits',
    'type': 'cnum'
}

This information can be consumed by using the addEvenListener function on the paymentCardEntry instance as seen below:

paymentCard.addEventListener('error', err => {
    err = JSON.parse(err);
    if (err.code === '0') {
        clearError('paymentCard');
    } else {
        handleError(err.message, 'paymentCard');
    }
});

Error responses with code === 0 are for the purpose of clearing validation errors and will still include a type specific to which field is valid. A list of all error responses are included below:

Error Code	Reason	Default Message	Type
0	clear error	N/A	cnum / exp / cvv
11	card number not given	Please enter a credit card number.	cnum
12	card number must be between 13 and 19 digits	Please enter a valid credit card number.	cnum
13	card number invalid	Please enter a valid credit card number.	cnum
15	expiration date must be in MM/YY format	Please enter an expiration date.	exp
16	expiration month must be between 1 and 12	Please enter a valid expiration date.	exp
17	card expired	Credit card expired. Please try a different card.	exp
18	cvv too short	Please enter a valid CVV.	cvv
19	invalid json in payment key response	Something went wrong, please try again.	paymentKey
20	unable to reach tokenization server	Server unavailable, check connection and try again.	paymentKey
21	statusText from request response	Something went wrong, please try again.	paymentKey
22	invalid form field(s)	Invalid card information.	paymentKey

The error messages can be customized by including the custom_error_messages field in the config (as seen below) where the key is the error code you wish to customize and the value is the custom message string. Only the specified messages will be overridden, everything else will return the default message. These custom messages will also be displayed within the iframe if the display_errors config is set to true.

var payCardConfig = {
    custom_error_messages: {
        '11': 'test message 11',
        '15': 'test message 15',
        '18': 'test message 18',
    }
};