JavaScript

Installation

Our JavaScript SDK is distributed from our CDN and can be loaded with a simple script tag. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

1<script src="https://js.evervault.com/v2"></script>

Using npm

You can also install Evervault via the @evervault/js package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

1import { loadEvervault } from "@evervault/js";
2
3const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");

Note: It is important to note that for PCI Compliance you must load the Evervault SDK directly from our CDN and cannot bundle it with your application. The loadEvervault function will always load the latest version of the Evervault SDK regardless of which version of @evervault/js you are using.

Asynchronous Loading

You can load the SDK asynchronously using the async attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

1<!DOCTYPE html>
2<html>
3  <head>
4    <script
5      src="https://js.evervault.com/v2"
6      onload="onEvervaultReady()"
7      async
8    ></script>
9    <script>
10      function onEvervaultReady() {
11        const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
12      }
13    </script>
14  </head>
15</html>

Usage

Once loaded, you can initialize the Evervault SDK with your Team and App ID found in the Evervault Dashboard.

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

Reference

Evervault

Creates an instance of the Evervault SDK using your Team and App ID.

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

Parameters

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

encrypt

Encrypts data using Evervault Encryption. 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 Relay.

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

Parameters

dataRequiredstring | Data | File | Blob
The data to encrypt

decrypt

Decrypts data previously encrypted with an Evervault product or SDK.

The decrypt() function uses Client-Side Tokens. 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.

1const encrypted = await evervault.encrypt("Hello, world!");
2await evervault.decrypt("<CLIENT-SIDE-TOKEN>", encrypted);

Parameters

clientSideTokenRequiredstring
A Client-Side Token with permission to decrypt the given payload.
encryptedDataRequiredstring
The encrypted data to decrypt.

ui.card

Initializes a Card component for Card Collection. The Card component makes it easy to collect and encrypt card data in a completely PCI-compliant environment.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2
3const card = evervault.ui.card({
4  theme: evervault.ui.themes.clean(),
5});
6
7card.on("change", (payload) => {
8  console.log(payload.card.number);
9  // ev:...
10});
11
12card.mount("#ev-card-fields");

Parameters

theme
Allows you to completely customize the appearance of the component. See Custom Styling for more information.
iconsBoolean | Record<brand, string>
If set to true, the component will display icons for the detected card brand. You can customize icons by passing an object with the brand as the key and src URL as the value.
autoFocusBoolean
If set to true, the component will automatically focus when it mounts.
acceptedBrandsstring[]
When set to a value in the supported cards list, the component will be restricted to those brands.
fieldsstring[]
Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
redactCVCBoolean
Sets the type attribute of the CVC field to password in order to visually redact the CVC field..
translationsObject
Allows you to customize the text shown inside of the component.
validationObject
Allows you to customize validation logic for the component.

card.mount

Mounts the component to a given DOM node.

1card.mount("#card-details");

card.on('change')

Subscribe to changes made to the component. The encrypted card details can be accessed from the payload passed to the callback. The change event will fire any time there is a state update in the component. This includes when the user types in a field, looses focus on a field, or when an error is displayed.

1card.on("change", (data) => {
2  console.log(data.card.number);
3  // ev:...
4});

Callback Parameters

data.cardObject
Information about the entered card, including meta data as well as the encrypted number aned CVC.
data.errorsRecord<string, string>
Validation errors related to the card details.
data.isValidBoolean
Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate method.
Note: This field represents if there are any errors shown, not if the card details are valid. You should use the isComplete field to determine if the user has successfully entered a valid card.
data.isCompleteBoolean
Whether or not the card details are valid. This will only be true if the user has entered a valid card number, expiry date and CVC.

card.on('complete')

The complete event will fire once the user has successfully filled out all fields in the Card Component with valid values.

1card.on("complete", (data) => {
2  console.log(data.card.number);
3  // ev:...
4});

Callback Parameters

data.cardObject
Information about the entered card, including meta data as well as the encrypted number aned CVC.
data.errorsRecord<string, string>
Validation errors related to the card details.
data.isValidBoolean
Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate method.
Note: This field represents if there are any errors shown, not if the card details are valid. You should use the isComplete field to determine if the user has successfully entered a valid card.
data.isCompleteBoolean
Whether or not the card details are valid. This will only be true if the user has entered a valid card number, expiry date and CVC.

