Client js v2 - USAePay Help

Client JS v2 (Beta)

Please Note: This page includes references to features that are still under development. For the currently-supported feature set, see the Client JS v1 Docs.

You can use the Client JS javascript library to collect payment information from customers paying online in our simple modern interface. Once payment information is collected, it tokenizes the sensitive data into a single-use payment_key to keep your customer's information secure.

Single Payment Entry

The Single Payment Entry is a clean pre-built UI which can be inserted into your payment page. This solution can be useful for merchants with a simple form only accepting a single payment type.

It could also be useful for merchants with a more complex payment flow. For example, if a merchant takes more than one payment type, but wants to spread those payment types throughout the form, they could create a Single Payment Entry container for each payment type. You will find examples below for:

Credit/Debit Cards
Apple Pay

Credit/Debit Card

To add the Payment Entry Box for credit cards to your form, follow these steps:

Card Container

STEP 1- Create a Public Key and Set Up Single Payment Entry Container

First, create a Public API Key in the merchant account. You can create a key by using the Public API Key Endpoint in REST, or creating it manually in the merchant account. Click here for more information.

Use that Public API Key when instantiating the client:

// Instantiate Client with Public API Key
let client = new usaepay.Client('_P120LOb42a1SF4nN54z1Hp0256K7bl3ki0x8iuJP9');

// Instantiate Payment Card Entry
let paymentCard = client.createPaymentCardEntry();

STEP 2- Create Payment Form

Next you should create the payment form. The Single Payment Entry Box will hold sensitive credit card information, so you will not have to add these fields to the payment form.

Once you have created an instance of the Single Payment Entry Box, enter it into the container you created.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Client HTML</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <h1>My Website Checkout Page</h1>

    <form id="paymentForm" action="/charge" method="post">

        <!-- Other Form Data -->

        <label for="paymentCardContainer">Credit/Debit Card</label>
        <div id="paymentCardContainer">
            <!-- PaymentCard iFrame content will go here. -->
        </div>
        <div id="paymentCardErrorContainer"role="alert">
            <!-- Any error messages will be inserted here. -->
        </div>

        <button>Submit Payment Form</button>

    </form>

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

The Payment Entry Box containing the credit card object is purposefully a very simple form to make integrating easier, but if you do want to customize the style of the Payment Entry Box, you can do it in the section labeled style below. Customizing the Payment Entry Box's style is optional. If no customizations are needed, you can move on to the next step.

// instantiate Payment Card Entry
let paymentCard = client.createPaymentCardEntry();

style = {
    // can add custom styling here
}

paymentCard.generateHTML(style);

paymentCard.addHTML('paymentCardContainer');

STEP 3- Create Payment Key

Next you will need to make sure that the card information tokenizes when the form is submitted. Create an event handler that sends fields to the gateway for tokenization, but does not yet submit the form. Example of event handler is shown below.

// listen for errors so that you can display error messages
paymentCard.addEventListener('error', errorMessage => {
    let errorContainer = document.getElementById('paymentCardErrorContainer');
    errorContainer.textContent = errorMessage;
});

// listen for your form to be submitted
let form = document.getElementById('paymentForm');
form.addEventListener('submit', event => {
    event.preventDefault();

    // create a payment key, returns a promise which will resolve in an error or the payment key
    client.getPaymentKey(paymentCard).then(result => {
    if (result.error) {
      let errorContainer = document.getElementById('paymentCardErrorContainer');
      errorContainer.textContent = result.error.message;
    } else {
      // do something with your payment key
      tokenHandler(result);
    }
  }).catch( err => {
        // catch errors
  });
})

After the card information is submitted, the server will return a response:

If the payment_key was generated successfully, the server will return a one time use token or payment_key. This is what you will use to actually run the transaction.
If the payment_key was NOT generated successfully, the server will return an error which you can interpret and relay to the customer.

STEP 4- Submit Form and Payment Key to Server

The final step is to submit the payment_key and the other fields you collected in the payment form to your server to process the transaction. Your server can then process all actions to complete the sale, including sending the sale to our server for approval. This is normally done using the REST API or one of our language specific libraries. Click here for an example of a REST API sale using the payment key.

