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!");

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.

To encrypt strings using the JavaScript SDK, simply pass a String or an Object into the evervault.encrypt() function. To encrypt a file, pass a File or Blob.

The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.

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

Parameters

dataRequiredString | Data | File | Blob

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.

config.cardNumberLabelString

The label for the card number input

config.expirationDateLabelString

The label for the expiration date input

config.securityCodeLabelString

The label for the security code input

config.expirationDatePlaceholderString

The placeholder for the expiration date input

config.invalidCardNumberLabelString

The message shown on an invalid card number

config.invalidExpirationDateLabelString

The message shown on an invalid expiration date

config.invalidSecurityCodeLabelString

The message shown on an invalid security code

config.fontUrlString

Load a custom font with the Google Fonts API

config.fontFamilyString

Set the font-family for the fontUrl

config.inputFontSizeString

Set the font-size property of the input attribute

config.inputBoxShadowString

Set the box-shadow property of the input attribute

config.labelFontSizeString

Set the font-size property of the label attribute

config.labelWeightString

Set the font-weight property of the label attribute

config.disableCVVString

Removes the CVV field from Inputs, showing only the Card Number and Expiry fields

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();

Localization

The iFrame can be localized on initialization by providing a set of labels in the config. The labels can then be updated as required using the setLabels method.

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

labels.cardNumberLabelString

The label for the card number input

labels.expirationDateLabelString

The label for the expiration date input

labels.securityCodeLabelString

The label for the security code input

labels.expirationDatePlaceholderString

The placeholder for the expiration date input

labels.invalidCardNumberLabelString

The message shown on an invalid card number

labels.invalidExpirationDateLabelString

The message shown on an invalid expiration date

labels.invalidSecurityCodeLabelString

The message shown on an invalid security code

iFrame loading status

If you need to wait for the iFrame that serves inputs to load before doing some action, there is an easy way to do so.

isInputsLoaded

This is a Promise that resolves when the iFrame is loaded. You can listen for the iFrame load event by awaiting this Promise, or using then:

1
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
2
const inputs = evervault.inputs('ev-card-fields');
3
4
await inputs.isInputsLoaded;
5
6
handleInputsLoaded();
7
8
// or
9
10
inputs.isInputsLoaded.then(() => {
11
    handleInputsLoaded();
12
});