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

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 Early Access, and files can only be decrypted with Relay.

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

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

The Card component collects and encrypts card data for Card Collection in a completely PCI-compliant environment. You can build it in two ways.

• Composable: compose the fields yourself as HTML elements inside <ev-card>. They render in the order you write them, so you control the layout.
• Config: initialize the card with ui.card() and configure it with a JavaScript object. The fields render in a fixed order.

1<ev-card teamid="<TEAM_ID>" appid="<APP_ID>" autoprogress>
2  <ev-card-holder label="Name on card"></ev-card-holder>
3  <ev-card-number></ev-card-number>
4  <ev-row>
5    <ev-card-expiry-month></ev-card-expiry-month>
6    <ev-card-expiry-year></ev-card-expiry-year>
7    <ev-card-cvc redact></ev-card-cvc>
8  </ev-row>
9  <ev-field name="postcode" label="Postcode" autocomplete="postal-code" required></ev-field>
10</ev-card>
11
12<script>
13  const card = document.querySelector("ev-card");
14
15  card.addEventListener("change", (event) => {
16    console.log(event.detail.card.number);
17    // ev:...
18  });
19</script>

1<script src="https://js.evervault.com/v2"></script>
2
3<ev-card teamid="<TEAM_ID>" appid="<APP_ID>"></ev-card>

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2evervault.ui.mountElements();

1<ev-card>
2  <ev-card-number></ev-card-number>
3  <ev-row>
4    <ev-card-expiry-month></ev-card-expiry-month>
5    <ev-card-expiry-year></ev-card-expiry-year>
6  </ev-row>
7  <ev-card-cvc></ev-card-cvc>
8</ev-card>

1<ev-card>
2  <ev-card-number></ev-card-number>
3  <ev-field
4    name="postcode"
5    label="Postcode"
6    autocomplete="postal-code"
7    autocapitalize="characters"
8    pattern="[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}"
9    errormessage="Enter a UK postcode"
10    required
11  ></ev-field>
12</ev-card>

1card.addEventListener("change", (event) => {
2  console.log(event.detail.fields.postcode);
3  // ev:... or null
4});

1const card = document.querySelector("ev-card");
2
3card.acceptedBrands = ["visa", "mastercard"];
4card.theme = evervault.ui.themes.minimal();

1card.translations = {
2  number: { label: "Card number" },
3  fields: { postcode: { label: "Postal code" } },
4};

1<ev-card-number
2  label="Card number"
3  unsupportedbrandmessage="This card isn't accepted"
4></ev-card-number>

1document.querySelector("ev-card-cvc").redact = true;

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

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

1card.addEventListener("ready", () => {
2  document.getElementById("loading").classList.add("hide");
3});

1card.addEventListener("error", () => {
2  console.error("The card failed to load");
3});

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

1card.addEventListener("validate", (event) => {
2  console.log(event.detail.isValid);
3});

1card.addEventListener("focus", (event) => {
2  console.log(event.detail.field); // "number" | "expiry" | "cvc" | "name" | "field"
3});

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

1card.show();

brands.create

Creates a custom card brand definition that can be passed to the customBrands option of the Card component. Use this to add support for card networks that aren't included in Evervault's built-in brand list.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2
3const acmeBrand = evervault.brands.create("acme-card", {
4  numberValidationRules: {
5    ranges: [[88000, 88999]],
6    lengths: [16],
7  },
8  securityCodeValidationRules: {
9    lengths: [3],
10  },
11});
12
13const card = evervault.ui.card({
14  customBrands: [acmeBrand],
15});

ui.pin

Initializes a component for collecting and encrypting PIN numbers in a PCI-compliant environment.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
2
3const pin = evervault.ui.pin({
4  length: 4,
5  mode: "numeric",
6});
7
8pin.on("complete", (data) => {
9  console.log(data.value); // encrypted PIN
10});
11
12pin.mount("#pin-field");

pin.mount()

Mounts the component to a given DOM node.

1pin.mount("#pin-field");

pin.on('change')

Fired whenever the PIN value changes.

1pin.on("change", (data) => {
2  console.log(data.value); // encrypted PIN or null
3  console.log(data.isComplete);
4});

pin.on('complete')

Fired when the user enters all PIN digits.

1pin.on("complete", (data) => {
2  console.log(data.value); // encrypted PIN
3});

pin.on('ready')

Fired when the component loads and is ready to be displayed.

1pin.on("ready", () => {
2  document.getElementById("pin-field").style.display = "block";
3});

pin.on('error')

Fired if the component fails to load.

1pin.on("error", () => {
2  console.error("PIN component failed to load");
3});

pin.update()

Updates the component configuration after initialization. Any arguments passed are merged with the original options.

1pin.update({ length: 6 });

pin.unmount()

Removes the component from the DOM.

1pin.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();

threeDSecure.mount()

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

1threeDSecure.mount();

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

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: "300px",
4    height: "400px",
5  },
6});

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.

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

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

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

ui.applePay

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

In Sandbox apps, the encrypted networkToken.number maps to a test card that matches the brand of the card the customer selects in their Apple Wallet.

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

The object passed to options.process includes metadata on card when present. Optional card.paymentMethodType is credit, debit, prepaid, or store when the wallet reports the funding type for the card the user selected. See the Apple Pay guide for how this relates to BIN-derived fields such as funding.

paymentDataType reflects the Apple token format from the credentials API (for example 3DSecure). transactionType indicates the transaction category (oneOff, recurring, or disbursement) based on how you created the transaction. transactionId is Apple's identifier for the token, and comes from the PKPaymentToken header. Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself. billingContact and shippingContact are only populated when the transaction requested those contact fields. shippingMethod is populated when you configured shippingMethods and the customer selected one. phoneticFamilyName and phoneticGivenName are populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). If there's no phonetic reading, then these two values are null.

applePay.mount()

Mounts the Apple Pay button to a given DOM node.

1component.mount("#apple-pay");

applePay.unmount()

Removes the Apple Pay button from the DOM. If an Apple Pay session is active, the sheet is dismissed first.

1component.unmount();

applePay.abort()

Programmatically dismisses the Apple Pay sheet while a session is in progress. This maps to the browser's PaymentRequest.abort() API. When the sheet closes, the cancel event is fired.

Use this when you need to close and reopen Apple Pay — for example, when a shipping address change requires a different currency. Currency cannot be updated mid-session via onShippingAddressChange; abort the session, update the transaction, and let the user open Apple Pay again.

1onShippingAddressChange: async (address) => {
2  const newCurrency = currencyForCountry(address.country);
3
4  if (newCurrency !== transaction.details.currency) {
5    await apple.abort();
6    updateCheckoutCurrency(newCurrency);
7    return { amount: 0, lineItems: [] };
8  }
9
10  return { amount: updatedAmount, lineItems };
11},

abort() is a no-op when no session is in progress. After the user authorizes payment, use fail() in the process callback instead.

applePay.availability()

Checks whether Apple Pay is available on the current device. Returns a promise resolving to "available", "unavailable", or "unsupported".

1const availability = await component.availability();
2
3if (availability === "available") {
4  component.mount("#apple-pay");
5} else {
6  // Show a fallback payment method
7}

applePay.on("ready")

Fired when the Apple Pay button is mounted and ready to be displayed.

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