function tokenHandler(token) {
    // Insert the token ID into the form so it gets submitted to the server
    var form = document.getElementById('paymentForm');
    var hiddenInput = document.createElement('input');
    hiddenInput.setAttribute('type', 'hidden');
    hiddenInput.setAttribute('name', 'payment_key');
    hiddenInput.setAttribute('value', token);
    form.appendChild(hiddenInput);

    // Submit the form
    form.submit();
}

Apple Pay

To add the ApplePay UI to your form, follow these steps:

STEP 1- Configure Apple Pay

To configure your account for Apple Pay you will need to:

Once complete, you will be able to use the next steps to add the Apple Pay button to your site.

STEP 2- Create a Public Key and Apple Pay Container

Use that Public API Key when instantiating the client.

// instantiate client with public_key
let client = new usaepay.Client('_MPJc1XA3dWP9TBj9vP7yLC5c3i05oIbM4S981T2ZL');

let applePayConfig = {
    targetDiv: 'applePayContainer',
    displayName: 'Capsule Corp.',
    paymentRequest: {
        lineItems: [
            {
                label: 'shipping',
                amount: '5.00',
                type: 'final'
            },
            {
                label: 'subtotal',
                amount: '54.99',
                type: 'final'
            },
            {
                label: 'tax',
                amount: '5.49',
                type: 'final'
            }
        ],
        total: {
            label: 'Capsule Corp.',
            amount: '60.48',
            type: 'final'
        },
        countryCode: 'US',
        currencyCode: 'USD'
    }
}

// Instantiate ApplePay Entry
let applePay = client.createApplePayEntry(applePayConfig);

Please Note: All information except the lineitems are required for an Apple Pay Entry, but other fields can also be included. Click here to see available fields.

STEP 3- Verify Apple Pay Compatibility

After you have created the ApplePayEntry, use the checkCompatibility function to verify that Apple Pay is compatible with the transaction. This function will verify the following:

That the customer's browser is compatible with Apple Pay
That the customer has a payment method stored in Apple Pay.
Apple Pay is successfully configured on the gateway account.

// check to see if Apple Pay is available
applePay.checkCompatibility().then( res => {
    // if so, add the Apple Pay button
    applePay.addButton();
}).catch( err => {
    // if not, hide the section it would have gone into
    document.getElementById('applePayContainer').style.display = 'none';
})

STEP 4- Create Payment Form with ApplePay Container

Next, create the payment form. The Apple Pay Container will hold sensitive credit card information, so you will not have to add these fields to the payment form.

Once you have created and verified the instance of the Apple Pay Entry, add it into the container.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Client HTML</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <h1>My Website Checkout Page</h1>

    <form id="paymentForm" action="/charge" method="post">

        <!-- Other Form Data -->

        <div id="applePayContainer">
            <!-- Apple Pay iFrame content will go here. -->
        </div>
        <div id="paymentCardErrorContainer"role="alert">
            <!-- Any error messages will be inserted here. -->
        </div>

        <button>Submit Payment Form</button>

    </form>

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

STEP 5- Create Payment Key

Next, tokenize the Apple Pay entry to create a payment_key. Create an event handler that sends fields to the gateway for tokenization, but does not yet submit the form like the one below:

// listen for Apple Pay to be successfully completed
applePay.on('applePaySuccess', function () {
    // once successfully completed, payment key is ready
    client.getPaymentKey(applePay).then(result => {
        paymentKeyHandler(result);
    }).catch(res => {
        console.error('CATCH: ', res);
    });
});

// listen for any Apple pay errors
applePay.on('applePayError', function () {
    // Handle Errors
})

After the Apple Pay information is submitted, the server will return a response:

If the payment_key was generated successfully, the server will return a one time use token or payment_key. This is what you will use to actually run the transaction.
If the payment_key was NOT generated successfully, the server will return an error which you can interpret and relay to the customer.

STEP 6- Submit Form and Payment Key to Server

function paymentKeyHandler(token) {
    // Insert the token ID into the form so it gets submitted to the server
    var form = document.getElementById('paymentForm');
    var hiddenInput = document.createElement('input');
    hiddenInput.setAttribute('type', 'hidden');
    hiddenInput.setAttribute('name', 'payment_key');
    hiddenInput.setAttribute('value', token);
    form.appendChild(hiddenInput);

    // Submit the form
    form.submit();
}

Google Pay™

