JavaScript SDK

You can use our JavaScript SDK to:

• Encrypt data client-side
• Collect or display senitive data with UI Components

Quickstart

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.

Using Evervault as a module

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.

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.

Initialize

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

Full example

Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using your own Team ID and App ID), run it in your own environment and run the encryption and decryption for yourself.

Reference

Evervault(appId, teamId)

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

Asynchronous initialization

You can also initialize the SDK asynchronously using the init method.

evervault.encrypt(data)

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.

evervault.decrypt(token, data)

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.

evervault.ui.card(options)

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

card.mount()

Mounts the component to a given DOM node.

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.

card.on('complete')

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

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.

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.

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.

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.

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.

card.unmount()

Removes the component from the DOM.

evervault.ui.threeDSecure(session, options)

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.

threeDSecure.mount(selector)

Mounts the component to the DOM. 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.

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.

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.

threeDSecure.on('error')

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

threeDSecure.update(options)

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.

threeDSecure.unmount()

Removes the component from the DOM.

Frictionless-only 3D-Secure

In some cases, you may want to avoid adding friction into the payment process by automatically failing 3D-Secure when a challenge is requested. You can do this by setting the failOnChallenge option to true. This will prevent the challenge from being shown to the user and will automatically mark the 3D Secure Session as failed.

Alternatively, you can pass a function to the failOnChallenge option to determine if the challenge should be shown on a per transaction basis.

evervault.ui.pin(options)

Initializes a Pin UI Component. The Pin component allows you to collect and encrypt pin numbers in a completely PCI-compliant environment.

pin.mount()

Mounts the component to a given DOM node.

pin.on('change')

Subscribe to changes made to the Pin component. The encrypted pin can be accessed from the payload passed to the callback.

pin.on('complete')

The 'complete' event will be fired once the pin number field has been fully filled out by the user.

pin.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.

pin.on('error')

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

evervault.transactions.create(details)

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

evervault.ui.googlePay(transaction, options)

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

Google Pay Events

googlePay.on('ready')

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

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.

evervault.ui.applePay(transaction, options)

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

Apple Pay Events

applePay.on('ready')

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

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.

evervault.ui.reveal(request)

Initializes a Reveal UI Component. 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.

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.

reveal.on('error')

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

reveal.text(JSONPath, options)

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

text.mount()

Mounts the Reveal Text component to a given DOM node.

text.unmount()

Removes the Text Component from the DOM.

reveal.copyButton(JSONPath, options)

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

copyButton.mount()

Mounts the component to a given DOM node.

copyButton.on("copy")

The "copy" event will be fired when ever the user clicks the button and copies the value to their clipboard.

copyButton.unmount()

Removes the component from the DOM.

evervault.ui.themes

Provides access to the built-in UI Component themes. See the UI Components Styling section for more details.

Content Security Policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.