card.on('ready')

The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

1card.on("ready", () => {
2  document.getElementById("loading").addClass("hide");
3  document.getElementById("card-details").removeClass("hide");
4});

card.on('error')

The error event will be fired if the component fails to load. If you want to respond to validation errors you should use the change event instead.

1card.on("error", () => {
2  alert("Opps, something went wrong!");
3});

card.on('swipe')

Subscribe to swipe events from card readers. The encrypted card details can be accessed from the payload passed to the callback. The component must have focus for the card reader event to be detected.

1card.on("swipe", (data) => {
2  console.log(data.card.number);
3  // ev:...
4});

Callback Parameters

data.cardObject
Information about the entered card, including meta data as well as the encrypted number aned CVC.

card.update()

Update the configuration for the component after it has been initialized. Any arguments passed will be merged with the arguments passed when the component was initialized. This can be used to dynamically update the translations for the component, or update the styling.

1card.update({
2  translations: {
3    number: {
4      label: "uimhir chárta",
5    },
6  },
7});

Parameters

theme
Allows you to completely customize the appearance of the component. See Custom Styling for more information.
iconsBoolean | Record<brand, string>
If set to true, the component will display icons for the detected card brand. You can customize icons by passing an object with the brand as the key and src URL as the value.
autoFocusBoolean
If set to true, the component will automatically focus when it mounts.
acceptedBrandsstring[]
When set to a value in the supported cards list, the component will be restricted to those brands.
fieldsstring[]
Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
translationsObject
Allows you to customize the text shown inside of the component.
validationObject
Allows you to customize validation logic for the component.

card.validate()

Manually trigger validation for the card details fields. This method is useful if you want to force validation to display error messages inside of the component. This is an asynchronous operation and will not return an immediate result. You can use the validate event to listen for the result of calling this method.

1card.on("validate", (data) => {
2  console.log(data.isValid);
3});
4
5card.validate();

card.unmount()

Removes the component from the DOM.

1card.unmount();

ui.threeDSecure

The ThreeDSecure component can be used in combination with the Evervault API to perform 3D Secure authentication. In order to use the ThreeDSecure component you must first create a 3D Secure session on your backend and pass it to your frontend. The component will display the 3D Secure iframe and handle the authentication process.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2const threeDSecure = evervault.ui.threeDSecure("tds_visa_123456789");
3threeDSecure.mount();

Parameters

sessionRequiredstring
The 3D Secure session ID. A 3D Secure session can be created using the Create 3D Secure Session API endpoint.
theme
Allows you to customize the appearance of the component. See Custom Styling for more information.
Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
size{ width: number | string, height: number | string }
This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
failOnChallengeBoolean | () => Booleanm | () => Promise<Boolean>
If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

threeDSecure.mount()

Mounts the component to the DOM. If no selector is provided the component will be rendered as a modal window.

1threeDSecure.mount();

Parameters

selectorstring
The selector of the DOM node to mount the component to. If no selector is provided the component will be rendered as a modal window.

threeDSecure.on('success')

The 'success' event will be fired once the 3D Secure authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the Retrieve 3DS Session endpoint to retrieve the cryptogram for the session and complete the payment.

Note: The component is automatically unmounted after the 'success' event is fired.

1threeDSecure.on("success", () => {
2  // 3DS is complete and payment can be finalized
3});

threeDSecure.on('failure')

The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.

Note: The component is automatically unmounted after the 'failure' event is fired.

1threeDSecure.on("failure", () => {
2  // 3DS failed and user should be informed
3});

threeDSecure.on('ready')

The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

1threeDSecure.on("ready", () => {
2  document.getElementById("threeDSecure").removeClass("hide");
3});

threeDSecure.on('error')

The error event will be fired if the component fails to load.

1threeDSecure.on("error", (error) => {
2  console.error(error);
3});

Callback Parameters

error.errorString
A unique code representing the error that occurred.
error.messageString
A human readable message describing the error.

threeDSecure.update()

Update the configuration for the component after it has been initialized. Any arguments passed will be merged with the arguments passed when the component was initialized.