To add the Google Pay Button to your form, follow these steps:

STEP 1- Enable Google Pay

To configure your account for Google Pay you will need to:

Enable Google Pay in the Merchant Console
Register with the Google Pay Business Console
- This is how you will get a Google merchant ID.
- When setting up your merchant account it will ask if you are doing a Direct or Gateway integration; you should select Gateway.
Complete the Google Pay web integration checklist

STEP 2- Create a Public Key

You will also need to add a Public API Key to the merchant account. You can create a key by using the Public API Key Endpoint in REST, or by creating it manually in the merchant console. Click here for more information.

STEP 3- Import Pay.js and Create Container

In order to use the Pay.js library, you will need to import it as a script on your page. You will also need to designate a container where you want to Google Pay button to be rendered. You can optionally import the Google Pay library in your HTML file as well, otherwise the Pay.js library includes a way to import it programatically later on.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Payment Form HTML</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- OPTIONAL Google Pay Library Import -->
    <script src="https://pay.google.com/gp/p/js/pay.js"></script>
    <!---------------------------------------->
</head>
<body>
    <h1>My Website Checkout Page</h1>

    <form id="paymentForm" action="/charge" method="post">

        <!-- Other Form Data -->

        <div id="googlePayContainer">
            <!-- Google Pay button will go here. -->
        </div>
        <div id="googlePayErrorContainer" role="alert">
            <!-- Any error messages will be inserted here. -->
        </div>

        <button>Submit Payment Form</button>

    </form>

     <!-- REQUIRED Pay.js Import -->
    <script src="https://www.usaepay.com/js/v2/pay.js"></script>
    <!----------------------------->
</body>
</html>

STEP 4- Instantiate Google Pay Client

Next you will need to instantiate Pay.js and the Google Pay client using your Public API Key and Google Pay Merchant ID.

// instantiate Pay.js client with public api key
let client = new usaepay.Client(<<public API key>>);

let googlePayConfig = {
    targetDiv: 'googlePayContainer',
    paymentDataRequest: {
        transactionInfo: {
            currencyCode: 'USD',
            totalPriceStatus: 'FINAL',
            totalPrice: '1.00'
        },
        merchantInfo: {
            merchantId: '<Google Merchant ID>'
        }
    }
}

// instantiate GooglenPay entry
let googlePay = client.createGooglePayEntry(googlePayConfig);

Please Note: The information in googlePayConfig in the example above is the bare minimum required for a Google Pay Entry, but other options can be configured as well. Click here to see available fields.

STEP 5- Verify Google Pay Compatibility

In order for Google Pay to work, certain requirements must be met. Once the compatibility test is passed, you can then render the button.

function checkCompatibility() {
    googlePay.checkCompatibility().then(res => {
        googlePay.addButton()
    }).catch(err => {
        // handle error
    });
}

Please Note: If you did not import the Google Pay library via script tag in the HTML of your page, then you must import it before checking for compatibility.

googlePay.loadLibrary().then(res => {
    checkCompatibility();
}).catch(err => {
    // handle error
});

STEP 6- Get Payment Key

Now that the Google Pay button has been rendered on your page, all that's left to do is wait for the user to click the button and complete the payment. Then you can tokenize the Google Pay entry to create a payment_key and process the transcation. Don't forget to handle any errors that may arise during the process.

googlePay.on('googlePaySuccess', () => {
    client.getPaymentKey(googlePay).then( result => {
        handlePaymentKey(result);
    }).catch( err => {
        // handle error
    })
});

googlePay.on('googlePayError', function () {
    // handle error
})

STEP 7- Submit Form and Payment Key to Server

function handlePaymentKey(token) {
    // Insert the token ID into the form so it gets submitted to the server
    var form = document.getElementById('paymentForm');
    var hiddenInput = document.createElement('input');
    hiddenInput.setAttribute('type', 'hidden');
    hiddenInput.setAttribute('name', 'payment_key');
    hiddenInput.setAttribute('value', token);
    form.appendChild(hiddenInput);

    // Submit the form
    form.submit();
}

Please Note: If would like to enable 3DS for PAN_ONLY credentials returned via the Google Pay API check out the documentation on VPAS (Verified by Visa) and UCAF (Mastercard Secure Code) and how to include it in the Transaction API.