You can use our React.js SDK to:

Encrypt data client-side
Collect or display card data with UI Components
Perform 3D Secure authentication

Quickstart

Install SDK

Our React.js SDK is distributed via npm, and can be installed using your preferred package manager.

Initialize SDK

Once installed, initialize the React.js SDK with your Team and App ID found in the Evervault Dashboard.

Use the <EvervaultProvider> component as a provider for your app.

Once you've added the <EvervaultProvider>, you can access the useEvervault() hook in its children. The useEvervault() hook returns an initialized instance of the JavaScript SDK, which includes the encrypt() function. The encrypt() function can can be used to encrypt plaintext data in your application.

Reference

<EvervaultProvider />

The EvervaultProvider component exposes the useEvervault() hook to any nested components. UI Components (<Card/>, <Pin/> and <Reveal/>) can also be used in children of the provider

Props

TeamIdRequiredString

The unique identifier for your Team. It's found in Team Settings.

appIdRequiredString

The unique identifier for your App. It's found in App Settings.

useEvervault()

The useEvervault hook is accessible in children of the EvervaultProvider, and returns an initialized instance of the Evervault JavaScript SDK. One of the functions included in the returned object is encrypt(), which can be passed any plaintext data structure.

evervault.encrypt(data)

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our Primitives. It is accessible on the returned value from the useEvervault() hook. To encrypt data using the React.js SDK, simply pass a String or an Object into the evervault.encrypt() function.

The encrypted data can be passed to your server and stored in your database as normal. It can also be used with any of Evervault’s other services.

Parameters

dataRequiredString | Object

The data to encrypt.

evervault.decrypt(token, data)

Decrypts data previously encrypted with the encrypt() function or through Relay.

The decrypt() function allows you to decrypt previously encrypted data using a token.

The token is a time bound token for decrypting data. 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.

The payload can be any String or Object and it will be returned, decrypted, in the same form.

Parameters

tokenRequiredString

A valid client side token with permissions to decrypt the given data.

dataRequiredString | Object

The data to decrypt.

<Card />

Initializes a Card UI Component. The Card Component allows you to collect and encrypt card data in a completely PCI-compliant environment.

Props

themeTheme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

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 steal focus when it mounts.

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.

onChange(payload: Object) => void

Triggered whenever the component's state is updated.

onComplete(payload: Object) => void

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

onSwipe(payload: Object) => void

Triggered when the component detects a swipe event from a card reader.

onReady() => void

Triggered when the component has fully loaded and is ready to be shown.

onError() => void

Triggered when the component fails to load. If you want to respond to validation errors you should use the change event instead.

translationsObject

Allows you to customize the text shown inside of the component.

useThreeDSecure(options)

The useThreeDSecure hook can be used in combination with the Evervault API to perform 3D Secure authentication. In order to use the hook you must first create a 3D Secure session on your backend and pass it to your frontend. The hook will manage displaying the 3D Secure iframe inside of a modal window and handle the authentication process.

Note: If you want more control over how and where the 3D Secure iframe is displayed you can use the ThreeDSecure component instead.

Options

options.theme

Allows you to customize the appearance of the component. See the Styling section for more details.

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.

Returns

start(session, options)

The start function is used to begin the 3D Secure authentication process.

Arguments

sessionRequiredString

The 3D Secure session ID. A 3D Secure session can be created using the Evervault API.

options.onSuccessFunction

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.

options.onFailureFunction

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.

options.onReadyFunction

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.

options.onErrorFunction

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

<ThreeDSecure />

The ThreeDSecure component can be used instead of the useThreeDSecure hook when you want more control over how and where the 3D Secure iframe is displayed. In order to use the component you must first create a 3D Secure session on your backend.

Note: If you want a simpler way to handle 3D Secure authentication you can use the useThreeDSecure hook instead.

Props

sessionRequiredString

The 3D Secure session ID. A 3D Secure session can be created using the Evervault API.

theme

Allows you to customize the appearance of the component. See the Styling section for more details.

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>

onSuccessFunction

onFailureFunction

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.

onReadyFunction

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.

onErrorFunction

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

<Pin />

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

Props

themeTheme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

autoFocusBoolean

If set to true, the component will automatically steal focus when it mounts.

lengthNumber | Default: 4

Change the length of the pin number.

modenumeric | alphanumeric

If set to 'alphanumeric' the pin number will also accept letters as input.

onChange(payload: Object) => void

Triggered whenever the component's state is updated.

onComplete(payload: Object) => void

Triggered when the pin number field has been fully filled out by the user.

onReady() => void

Triggered when the component has fully loaded and is ready to be shown.

onError() => void

Triggered when the component fails to load. If you want to respond to validation errors you should use the change event instead.

<Reveal />

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 from 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!

Props

requestRequiredRequest

The request objet for fetching the data.

onReady() => void

Triggered when the request has been made and all child components are ready to be shown.

onError() => void

Triggered when the request fails, or the component fails to load.

<Reveal.Text />

Creates a Reveal Text consumer component. The Reveal Text consumer allows you to render a selected field from the request response. This component must be rendered as a child of the Reveal component.

Props

pathRequiredString

A JSON path selector for the response field you want to display.

themeTheme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

format

Allows you to use regex matching to format the field value.

<Reveal.CopyButton />

Creates a Reveal Copy Button consumer component. This renders a button which when clicked will copy a response field to the users clipboard. This component must be rendered as a child of the Reveal component.

Props

pathRequiredString

A JSON path selector for the response field you want to display.

themeTheme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

onCopy() => void

Triggered when the user clicks the button and copies the value to their clipboard.

format

Allows you to use regex matching to format the field value.

themes

The themes export 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.