Guides

React.js SDK

You can use our React.js SDK to:

  • Encrypt data client-side
  • Collect or display card data with UI Components

Quickstart

Install SDK

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

claude:~$
# 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.

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

Encrypt a string

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.

1
import { useState } from 'react';
2
import { useEvervault } from '@evervault/react';
3
4
export 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
}

Reference

<EvervaultProvider />

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

1
<EvervaultProvider teamId={String} appId={String} />
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.

1
const evervault = useEvervault();

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.

1
const evervault = useEvervault();
2
3
const encrypted = await evervault.encrypt('Hello, world!');
Parameters
dataRequiredString | Object

The data to encrypt.


<EvervaultInput />

The <EvervaultInput> component makes it easy to use Evervault's Inputs UI Component in your React application. Inputs make it easy to collect encrypted cardholder data in a completely PCI-compliant environment.

Inputs is 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).

Simply include the component in your JSX to get started.

The component also supports themes and custom styles so you can customise how Inputs looks in your UI.

Props
onChangeRequiredFunction

A function that is called whenever the submission changes.

onInputsLoadFunction

A function that is called when the iFrame that serves Inputs has loaded.

configString | Object

A theme string (supported: default, minimal or material), or a config object for custom styles.

Retrieving card data

There are two ways of accessing encrypted card data once it has been entered.

In each case, a cardData object containing details about the card data your user has entered is returned.

You can see the format of this object below:

1
{
2
"card": {
3
"type": "visa_credit",
4
"number": "ev:encrypted:abc123",
5
"cvc": "ev:encrypted:def456",
6
"expMonth": "01",
7
"expYear": "23"
8
},
9
"isValid": true,
10
"isPotentiallyValid": true,
11
"isEmpty": false,
12
"error": {
13
"type": "invalid_pan",
14
"message": "The credit card number you entered was invalid"
15
}
16
}

Card data can be retrieved in one of the following two ways:

onChange()

This option is best when you are looking to handle the card values in realtime, like displaying validation errors as a user is inputting their card data. The callback function is run every time your user updates the card data.

1
<EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
2
<div className="App">
3
<EvervaultInput
4
onChange={(encryptedCard) => setEncryptedCard(encryptedCard)}
5
/>
6
</div>
7
</EvervaultProvider>

Localization

The iFrame can be localized on initialization by providing a set of labels in the config. The labels can then be updated as required using the setLabels method.

1
const config = {
2
cardNumberLabel: 'Numéro de carte:',
3
expirationDateLabel: 'Date d'expiration:',
4
securityCodeLabel: 'Code de sécurité:'
5
}
6
7
<EvervaultProvider teamId='<TEAM_ID>' appId='<APP_ID>'>
8
<div className="App">
9
<EvervaultInput onChange={(encryptedCard) => setEncryptedCard(encryptedCard)} config={config} />
10
</div>
11
</EvervaultProvider>
labels.cardNumberLabelString

The label for the card number input

labels.expirationDateLabelString

The label for the expiration date input

labels.securityCodeLabelString

The label for the security code input

labels.expirationDatePlaceholderString

The placeholder for the expiration date input

labels.invalidCardNumberLabelString

The message shown on an invalid card number

labels.invalidExpirationDateLabelString

The message shown on an invalid expiration date

labels.invalidSecurityCodeLabelString

The message shown on an invalid security code

Custom Fonts

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

1
const config = {
2
fontUrl: 'https://fonts.googleapis.com/css2?family=Poppins:wght@100;800&display=swap',
3
fontFamily: 'Poppins, sans-serif',
4
inputFontSize: '20px',
5
inputBoxShadow: '2px 2px 2px 1px rgba(0, 0, 255, .2)',
6
labelFontSize: '13px',
7
labelWeight: '400'
8
}
9
10
<EvervaultProvider teamId='<TEAM_ID>' appId='<APP_ID>'>
11
<div className="App">
12
<EvervaultInput onChange={(encryptedCard) => setEncryptedCard(encryptedCard)} config={config} />
13
</div>
14
</EvervaultProvider>
config.fontUrlString

Load a custom font with the Google Fonts API

config.fontFamilyString

Set the font-family for the fontUrl

config.inputFontSizeString

Set the font-size property of the input attribute

config.inputBoxShadowString

Set the box-shadow property of the input attribute

config.labelFontSizeString

Set the font-size property of the label attribute

config.labelWeightString

Set the font-weight property of the label attribute

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:

1
<EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
2
<div className="App">
3
<EvervaultInput
4
onInputsLoad={() => {
5
console.log('Inputs has loaded!');
6
}}
7
/>
8
</div>
9
</EvervaultProvider>

<EvervaultReveal />

Use evervault.reveal 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.

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!

1
{
2
"cardNumber": "string | number",
3
"cvv": "string | number",
4
"expiry": "string | number"
5
}

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.

1
export default function Reveal() {
2
const request = {
3
url: 'https://example-com.relay.evervault.com',
4
method: 'GET',
5
headers: {
6
Authorization: 'Bearer ey...',
7
},
8
};
9
10
return (
11
<main>
12
<EvervaultReveal request={request}></EvervaultReveal>
13
</main>
14
);
15
}

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.

Parameters
requestRequest

The request that Reveal should make when fetching the card details.

configString | Object

A config object for custom styles.

onLoadFunction

A callback that is called when the Reveal iFrame has finished loading successfully.

onCopyFunction

A callback that is called when the Reveal iFrame errors while loading.

onCopyFunction

A callback that is called when a user presses the copy button in the iFrame.