1threeDSecure.update({
2  size: {
3    width: 300,
4    height: 400,
5  },
6});

Parameters

theme
Allows you to customize the appearance of the component. See Custom Styling for more information.
Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
size{ width: number | string, height: number | string }
This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
failOnChallengeBoolean | () => Booleanm | () => Promise<Boolean>
If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

threeDSecure.unmount()

Removes the component from the DOM.

1threeDSecure.unmount();

ui.reveal

The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. Before using Reveal you'll first need to have a JSON endpoint to retrieve data from. This is often your own API endpoint combined with Relay to decrypt previously encrypted data from your database or a third-party API.

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!

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2// Create a request to your endpoint to fetch the data
3const request = new Request("<YOUR_ENDPOINT>");
4// Create a reveal instance, passing the request as an argument
5const reveal = evervault.ui.reveal(request);
6// Use JSON path to select the data in the response you want to
7// display and mount it to the DOM.
8reveal.text("$.card.number").mount("#card-number");

reveal.on("ready")

The ready event will be fired once the request has been completed and all reveal consumer components are ready to be shown.

1reveal.on("ready", () => {
2  console.log("Reveal is ready");
3});

reveal.on("error")

The error event will be fired if the Reveal Component fails to load or the passed request fails.

1reveal.on("error", () => {
2  console.log("Something went wrong");
3});

reveal.text()

Creates a Reveal Text consumer. The Reveal Text consumer allows you to render a selected field from the request response.

1const request = new Request("<YOUR_ENDPOINT>");
2const reveal = evervault.ui.reveal(request);
3const text = reveal.text("$.card.number", {
4  format: {
5    regex: /(.{4})(.{4})(.{4})(.{4})/g,
6    replace: "$1 $2 $3 $4",
7  },
8});
9
10text.mount("#card-number");

Parameters

pathRequiredstring
The JSON path to the field you want to display.
options.themeTheme
Allows you to completely customize the appearance of the component. See Custom Styling for more information.
options.formatObject
Allows you to use regex matching to format the field value.

text.mount()

Mounts the Reveal Text component to a given DOM node.

1text.mount("#card-details");

text.unmount()

Removes the Text Component from the DOM.

1text.unmount();

reveal.copyButton()

Creates a Reveal Copy Button consumer. This renders a button which when clicked will copy a response field to the users clipboard.

1const request = new Request("<YOUR_ENDPOINT>");
2const reveal = evervault.ui.reveal(request);
3const text = reveal.copyButton("$.card.number", {
4  theme: evervault.ui.themes.clean(),
5  text: "Copy Number",
6  format: {
7    regex: /(.{4})(.{4})(.{4})(.{4})/g,
8    replace: "$1 $2 $3 $4",
9  },
10});
11
12text.mount("#card-number");

Parameters

pathRequiredstring
The JSON path to the field you want to display.
options.themeTheme
Allows you to completely customize the appearance of the component. See Custom Styling for more information.
options.textRequiredstring
The text to display on the button.
options.formatObject
Allows you to use regex matching to format the field value.

copyButton.on("copy")

The copy event will be fired when the button is clicked and the value has been copied to the clipboard.

1copyButton.on("copy", () => {
2  console.log("Copied to clipboard");
3});

copyButton.mount()

Mounts the Reveal Copy Button component to a given DOM node.

1copyButton.mount("#node");

copyButton.unmount()

Removes the Copy Button Component from the DOM.

1copyButton.unmount();

transactions.create

Creates a transaction object that can be used with Apple Pay and Google Pay components.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2const transaction = evervault.transactions.create({
3  amount: 1299,
4  currency: "USD",
5  country: "US",
6  merchantId: "merchant_abc123",
7});

Parameters

options.amountRequirednumber
The transaction amount in smallest currency unit (e.g., cents).
options.currencyRequiredstring
The three-letter ISO currency code.
options.countryRequiredstring
The two-letter ISO country code.
options.merchantIdRequiredstring
Your Evervault merchant ID.
options.ypepayment | disbursement | recurring
Specify the type of transaction. Disbursement requests are only available with Apple Pay. Default: payment.
options.lineItemsTransactionLineItem[]
Optional array of line items to display in the payment sheet.
options.requiredReceipientDetailsstring[]
Optional array of recipient details required for collection on a disbursement transactions. Possible values: name, email, phone, address.

