toc

JavaScript SDK

A full reference of our JavaScript SDK.

The Evervault JavaScript SDK is a toolkit for encrypting data in the browser.

You can use our frontend SDKs to encrypt data — rather than with Relay — and still send it to a third-party via Relay. Encrypting with our frontend SDKs is best for developers who want to avoid the network latency of Relay and/or want to avoid sending plaintext data to an Evervault endpoint.

You don’t need to change your database configuration. You can store Evervault-encrypted data in your database as you would the plaintext version.

Installation

Add this script tag immediately before the closing </body> tag:

html
<script src="https://js.evervault.com/v1" async></script>

Initialization

Once installed, initialize the JavaScript SDK with your team's unique ID found in the Settings.

javascript
const evervault = new Evervault('<YOUR_TEAM_ID>');

Reference

The Evervault JavaScript SDK exposes two functions.

evervault.encrypt()

evervault.encrypt() encrypts data for use in your Cages and through Relay. To encrypt data in the browser, simply pass an object or string into the evervault.encrypt() function. Store the encrypted data in your database as normal.

javascript
async evervault.encrypt(data: Object | Array | String | Number);
ParameterTypeDescription
dataObject, Array, String or NumberData to be encrypted

evervault.inputs()

Self-Serve customers can only use Inputs in debug mode, which is not safe for production use.

evervault.inputs() initialises Evervault Inputs which make it easy to collect encrypted cardholder data in a completely PCI-compliant environment.

Evervault Inputs are served within an iFrame retrieved directly from Evervault’s PCI-compliant infrastructure, which can reduce your PCI DSS compliance scope to the simplest form (SAQ-A) once integrated correctly.

Simply pass the id of the element in which the iFrame should be embedded.

We also support themes and custom styles so you can customise how Inputs looks in your UI.

javascript
evervault.inputs(id: String, config: String | Object);
ParameterTypeDescription
idStringID of the element in which the Evervault Inputs iFrame should be embedded
configString or ObjectA theme string (supported: minimal or material), or a config object for custom styles. See supported styles below.
html
<body>
<form id="ev-payment-form">
<div id="ev-card-fields">
<!-- Evervault will create input elements here -->
</div>
</form>
</body>
<script src="https://js.evervault.com/v1"></script>
<script>
const inputs = evervault.inputs('ev-card-fields');
</script>

Supported styles

When passing a config object for styling Inputs, the following key-value pairs are supported.

ParameterTypeDescription
themeStringThe base styling for Inputs. Currently supports minimal and material
heightStringThe height of the Evervault Inputs iFrame
primaryColorStringThe main theme color
labelColorStringThe color CSS property applied to the input labels
inputBorderColorStringThe border-color CSS property applied to inputs
inputTextColorStringThe color CSS property applied to inputs
inputBackgroundColorStringThe background-color CSS property applied to inputs
inputPlaceholderColorStringThe color CSS property applied to the ::placeholder CSS pseudo-element for inputs
inputBorderRadiusStringThe border-radius CSS property applied to inputs
inputHeightStringThe height CSS property applied to inputs

Retrieving card data

There are two ways of accessing encrypted card data once it has been entered.

In each case, a cardData object containing details about the card data your user has entered is returned.

json
{
"card": {
"type": "visa_credit",
"number": "ev:encrypted:abc123",
"cvc": "ev:encrypted:def456",
"expMonth": "01",
"expYear": "23"
},
"isValid": true,
"isPotentiallyValid": true,
"isEmpty": false,
"error": {
"type": "invalid_pan",
"message": "The credit card number you entered was invalid"
}
}
onChange hook

This option is best when you are looking to handle the card values in realtime, like displaying validation errors as a user is inputting their card data. The callback for the hook is run every time your user updates the card data.

javascript
const hook = inputs.on('change', async (cardData) => {});

getData method

This option is best when you are looking to retrieve card data occasionally, like when your form is submitted.

javascript
const cardData = await inputs.getData();

JavaScript SDK v2 Migration Guide

Recently, Evervault released a UI overhaul alongside the introduction of Apps. The concept of Apps allows users to create multiple tenants (Apps) within a single team. Along with this change, comes a change to how our JavaScript SDK works.

If you had created a team with Evervault prior to the release of Apps, a default App has been created for you and all your existing resource will live inside that app.

If you wish to use the JavaScript SDK with Apps (excluding the default App created for you), you will need to upgrade to the latest version of the SDK!
  1. You should already have the below script tag immediately before the closing </body> tag: <script src="https://js.evervault.com/v1" async></script>

  2. Update this script tag to the below tag: <script src="https://js.evervault.com/v2" async></script>

  3. Update how you initialise the SDK by including an App ID:

javascript
const evervault = new Evervault('<YOUR_TEAM_ID>', '<YOUR_APP_ID>');

Congratulations, you’ve migrated! You can now continue using the SDK the way you always have been!


Was this page useful?