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 Card
To add the Payment Entry Box for credit cards to your form, follow these steps:
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 orpayment_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:
- Register Apple Merchant ID
- Create Payment Processing Certificate
- Register Merchant Domains
- Create Merchant Identity Certificate
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
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_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 orpayment_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
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 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
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 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.