Reference

JavaScript SDK

You can use our JavaScript SDK to:

  • Encrypt data client-side
  • Collect credit card numbers with Inputs

Quickstart

Install SDK

Our JavaScript SDK is distributed from our CDN, and can be installed just by placing this script tag before the closing </body> tag in your HTML.

1
<body>
2
<script src="https://js.evervault.com/v2" async></script>
3
</body>

Initialize SDK

Once installed, initialize the JavaScript SDK with your Team and App ID found in the Evervault Dashboard.

1
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');

Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

1
const encrypted = await evervault.encrypt("Hello, world!");

Full example

Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key), run it in your own environment and run the encryption and decryption for yourself.

1
<body>
2
<script src="https://js.evervault.com/v2"></script>
3
<script>
4
(async () => {
5
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
6
const encrypted = await evervault.encrypt("Hello, world!");
7
8
console.log(encrypted);
9
})();
10
</script>
11
</body>

Reference

window.Evervault(appId, teamId)

The SDK constructor accepts two parameters:

  • Your Team ID
  • Your App ID
1
const evervault = new Evervault(
2
// Your Team ID
3
"<TEAM_ID>",
4
// Your App ID
5
"<APP_ID>",
6
);
Parameters
appIdRequired

The ID of your Evervault app. This can be found inside of your app settings on the Evervault dashboard.

teamIdRequired

The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.


evervault.encrypt(data)

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products. To encrypt data using the JavaScript SDK, simply pass a String or an Object into the evervault.encrypt() function.

The encrypted data can be passed to your server and stored in your database as normal. It can also be used with any of Evervault’s other services.

1
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2
3
const encrypted = await evervault.encrypt("Hello, world!");
Parameters
dataRequiredString | Data

The data to encrypt.


evervault.inputs(element, config)

Initializes Evervault Inputs. Evervault Inputs makes 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).

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.

Example

1
<body>
2
<form id="ev-payment-form">
3
<div id="ev-card-fields">
4
<!-- Evervault will create input elements here -->
5
</div>
6
</form>
7
<script src="https://js.evervault.com/v2"></script>
8
<script>
9
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
10
const inputs = evervault.inputs('ev-card-fields');
11
</script>
12
</body>
Parameters
elementIdString

ID of the DOM element in which the Evervault Inputs iFrame should be embedded.

configString | Object

A theme string (supported: default, minimal or material), or a config object for custom styles.

config.themeString

The base styling for Inputs. Currently supports default, minimal and material.

config.heightString

The height of the Evervault Inputs iframe.

config.primaryColorString

The main theme color.

config.labelColorString

The color CSS property applied to the input labels.

config.inputBorderColorString

The border-color CSS property applied to inputs.

config.inputTextColorString

The color CSS property applied to inputs.

config.inputBackgroundColorString

The color CSS property applied to the ::placeholder CSS pseudo-element for inputs.

config.inputBorderRadiusString

The border-radius CSS property applied to inputs.

config.inputHeightString

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.

You can see the format of this object below:

1
{
2
"card": {
3
"type": "visa_credit",
4
"number": "ev:encrypted:abc123",
5
"cvc": "ev:encrypted:def456",
6
"expMonth": "01",
7
"expYear": "23"
8
},
9
"isValid": true,
10
"isPotentiallyValid": true,
11
"isEmpty": false,
12
"error": {
13
"type": "invalid_pan",
14
"message": "The credit card number you entered was invalid"
15
}
16
}

Card data can be retrieved in one of the following two ways:

onChange()

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 function is run every time your user updates the card data.

1
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
2
const inputs = evervault.inputs('ev-card-fields');
3
4
const hook = inputs.on('change', async (encryptedCardData) => {
5
console.log(encryptedCardData);
6
});

getData()

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

1
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
2
const inputs = evervault.inputs('ev-card-fields');
3
4
const encryptedCardData = await inputs.getData();