Evervault React.js SDK

The Evervault React.js SDK is a toolkit for encrypting data on the client. Using the Evervault React.js SDK means your customer's data never leaves their device unencrypted.

Getting Started

Before starting with the Evervault React SDK, you will need to create an account and a team.

Documentation

See the Evervault React.js SDK documentation.

Installation

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

# Using npm
npm install @evervault/react

# Using yarn
yarn add @evervault/react

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.

import { EvervaultProvider } from "@evervault/react";
import ChildComponent from "../ChildComponent";
export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      <ChildComponent />
    </EvervaultProvider>
  );
}

Encrypt a string

Once you've added the <EvervaultProvider>, you can use the useEvervault() hook in its children. The useEvervault() hook returns an initialized instance of the JavaScript SDK, which includes the encrypt() function.

import { useState } from "react";
import { useEvervault } from "@evervault/react";

export default function ChildComponent() {
  const evervault = useEvervault();
  const [message, setMessage] = useState("");

  const handleSubmit = async (e) => {
    e.preventDefault();
    const encryptedMessage = await evervault.encrypt(message);
    alert(encryptedMessage);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button>Submit</button>
    </form>
  );
}

Reference

<EvervaultProvider />

The EvervaultProvider component exposes the useEvervault() hook to any nested components.

<EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
  <App />
</EvervaultProvider>

Props

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.

const evervault = useEvervault();

evervault.encrypt(data)

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.

const evervault = useEvervault();

const encrypted = await evervault.encrypt("Hello, world!");

<EvervaultInput />

Use Evervault Inputs to securely collect encrypted cardholder data. Evervault Inputs are served within an iFrame retrieved directly from Evervault’s PCI-compliant infrastructure, which can reduce your PCI DSS compliance scope to the simplest form (SAQ A).

Evervault Inputs also support themes and custom styles so you can customise how Inputs looks in your UI.

Props

Retrieving card data

To access the encrypted card data, you must pass an onChange handler. This function will be called any time the card data is updated and is passed an object with the encrypted card details as well as validation information.

function Payment() {
  const handleChange = ({ encryptedCard, isValid }) => {
    if (isValid) {
      console.log(encryptedCard);
    }
  };

  return <EvervaultInput onChange={handleChange} />;
}

onChange callback params

The onChange callback will be passed the following object as a parameter.

{
  "encryptedCard": {
    "type": "visa_credit",
    "number": "ev:encrypted:abc123",
    "cvc": "ev:encrypted:def456",
    "expMonth": "01",
    "expYear": "23"
    "lastFour": "1234"
  },
  "isValid": true,
  "isPotentiallyValid": true,
  "isEmpty": false,
  "error": {
    "type": "invalid_pan",
    "message": "The credit card number you entered was invalid"
  }
}

Localization

The iFrame can be localized on initialization by providing a set of labels in the config.

const config = {
  cardNumberLabel: 'Numéro de carte:',
  expirationDateLabel: 'Date d'expiration:',
  securityCodeLabel: 'Code de sécurité:'
}

<EvervaultInput onChange={handleChange} config={config} />

Custom Fonts

A custom font can be loaded from Google's Fonts API and the font-family set with the fontFamily config paramerter

const config = {
  fontUrl: 'https://fonts.googleapis.com/css2?family=Poppins:wght@100;800&display=swap',
  fontFamily: 'Poppins, sans-serif',
  inputFontSize: '20px',
  inputBoxShadow: '2px 2px 2px 1px rgba(0, 0, 255, .2)',
  labelFontSize: '13px',
  labelWeight: '400'
}

<EvervaultInput onChange={handleChange} config={config} />

iFrame loading status

If you need to wait for the iFrame that serves Inputs to load before doing some action, you can used the onInputsLoad prop callback:

<EvervaultInput
  onInputsLoad={() => {
    console.log("Inputs has loaded!");
  }}
/>

<Card />

Default. Mounts and shows immediately.

<Card />

With preload. Boots the card hidden as soon as it mounts, then call show() via a ref when the user reaches the payment step. Useful when the card sits behind a later checkout step.

const cardRef = useRef(null);

<Card ref={cardRef} preload />;

// Later.
cardRef.current?.show();

<EvervaultReveal />

Use Evervault Reveal to show encrypted card details to show your users their encrypted card details in plaintext in a secure iFrame hosted by Evervault. Before using Reveal you'll first have to create a Relay to decrypt the card details; Reveal expects to receive the card data from the Relay as a JSON object with the schema below.

Note: It is important that the endpoint that you create sets the applicable CORS headers so that it can be accessed from the Inputs iFrame. Otherwise your requests will fail!

{
  "cardNumber": "string | number",
  "cvv": "string | number",
  "expiry": "string | number"
}

Once you have your endpoint that returns the encrypted card data, you'll need to create an Evervault Inbound Relay that will decrypt the encrypted card data as is passes through it, before it gets to the iFrame. Once you have created your Relay you can add the component to your React app.

export default function Reveal() {
  const request = {
    url: "https://example-com.relay.evervault.com",
    method: "GET",
    headers: {
      Authorization: "Bearer ey...",
    },
  };

  return (
    <main>
      <EvervaultReveal request={request}></EvervaultReveal>
    </main>
  );
}

The only required field is request which takes an object that supports all of the same fields as a Javascript Request Object. The URL must be the Evervault Inbound Relay you configured earlier.

Props

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/evervault/evervault-react.

Feedback

Questions or feedback? Let us know.