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.
autoProgressBoolean
If set to true, the component automatically moves focus to the next field when the current field is complete.
autoCompleteObject
Controls browser autocomplete behavior per field.
- autoComplete.nameBoolean
  Enable browser autocomplete for the name field.
- autoComplete.numberBoolean
  Enable browser autocomplete for the card number field.
- autoComplete.expiryBoolean
  Enable browser autocomplete for the expiry field.
- autoComplete.cvcBoolean
  Enable browser autocomplete for the CVC field.
acceptedBrandsstring[]
Restricts the component to only accept the specified card brands. If not provided, all brands are accepted. Possible values are visa, mastercard, american-express, diners-club, discover, jcb, unionpay, maestro, elo, mir, hiper, hipercard, szep, uatp, rupay. Custom brands defined using customBrands are accepted regardless of this list.
customBrandsCustomBrand[]
An array of custom card brand definitions created with brands.create. Custom brands are always accepted, even when acceptedBrands is set. See the custom card brands section for usage examples.
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.
defaultValuesObject
Sets default values for card fields on mount.
- defaultValues.namestring
  Default value for the cardholder name field.
redactCVCBoolean
Sets the type attribute of the CVC field to password in order to visually redact the CVC field..
allow3DigitAmexCVCBoolean
If set to false, rejects 3-digit CVCs for American Express cards and requires a 4-digit CVC. Defaults to true.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
translationsObject
Allows you to customize the text shown inside of the component.
- translations.name.label
  Customize the label for the name field.
- translations.name.placeholder
  Customize the placeholder for the name field.
- translations.name.errors.invalid
  Customize the error message for the name field when the value is invalid.
- translations.name.errors.regex
  Customize the error message for when the name field fails regex validation.
- translations.number.label
  Customize the label for the number field.
- translations.number.placeholder
  Customize the placeholder for the number field.
- translations.number.errors.invalid
  Customize the error message for the number field when the value is invalid.
- translations.expiry.label
  Customize the label for the expiry field.
- translations.expiry.placeholder
  Customize the placeholder for the expiry field.
- translations.expiry.errors.invalid
  Customize the error message for the expiry field when the value is invalid.
- translations.cvc.label
  Customize the label for the cvc field.
- translations.cvc.placeholder
  Customize the placeholder for the cvc field.
- translations.cvc.errors.invalid
  Customize the error message for the cvc field when the value is invalid.
validationObject
Allows you to customize validation logic for the component.
- validation.name.regexRegExp
  A regex pattern that the name must match in order to be considered valid. You can use this option to only allow certain characters.
- validation.cvc.optionalBoolean
  When set to true, the CVC field is treated as optional. The card is considered valid even if no CVC is entered. If a CVC is entered, it is validated as normal. Defaults to false.

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.card.numberstring
  The encrypted card number.
- data.card.brandstring
  The card brand.
- data.card.lastFourstring
  The last four digits of the card number.
- data.card.binstring
  The bin for the card. This will only be present if the number is valid.
- data.card.expiry.monthstring
  The month of the card expiry date.
- data.card.expiry.yearstring
  The year of the card expiry date.
- data.card.cvcstring
  The encrypted CVC.
- data.card.namestring
  The card holder name.
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.card.numberstring
  The encrypted card number.
- data.card.brandstring
  The card brand.
- data.card.lastFourstring
  The last four digits of the card number.
- data.card.binstring
  The bin for the card. This will only be present if the number is valid.
- data.card.expiry.monthstring
  The month of the card expiry date.
- data.card.expiry.yearstring
  The year of the card expiry date.
- data.card.cvcstring
  The encrypted CVC.
- data.card.namestring
  The card holder name.
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.
- data.card.numberstring
  The encrypted card number.
- data.card.brandstring
  The card brand.
- data.card.lastFourstring
  The last four digits of the card number.
- data.card.binstring
  The bin for the card. This will only be present if the number is valid.
- data.card.monthstring
  The month of the card expiry date.
- data.card.yearstring
  The year of the card expiry date.
- data.card.cvcstring
  The encrypted CVC.
- data.card.firstNamestring
  The card holder first name if one was detected.
- data.card.lastNamestring
  The card holder last name if one was detected.

card.on('validate')

Fired when card.validate() is called. Use this to read the validation result after triggering programmatic validation.

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