ui.applePay

Initializes an Apple Pay button that handles the payment flow and returns encrypted payment details.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2const transaction = evervault.transactions.create({
3  amount: 1299,
4  currency: "USD",
5  country: "US",
6  merchantId: "<MERCHANT_ID>",
7});
8
9const component = evervault.ui.applePay(transaction, {
10  process: async (data, { fail }) => {
11    try {
12      await processPayment(data);
13    } catch (error) {
14      fail({
15        message: "Payment failed",
16      });
17    }
18  },
19});
20
21component.mount("#apple-pay");

Parameters

transactionRequiredTransaction
The transaction object created with transactions.create.
optionsRequiredObject
Configuration options for the Apple Pay button.

applePay.on("success")

Fired when the payment has been successfully authorized.

applePay.on("error")

Fired if there's an error initializing the Apple Pay button.

applePay.on("cancel")

Fired when the user cancels the Apple Pay payment flow.

ui.googlePay

Initializes a Google Pay button that handles the payment flow and returns encrypted payment details.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2const transaction = evervault.transactions.create({
3  amount: 1299,
4  currency: "USD",
5  country: "US",
6  merchantId: "MERCHANT_ID",
7});
8
9const googlePay = evervault.ui.googlePay(transaction, {
10  type: "pay",
11  color: "black",
12  borderRadius: 4,
13  allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
14  allowedCardNetworks: ["VISA", "MASTERCARD"],
15  process: async (data, { fail }) => {
16    try {
17      await processPayment(data);
18    } catch (error) {
19      fail({
20        message: "Payment failed",
21      });
22    }
23  },
24});
25
26googlePay.mount("#google-pay-button");

Parameters

transactionRequiredTransaction
The transaction object created with transactions.create.
optionsRequiredObject
Configuration options for the Google Pay button.

googlePay.on("success")

Fired when the payment has been successfully authorized.

googlePay.on("error")

Fired if there's an error initializing the Google Pay button.

googlePay.on("cancel")

Fired when the user cancels the Google Pay payment flow.

googlePay.on("ready")

Fired when the Google Pay button is ready to be displayed.

Custom Styling

Some components in the SDK allow you to customize the appearance of the component using a theme object. A theme is just an object with a styles property. This styles property uses a CSS-as-JS format to define CSS rules for the component. These rules will be compiled to CSS and injected into the iframe.

Although you can customize the CSS inside of the iframe, you cannot modify the HTML. We know that layout can have a big impact on style definitions and so to help with this, we apply custom attributes to various elements within the iframe. These attributes are prefixed with ev-.

You can see our premade Card Collection themes for an example of how these attributes can be used when creating themes.

1const theme = {
2  styles: {
3    ":root": {
4      "color-scheme": "light",
5    },
6    label: {
7      fontSize: 11,
8      fontWeight: 500,
9      textTransform: "uppercase",
10    },
11    ".error": {
12      color: "red",
13      fontSize: 12,
14      marginTop: 5,
15    },
16    ".field input": {
17      marginTop: 5,
18      padding: "8px 12px",
19      border: "2px solid #dddddd",
20    },
21    ".field:focus-within input": {
22      borderColor: "#6633ee",
23    },
24  },
25};

Responsive Styling

You can define media queries inside of the themes styles object, however, this may lead to unexpected behaviour as the media queries will be matched against the iframe document, not the parent document. To get around this, we provide a media utility which allows you to define styles based on media queries that match the parent document.

To access the media utility you will need to define your theme as a function that returns a theme object. This function will be passed a utilities object as an argument, which contains the media utility. The media utility should be spread into the styles object of the returned theme.

1const theme = (utilities) => {
2  return {
3    styles: {
4      label: {
5        fontSize: 16,
6      },
7      ...utilities.media("(max-width: 400px)", {
8        label: {
9          fontSize: 20,
10        },
11      }),
12    },
13  };
14};

JavaScript

Parameters

Parameters

Parameters

Parameters

Callback Parameters

Callback Parameters

Callback Parameters

Parameters

Parameters

Parameters

Callback Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

On this page