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.applePay(transaction, options)

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

evervault.ui.googlePay(transaction, options)

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