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

The EvervaultProvider accepts a ref that exposes a reload() method that you can use to reload the script if it fails.

Ref Methods

reload() => void
Attempts to reload the Evervault script. Typically called in response to an onLoadError event.

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.
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.
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.
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. Use evervault.brands.create from the browser SDK to create them. 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.
translationsObject
Allows you to customize the translations 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.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 the validation logic of 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.
onChange(payload: Object) => void
Triggered whenever the component's state is updated.
- card.nameString
  The card holder name.
- card.numberString
  The encrypted card number. This will only be present if the number is valid.
- card.brandString
  The brand that issued the card.
- card.lastFourString
  The last 4 digits of the card. This will only be present if the number is valid.
- card.binString
  The bin for the card. This will only be present if the number id valid.
- card.expiry.monthString
  The month for the card expiry field.
- card.expiry.yearString
  The year for the card expiry field.
- card.cvcString
  The encrypted card CVC.
- card.errorsObject
  Validation errors related to the card details.
- card.isValidBoolean
  Whether or not there are any errors shown in the component.
- card.isCompleteBoolean
  Whether or not all of the fields have been filled out successfully with valid values.
onComplete(payload: Object) => void
Triggered when the component is complete.
- card.nameString
  The card holder name.
- card.numberString
  The encrypted card number. This will only be present if the number is valid.
- card.brandString
  The brand that issued the card.
- card.lastFourString
  The last 4 digits of the card. This will only be present if the number is valid.
- card.binString
  The bin for the card. This will only be present if the number id valid.
- card.expiry.monthString
  The month for the card expiry field.
- card.expiry.yearString
  The year for the card expiry field.
- card.cvcString
  The encrypted card CVC.
- card.errorsObject
  Validation errors related to the card details.
- card.isValidBoolean
  Whether or not there are any errors shown in the component.
- card.isCompleteBoolean
  Whether or not all of the fields have been filled out successfully with valid values.
onValidate(payload: Object) => void
Triggered when the component is programmatically validated with the validate() ref method.
- card.nameString
  The card holder name.
- card.numberString
  The encrypted card number. This will only be present if the number is valid.
- card.brandString
  The brand that issued the card.
- card.lastFourString
  The last 4 digits of the card. This will only be present if the number is valid.
- card.binString
  The bin for the card. This will only be present if the number id valid.
- card.expiry.monthString
  The month for the card expiry field.
- card.expiry.yearString
  The year for the card expiry field.
- card.cvcString
  The encrypted card CVC.
- card.errorsObject
  Validation errors related to the card details.
- card.isValidBoolean
  Whether or not there are any errors shown in the component.
- card.isCompleteBoolean
  Whether or not all of the fields have been filled out successfully with valid values.
onSwipe(payload: Object) => void
Triggered when the component is swiped.
- brandString
  The brand that issued the card.
- localBrandsString[]
  The brands that are supported by the component.
- numberString
  The card number.
- expiryObject
  The expiry date of the card.
- firstNameString
  The first name of the card holder.
- lastNameString
  The last name of the card holder.
- lastFourString
  The last 4 digits of the card.
- binString
  The bin for the card.
onFocus(event: { field: string, data: Object }) => void
Triggered when a card field receives focus. The field property identifies which field received focus (name, number, expiry, or cvc).
onBlur(event: { field: string, data: Object }) => void
Triggered when a card field loses focus. The field property identifies which field lost focus (name, number, expiry, or cvc).
onKeyUp(event: { field: string, data: Object }) => void
Triggered on a key-up event within a card field. The field property identifies the active field.
onKeyDown(event: { field: string, data: Object }) => void
Triggered on a key-down event within a card field. The field property identifies the active field.
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.

The Card component accepts a ref that exposes the following methods:

Ref methods

validate() => void
Programmatically triggers validation on all card fields and emits a validate event with the current payload. Use this with the onValidate callback to implement submit-time validation.

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.
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.
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.
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.
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.
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.
- regexString
  The regex statement to match against the value.
- replaceString
  The text to replace the value with. You can use $ to reference matched regex groups.

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.
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.
formatObject
Allows you to use regex matching to format the field value.
- regexString
  The regex statement to match against the value.
- replaceString
  The text to replace the value with. You can use $ to reference matched regex groups.
onCopy() => void
A callback function that is called when the button is clicked.

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.
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.
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.
inputType"number" | "text" | "password"
Sets the type attribute of the underlying input elements used to capture the pin. Defaults to "number".
onChange(payload: Object) => void
Triggered whenever the component's state is updated.
- valueString
  The encrypted pin number.
- isCompleteBoolean
  Whether or not the pin number field is complete.
onComplete(payload: Object) => void
Triggered when the pin number field has been fully filled out by the user.
- valueString
  The encrypted pin number.
- isCompleteBooleanBoolean
  Whether or not the pin number field is complete.
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.

.brands.create()

Creates a custom card brand definition that can be passed to the customBrands prop on Card. Use this to add support for card networks that aren't included in Evervault's built-in brand list.

1const acmeBrand = evervault.brands.create("acme-card", {
2  numberValidationRules: {
3    ranges: [9900, [88000, 88999]],
4    lengths: [16],
5  },
6  securityCodeValidationRules: {
7    lengths: [3],
8  },
9})

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.

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

threeDSecure.update()

The update function updates the options passed to the active 3D Secure instance without restarting the authentication flow.

Parameters

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

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;