Pay.js - USAePay Help

Pay.js v1 (previously Client JS)

You can use the Pay.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 you 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();
}