Pay.js v1 → v2 Migration Guide

To migrate from Pay.js v1 to v2 simply change the URL in the script tag where you're importing the library:

Before

<script src="https://www.usaepay.com/js/v1/pay.js"></script>

After

<script src="https://www.usaepay.com/js/v2/pay.js"></script>

Breaking Changes

There are 2 breaking changes in the Payment Card Entry class:

Payment Key Response

When calling the getPaymentKey() function on the Payment Card Entry, instead of returning the payment key as a string, this function now returns an object that contains some obfuscated card info along with the payment key as shown below:

Before

    client.getPaymentKey(paymentCard).then(result => {
        if (result.error) {
            // returns error object with error message
        } else {
            // returns payment key string 
            // ex: "a1b2c3d4e5")
        }
    });

After

    client.getPaymentKey(paymentCard).then(result => {
        if (result.error) {
            // returns error object with error message
        } else {
            // returns payment key object
            // ex: {
            //    "type":"payment_key",
            //    "key":"a1b2c3d4e5",
            //    "creditcard":{
            //        "number":"111111xxxxxx1111",
            //        "cardtype":"02"
            //    }
            // }
        }
    });

Error Response

When an error event is thrown from the Payment Card Entry, instead of sending a simple string message, a more detailed object is sent which contains a code, type, reason, and message as shown below.

Before

    paymentCard.addEventListener('error', errorMessage => {
        // errorMessage is a string
        var errorContainer = document.getElementById('paymentCardErrorContainer');
        errorContainer.textContent = errorMessage;
    });

After

    paymentCard.addEventListener('error', err => {
        // err is an object
        // ex: {
        //  'code': '12',
        //  'message': 'Please enter a valid credit card number.',
        //  'reason': 'card number must be between 13 and 19 digits',
        //  'type': 'cnum'
        // }
        err = JSON.parse(err);
        if (err.code === '0') {
            clearError();
        } else {
            handleError(err);
        }
    });

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

These error messages can be customized by setting the custom_error_messages config as seen below where the object key is the error code 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 Payment Card Entry 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',
    },
    display_errors: true
};