React

Getting Started

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

1npm install @evervault/react

Once installed, Initialize the SDK by wrapping your application with the EvervaultProvider component.

1import { EvervaultProvider } from "@evervault/react";
2
3export default function App() {
4  return (
5    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
6      ...
7    </EvervaultProvider>
8  );
9}

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.

1import { useState } from "react";
2import { useEvervault } from "@evervault/react";
3
4export default function ChildComponent() {
5  const evervault = useEvervault();
6  const [message, setMessage] = useState("");
7
8  const handleSubmit = async (e) => {
9    e.preventDefault();
10    const encryptedMessage = await evervault.encrypt(message);
11    alert(encryptedMessage);
12  };
13
14  return (
15    <form onSubmit={handleSubmit}>
16      <input value={message} onChange={(e) => setMessage(e.target.value)} />
17      <button>Submit</button>
18    </form>
19  );
20}

Components

EvervaultProvider

Sets up a client for interacting with Evervault. You must provide a teamId and appId to the provider.

1<EvervaultProvider teamId={String} appId={String}>
2  {children}
3</EvervaultProvider>

Props

teamIdRequiredString
The unique identifier for your Team.
appIdRequiredString
The unique identifier for your App.
onLoadErrorFunction
A callback function that is called if the SDK fails to load.

Card

The Card Component allows you to collect and encrypt card data in a completely PCI-compliant environment. See Card Collection for more information.

1import { Card, themes } from "@evervault/react";
2const theme = themes.clean();
3
4export function Checkout() {
5  const handleChange = (details) => {
6    console.log(details);
7  };
8
9  return (
10    <div>
11      <Card theme={theme} onChange={handleChange} />
12    </div>
13  );
14}

Props

themeObject
The theme to use for the Card. See the styling section 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 the first field when the component is mounted.
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.
redactCVCBoolean
Sets the type attribute of the CVC field to password in order to visually redact the CVC field..
onChange(payload: Object) => void
Triggered whenever the component's state is updated.
onComplete(payload: Object) => void
Triggered when the component is complete.
onSwipe(payload: Object) => void
Triggered when the component is swiped.
onReady() => void
Triggered when the component has loaded and is ready to be used.
onError() => void
Triggered when the component encounters an error and fails to load.
translationsObject
Allows you to customize the translations of the component.

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.

1import { ThreeDSecure } from "@evervault/react";
2
3export function MyComponent() {
4  const handleSuccess = () => {
5    console.log("3D Secure authentication complete");
6  };
7
8  return (
9    <ThreeDSecure session="tds_visa_123456789" onSuccess={handleSuccess} />
10  );
11}

Props

sessionRequiredString
The 3D Secure session ID. A 3D Secure session can be created using the API.
themeObject
Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
size{ width: number, height: number }
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.
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.
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.
onErrorFunction
The error event will be fired if the component fails to load.
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.

Reveal

The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. See Card Reveal for more information.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.Text path="$.card.number" />
12      <Reveal.CopyButton path="$.card.number" text="Copy Number" />
13    </Reveal>
14  );
15}

Props

requestRequiredRequest
The request to use to fetch the encrypted data.
onReadyFunction
Triggered when the component has fully loaded and is ready to be shown.
onErrorFunction
Triggered when 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.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.Text path="$.user.pin" />
12    </Reveal>
13  );
14}

Props

themeObject
Allows you to completely customize the appearance of the component.
pathRequiredString
A JSON path selector for the response field you want to display.
formatObject
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.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.CopyButton path="$.card.number" />
12    </Reveal>
13  );
14}

Props

pathRequiredString
A JSON path selector for the response field you want to copy.
themeObject
Allows you to completely customize the appearance of the component.
onCopyFunction
A callback function that is called when the button is clicked.
formatObject
Allows you to use regex matching to format the field value.

Creates a Pin component which allows you to collect and encrypt pin numbers in a completely PCI-compliant environment.

1import { Pin, themes } from "@evervault/react";
2const theme = themes.clean();
3
4export function MyComponent() {
5  const handleChange = (details) => {
6    console.log(details);
7  };
8
9  return (
10    <div>
11      <Pin theme={theme} onChange={handleChange} />
12    </div>
13  );
14}

Props

themeObject
The theme to use for the Pin.
autoFocusBoolean
If set to true, the component will automatically steal focus when it mounts.
lengthNumber
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.
onReadyFunction
Triggered when the component has fully loaded and is ready to be shown.
onErrorFunction
Triggered when the component fails to load. If you want to respond to validation errors you should use the change event instead.

Hooks

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.

1const evervault = useEvervault();

.encrypt()

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products. 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.

1function MyComponent() {
2  const evervault = useEvervault();
3
4  const handleEncrypt = async () => {
5    const encrypted = await evervault.encrypt("Hello, world!");
6    console.log(encrypted);
7  };
8
9  return <button onClick={handleEncrypt}>Encrypt</button>;
10}

Parameters

dataRequiredString | Object | Array | File | Blob
The data to encrypt.

.decrypt()

Allows you to decrypt a previously encrypted piece of data using a client side 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.

1const evervault = useEvervault();
2const data = await evervault.encrypt("Hello, world!");
3const decrypted = await evervault.decrypt("[client-side-token]", data);

Parameters

tokenRequiredString
A valid client-side token with permissions to decrypt the data.
dataRequiredString | Object
The encrypted data to decrypt.

useThreeDSecure

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.

See 3D Secure for more information.

1import { Card, useThreeDSecure } from "@evervault/react";
2import { createThreeDSSession, finalizePayment } from "./api";
3
4function Checkout() {
5  const threeDSecure = useThreeDSecure();
6
7  const handlePay = async () => {
8    const session = await createThreeDSSession();
9    threeDSecure.start(session, {
10      onSuccess: () => {
11        finalizePayment(session);
12      },
13    });
14  };
15
16  return (
17    <>
18      <Card />
19      <button onClick={handlePay}>Pay</button>
20    </>
21  );
22}

Options

themeObject
Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
size{ width: number, height: number }
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.start()

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

Parameters

sessionRequiredString
The 3D Secure session ID. A 3D Secure session can be created using the 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.onErrorFunction
The error event will be fired if the component fails to load.
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.

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.

1script-src https://js.evervault.com;
2connect-src https://keys.evervault.com https://api.evervault.com;
3frame-src https://ui-components.evervault.com;

React

Getting Started

Encrypting Data

Components

EvervaultProvider

Props

Card

Props

ThreeDSecure

Props

Reveal

Props

Reveal.Text

Props

Reveal.CopyButton

Props

Pin

Props

Hooks

useEvervault

.encrypt()

Parameters

.decrypt()

Parameters

useThreeDSecure

Options

threeDSecure.start()

Parameters

Content Security Policy (CSP)

On this page