Callback Parameters

data.cardObject
Information about the card, including metadata, the encrypted number, and CVC.
- data.card.numberstring
  The encrypted card number.
- data.card.brandstring
  The card brand.
- data.card.lastFourstring
  The last four digits of the card number.
- data.card.binstring
  The BIN for the card. Only present when a valid card numbers is entered.
- data.card.expiry.monthstring
  The month of the card expiry date.
- data.card.expiry.yearstring
  The year of the card expiry date.
- data.card.cvcstring
  The encrypted CVC.
- data.card.namestring
  The cardholder name.
data.isValidBoolean
Whether all fields are currently valid.
data.isCompleteBoolean
Whether all required fields are currently valid.
data.errorsRecord<string, string>
Validation errors for each field.

card.on('focus')

Fired when a card field receives focus.

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

Callback Parameters

event.fieldstring
The field that received focus. One of name, number, expiry, or cvc.
event.dataObject
The current card payload at the time of the event. Same shape as the change event payload.

card.on('blur')

Fired when a card field loses focus.

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

Callback Parameters

event.fieldstring
The field that lost focus. One of name, number, expiry, or cvc.
event.dataObject
The current card payload at the time of the event.

card.on('keyup')

Fired on a key-up event within a card field.

1card.on("keyup", (event) => {
2  console.log(event.field);
3});

Callback Parameters

event.fieldstring
The active field. One of name, number, expiry, or cvc.
event.dataObject
The current card payload at the time of the event.

card.on('keydown')

Fired on a key-down event within a card field.

1card.on("keydown", (event) => {
2  console.log(event.field);
3});

Callback Parameters

event.fieldstring
The active field. One of name, number, expiry, or cvc.
event.dataObject
The current card payload at the time of the event.

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.
autoProgressBoolean
If set to true, the component automatically moves focus to the next field when the current field is complete.
autoCompleteObject
Controls browser autocomplete behavior per field.
- autoComplete.nameBoolean
  Enable browser autocomplete for the name field.
- autoComplete.numberBoolean
  Enable browser autocomplete for the card number field.
- autoComplete.expiryBoolean
  Enable browser autocomplete for the expiry field.
- autoComplete.cvcBoolean
  Enable browser autocomplete for the CVC field.
acceptedBrandsstring[]
Restricts the component to only accept the specified card brands. If not provided, all brands are accepted. Possible values are american-express, visa, mastercard, discover, jcb, diners-club, unionpay, maestro, mir, elo, hipercard, hiper, szep, uatp, rupay. Custom brands defined using customBrands are accepted regardless of this list.
customBrandsCustomBrand[]
An array of custom card brand definitions created with brands.create. Custom brands are always accepted, even when acceptedBrands is set.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
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.
defaultValuesObject
Sets default values for card fields.
- defaultValues.namestring
  Default value for the cardholder name field.
allow3DigitAmexCVCBoolean
If set to false, rejects 3-digit CVCs for American Express cards and requires a 4-digit CVC. Defaults to true.
translationsObject
Allows you to customize the text shown inside of the component.
- translations.name.label
  Customize the label for the name field.
- translations.name.placeholder
  Customize the placeholder for the name field.
- translations.name.errors.invalid
  Customize the error message for the name field when the value is invalid.
- translations.name.errors.regex
  Customize the error message for when the name field fails regex validation.
- translations.number.label
  Customize the label for the number field.
- translations.number.placeholder
  Customize the placeholder for the number field.
- translations.number.errors.invalid
  Customize the error message for the number field when the value is invalid.
- translations.expiry.label
  Customize the label for the expiry field.
- translations.expiry.placeholder
  Customize the placeholder for the expiry field.
- translations.expiry.errors.invalid
  Customize the error message for the expiry field when the value is invalid.
- translations.cvc.label
  Customize the label for the cvc field.
- translations.cvc.placeholder
  Customize the placeholder for the cvc field.
- translations.cvc.errors.invalid
  Customize the error message for the cvc field when the value is invalid.
validationObject
Allows you to customize validation logic for the component.
- validation.name.regexRegExp
  A regex pattern that the name must match in order to be considered valid. You can use this option to only allow certain characters.
- validation.cvc.optionalBoolean
  When set to true, the CVC field is treated as optional. The card is considered valid even if no CVC is entered. If a CVC is entered, it is validated as normal. Defaults to false.

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

