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.

javascriptconst 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.

javascriptasync evervault.encrypt(data: Object | Array | String | Number);

Parameter	Type	Description
`data`	`Object`, `Array`, `String` or `Number`	Data 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.

javascriptevervault.inputs(id: String, config: String | Object);

Parameter	Type	Description
id	String	ID of the element in which the Evervault Inputs iFrame should be embedded
config	String or Object	A 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.

Parameter	Type	Description
theme	String	The base styling for Inputs. Currently supports minimal and material
height	String	The height of the Evervault Inputs iFrame
primaryColor	String	The main theme color
labelColor	String	The color CSS property applied to the input labels
inputBorderColor	String	The border-color CSS property applied to inputs
inputTextColor	String	The color CSS property applied to inputs
inputBackgroundColor	String	The background-color CSS property applied to inputs
inputPlaceholderColor	String	The color CSS property applied to the ::placeholder CSS pseudo-element for inputs
inputBorderRadius	String	The border-radius CSS property applied to inputs
inputHeight	String	The 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.

javascriptconst 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.

javascriptconst 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!

You should already have the below script tag immediately before the closing </body> tag: <script src="https://js.evervault.com/v1" async></script>
Update this script tag to the below tag: <script src="https://js.evervault.com/v2" async></script>
Update how you initialise the SDK by including an App ID:

javascriptconst 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!

toc