You can use our JavaScript SDK to:

Encrypt data client-side
Collect or display card data with UI Components

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 Primitives. 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.decrypt(token, data)

Decrypts data previously encrypted with the encrypt() function or through Relay.

The decrypt() function allows you to decrypt previously encrypted data using a token.

The token is a time bound token for decrypting data. The token can be generated using our backend SDKs or through our REST API.

The payload must be the same payload that was used to create the token and expires in a maximum of 10 minutes depending on the expiry set when creating the token.

The payload can be any String or Object and it will be returned, decrypted, in the same form.

1
const encrypted = await evervault.encrypt("Hello, world!");
2
3
const decrypted = await evervault.decrypt("<VALID DECRYPT TOKEN>", encrypted)
4
console.log(decrypted) // Output: "Hello, world!"

evervault.inputs(element, config)

Initializes Evervault's Inputs UI Component. 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.

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 by providing a set of labels in the config on initialization. The labels can then be updated as required using the setLabels method.

Adding labels on initialization:

1
const config = {
2
  cardNumberLabel: 'Numéro de carte:',
3
  expirationDateLabel: 'Date d'expiration:', 
4
  securityCodeLabel: 'Code de sécurité:'
5
}
6
7
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
8
const inputs = evervault.inputs('ev-card-fields', config);

Updating labels:

1
const translations = {
2
  "es": {
3
    cardNumberLabel: 'Numéro de carte:',
4
    expirationDateLabel: 'Date d'expiration:', 
5
    securityCodeLabel: 'Code de sécurité:'
6
  }
7
}
8
9
handleLanguageChange = (selectedLanguage) => {
10
  inputs.setLabels(translations[selectedLanguage]);
11
};

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

evervault.reveal(element, request, config, onCopy)

Use evervault.reveal to show your users their encrypted card details in plaintext in a secure iframe hosted by Evervault. Before using Reveal you'll first have to create a Relay to decrypt the card details; Reveal expects to receive the card data from the Relay as a JSON object with the schema below.

It is important that the endpoint that you create sets the applicable CORS headers so that it can be accessed from the Reveal iframe. Otherwise your requests will fail!

1
{
2
  "cardNumber": "string | number",
3
  "cvv": "string | number",
4
  "expiry": "string | number"
5
}

Once you have your endpoint that returns the encrypted card data, you'll need to create an Evervault Inbound Relay that will decrypt the encrypted card data as is passes through it, before it gets to the iFrame. Once you have created your Relay you can add the component to your React app.

1
<div id="reveal"></div>
2
3
<script>
4
  let request = new Request("https://example-com.relay.evervault.com/card-details", {
5
    method: "GET",
6
    headers: {
7
      Authorization: "Bearer ey...",
8
    },
9
  });
10
11
  let config = {
12
    revealFontSize: "20px",
13
    revealFontWeight: 200,
14
    revealTextColor: "#d1dce6",
15
  };
16
17
  const reveal = evervault.reveal("reveal", request, config, () => alert("Copied from Clipboard!"));
18
19
  reveal.isRevealLoaded().then(() => {
20
    console.log("Reveal has loaded");
21
  }).catch((e) => {
22
    console.error(`Reveal has loaded: ${e}`);
23
  });
24
</script>

Example

Parameters

elementIdString

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

requestRequest

The request that Reveal should make when fetching the card details.

configString | Object

A config object for custom styles.

onCopyFunction

A callback that is called when a user presses the copy button in the iFrame