brands.create

Creates a custom card brand definition that can be passed to the customBrands option on ui.card. 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});

Parameters

nameRequiredstring
A unique identifier for the brand. This value is returned in the localBrands array of the card change payload.
optionsRequiredObject
Configuration for the custom brand.
- options.numberValidationRulesRequiredObject
  Rules used to validate card numbers for this brand.
- options.securityCodeValidationRulesRequiredObject
  Rules used to validate the CVC for this brand.
- options.iconSrcstring
  A URL for the brand's icon. Displayed in the card component when a matching card number is entered.

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

Parameters

theme
Allows you to customize the component's appearance. See Custom Styling for more information.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
lengthnumber
The number of PIN digits to collect. Defaults to 4, maximum 10.
autoFocusBoolean
If set to true, the component automatically focuses when it mounts.
mode"numeric" | "alphanumeric"
If set to "alphanumeric", the PIN field will accept letters as well as digits. Defaults to "numeric".
inputType"number" | "text" | "password"
Sets the type attribute of the underlying input elements used to capture the PIN. Defaults to "number".

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

Callback Parameters

data.valuestring | null
The encrypted PIN value, or null if the field is empty.
data.isCompleteBoolean
Whether the PIN field is complete.

pin.on('complete')

Fired when the user enters all PIN digits.

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

Callback Parameters

data.valuestring | null
The encrypted PIN value.
data.isCompleteBoolean
Whether the PIN field is complete.

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

Parameters

sessionRequiredstring
The 3D Secure session ID. A 3D Secure session can be created using the Create 3D Secure Session API endpoint.
options
Configuration options for the ThreeDSecure component.
- options.colorSchemestring
  Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- options.themeObject
  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.
- options.size{ width: string, height: 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.
- options.failOnChallengeBoolean | () => Boolean | () => 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: "300px",
4    height: "400px",
5  },
6});

Parameters

colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
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: string, height: 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 | () => Boolean | () => 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.colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
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.
- format.regexRequiredRegExp
  The regex statment to match against the value.
- format.replaceRequiredstring
  The text to replace the value with. You can use $ to reference matched regex groups.

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.textstring
The text to display on the button.
options.iconstring
A URL for an icon to display on the button.
options.colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
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.
- format.regexRequiredRegExp
  The regex statment to match against the value.
- format.replaceRequiredstring
  The text to replace the value with. You can use $ to reference matched regex groups.

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.typepayment | 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.
- lineItem.amountRequiredstring
  The line item amount in smallest currency unit.
- lineItem.labelRequirednumber
  Description of the line item.
options.requiredRecipientDetailsstring[]
Optional array of recipient details required for collection on a disbursement transaction. Possible values: name, email, phone, address.
options.merchantCapabilitiesstring[]
Optional array of Apple Pay merchant capabilities for disbursement transactions. When omitted, defaults to supports3DS, and adds supportsInstantFundsOut when instantTransfer is set. Supported values: supports3DS, supportsEMV, supportsCredit, supportsDebit, supportsInstantFundsOut. On iOS the equivalent is the singular merchantCapability field on DisbursementTransaction.
options.managementURLstring
URL for managing the recurring payment subscription. Required when type is recurring.
options.billingAgreementstring
Description of the billing agreement shown to the user. Required when type is recurring.
options.descriptionstring
Description of the recurring payment. Required when type is recurring.
options.regularBillingobject
Billing details for the recurring charge. Required when type is recurring.
- regularBilling.amountRequiredstring
  The billing amount as a decimal string (e.g., "2.13").
- regularBilling.labelRequiredstring
  Description of the billing charge.
- regularBilling.recurringPaymentStartDateRequiredDate
  The start date for the recurring payment.
- regularBilling.recurringPaymentIntervalUnitminute | hour | day | week | month | year
  The interval unit for the recurring payment frequency. The default value is "month".
- regularBilling.recurringPaymentIntervalCountnumber
  The number of interval units between each recurring charge. The default value is 1.
options.trialBillingobject
Optional trial billing details for the recurring payment.
- trialBilling.amountRequiredstring
  The trial billing amount as a decimal string (e.g., "0.99").
- trialBilling.labelRequiredstring
  Description of the trial billing charge.
- trialBilling.trialPaymentStartDateRequiredDate
  The start date for the trial period.

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

Parameters

transactionRequiredTransaction
The transaction object created with transactions.create.
optionsRequiredObject
Configuration options for the Apple Pay button.
- options.processRequiredFunction
  Callback function called when payment is authorized. Receives encrypted payment data and helper functions.
- options.typestring
  Apple Pay button type. Possible values: add-money, book, buy, check-out, continue, contribute, donate, order, pay, plain, reload, rent, set-up, subscribe, support, tip, top-up
- options.stylestring
  Apple Pay button style. Possible values: black, white, white-outline
- options.localestring
  An ISO-639-1 code for localization.
- options.paddingstring
  The padding around the button as a CSS string with units (e.g., "10px").
- options.borderRadiusstring | number
  The border radius of the button. This can be a string with units (e.g., "10px") or a number (e.g., 10).
- options.size{ width: number | string, height: number | string }
  An object defining the width and height of the button.
- options.allowedCardNetworksstring[]
  An array of supported card networks. Supported card networks: AMEX, DISCOVER, ELECTRON, ELO, ELO_DEBIT, INTERAC, JCB, MAESTRO, MASTERCARD, VISA
- options.requestPayerDetailsstring[]
  An array of payer details to request. Possible values: name, email, phone.
- options.requestBillingAddressboolean
  Whether to request billing address information.
- options.requestShippingboolean
  Whether to request shipping information.
- options.onPaymentMethodChangeFunction
  Called when the user changes their payment method. Receives the new payment method and returns a promise resolving to an updated amount and optional lineItems. Requires requestBillingAddress: true to receive billing address data.
- options.onShippingAddressChangeFunction
  Called when the user changes their shipping address. Receives the new address and returns a promise resolving to an updated amount and optional lineItems. Requires requestShipping: true.
- options.prepareTransactionFunction
  Called before the Apple Pay modal is shown. Use this to perform async logic (e.g., fetch a discount) and return an updated amount and optional lineItems.
- options.appleMerchantIdstring
  Optional Apple Pay merchant identifier for the payment sheet. Defaults to merchant.com.evervault.{merchantId}, which works with Evervault's domain verification and merchant-session flow. A custom value is only used by the browser to open the Apple Pay sheet. It doesn't change merchant validation — that still uses Evervault's registered identifier unless separately configured with Apple for your domain.
- options.paymentOverridesObject
  Advanced overrides for the underlying Payment Request.
- options.disbursementOverridesObject
  Advanced overrides for disbursement Payment Requests.

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.

The paymentDataType field reflects the Apple token format returned by the credentials API (for example 3DSecure). The transactionType field indicates the transaction category: oneOff for one-time payments, recurring for subscriptions, or disbursement for fund-out flows.

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

Parameters

transactionRequiredTransaction
The transaction object created with transactions.create.
optionsRequiredObject
Configuration options for the Google Pay button.
- options.processRequiredFunction
  Callback function called when payment is authorized. Receives encrypted payment data and helper functions.
- options.typestring
  Google Pay button type. Possible values: book, buy, checkout, donate, order, pay, plain, subscribe, top-up
- options.colorstring
  Google Pay button color. Possible values: black, white
- options.localestring
  An ISO-639-1 code for localization.
- options.size{ width: number | string, height: number | string }
  An object defining the width and height of the button.
- options.allowedAuthMethodsstring[]
  Allowed authentication methods. With CRYPTOGRAM_3DS set, users on mobile can authenticate with their fingerprint which acts as a Strong Customer Authentication and so a cryptogram and ECI value are returned. Users on web cannot authenticate with their fingerprint so only the PAN is returned. Possible values: PAN_ONLY, CRYPTOGRAM_3DS
- options.allowedCardNetworksstring[]
  An array of supported card networks. Supported card networks: AMEX, DISCOVER, ELECTRON, ELO, ELO_DEBIT, INTERAC, JCB, MAESTRO, MASTERCARD, VISA
- options.colorSchemestring
  Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- options.emailRequiredboolean
  When set to true, the user will be required to provide their email address.
- options.billingAddressboolean | Object
  Request billing address information.

The object passed to options.process includes metadata on card when present. Optional card.paymentMethodType matches Google Pay's funding source for the selected card when available. See the Google Pay guide.

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