Primitives

UI Components

Inputs image

Evervault UI Components make it easy to collect or display cardholder data securely in the browser with our client-side SDKs.

The UI Components primitive includes two elements: Inputs and Reveal. Inputs is an iframe form which can be used to collect and encrypt card data. Reveal is an iframe container which can be used to decrypt and display encrypted card data.

UI Components are served within an iframe retrieved directly from Evervault’s PCI-compliant infrastructure, and all operations on card data occur within Evervault's PCI Compliant environment.

Adopting this approach for collecting or displaying card data can reduce your PCI DSS compliance scope to the simplest form (SAQ A Control Set), once integrated correctly.

UI Components are fully customizable and can be updated to match your design system with simple CSS configuration.


Inputs

Get up and running with Evervault Inputs in less than 5 minutes.

In this example, we will use one of our client-side SDKs. Before starting this tutorial, you'll need to sign up for an Evervault account and create an app.

Getting Started

To use Evervault Inputs, you will need to install either our JavaScript SDK or React.js SDK.

1
# Using npm
2
npm install @evervault/react
3
4
# Using yarn
5
yarn add @evervault/react

Integrate Evervault Inputs

Once installed, initialize the JavaScript SDK or React.js SDK with your Team ID and App ID, both of which can be found in the Evervault Dashboard.

Integrating Inputs is then as easy as creating an element in HTML or using the <EvervaultInputs /> component in React.js.

1
// Use the EvervaultProvider component as a provider for your app.
2
import { EvervaultProvider } from '@evervault/react';
3
import ChildComponent from '../ChildComponent';
4
5
export default function App() {
6
return (
7
<EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
8
<ChildComponent />
9
</EvervaultProvider>
10
);
11
}
12
13
// Once you've included the EvervaultProvider, you can then use the `<EvervaultInputs />` components to render
14
import { EvervaultInput } from '@evervault/react';
15
import { useState, useEffect } from 'react';
16
17
export const ChildComponent = () => {
18
const [encryptedCardDetails, setEncryptedCardDetails] = useState(undefined);
19
20
useEffect(() => {
21
if (!encryptedCardDetails) return;
22
23
console.log(encryptedCardDetails);
24
}, [encryptedCardDetails]);
25
26
return <EvervaultInput onChange={setEncryptedCardDetails} />;
27
};

Encrypted card details will be returned to you in JSON format, so you can then pass it on to your backend without ever handling cardholder data in plaintext — reducing your PCI DSS compliance scope to the simplest form.

The output JSON will be structured like this:

1
{
2
"card": {
3
"type": "visa_credit",
4
"number": "ev:encrypted_string",
5
"cvc": "ev:encrypted_string",
6
"expMonth": "01",
7
"expYear": "23",
8
"bin": "454858",
9
"lastFour": "2134",
10
"name": "John",
11
"swipe": false,
12
"track": {
13
"fullTrack": "",
14
"trackOne": "",
15
"trackTwo": ""
16
}
17
},
18
"isValid": true,
19
"isPotentiallyValid": true,
20
"isEmpty": false,
21
"error": {
22
"type": "invalid_pan",
23
"message": "The credit card number you entered was invalid"
24
}
25
}

Styling

Inputs can be customized to match your brand’s design system. Both the JavaScript and React SDK allow additional configuration for styling both the Evervault Inputs container as well as each <input> within the container.

1
<EvervaultInput
2
config={{
3
theme: 'minimal',
4
height: '40px',
5
}}
6
/>

Supported settings

When passing a config object for customizing Inputs, the following key-value pairs are supported.

themeString

The base styling for Inputs. Currently supports default, minimal and material.

heightString

The height of the Evervault Inputs iframe.

primaryColorString

The main theme color.

labelColorString

The color CSS property applied to the input labels.

inputTextColorString

The color CSS property applied to inputs.

inputPlaceholderColorString

The color CSS property applied to the ::placeholder CSS pseudo-element for inputs.

inputBorderColorString

The border-color CSS property applied to inputs.

inputBackgroundColorString

The background color CSS property applied to inputs.

inputBorderRadiusString

The border-radius CSS property applied to inputs.

inputHeightString

The height CSS property applied to inputs.

cardNumberLabelString

The label for the card number input

expirationDateLabelString

The label for the expiration date input

securityCodeLabelString

The label for the security code input

expirationDatePlaceholderString

The placeholder for the expiration date input

invalidCardNumberLabelString

The message shown on an invalid card number

invalidExpirationDateLabelString

The message shown on an invalid expiration date

invalidSecurityCodeLabelString

The message shown on an invalid security code

fontUrlString

Load a custom font with the Google Fonts API

fontFamilyString

Set the font-family for the fontUrl

inputFontSizeString

Set the font-size property of the input attribute

inputBoxShadowString

Set the box-shadow property of the input attribute

labelFontSizeString

Set the font-size property of the label attribute

labelWeightString

Set the font-weight property of the label attribute

disableCVVString

Will remove the CVV field from Inputs and show only the card number and expiry fields if this key is present.

disableExpiryString

Will remove the Expiry field from Inputs and show only the card number and CVV fields if this key is present.

Default theme

Set theme to default to use the Default theme for Inputs.

Minimal theme

Set theme to minimal to use the Minimal theme for Inputs.

Material theme

Set theme to material to use the Material theme for Inputs.

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 in the JavaScript SDK or React.js SDK.


Reveal

Getting Started

Displaying card data to a user while minimizing PCI Compliance scope is possible with Evervault's Reveal UI Component. To use Reveal, you'll need to create an Inbound Relay that points at your API. The endpoint should return an encrypted card data payload in the json format outlined below. The request parameter of Reveal receives a Request object pointing at the Inbound Relay URL, along with the Authentication headers required to access the endpoint. Inbound Relay will automatically decrypt the card data before it arrives at the Reveal iframe.

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": "ev:debug:Tk9D:number:mqrANWE1KMapRVCX:A8Gse2iNxLKy8WLnBDkqtkt+TTSaJFNyc+R/toYd2d8n:FUM5vwjOIrHI+3Jk7QnVCUpHVS0aZQC80ih/wpHtR2o=:$",
3
"cvv": "ev:debug:Tk9D:number:YG1KlyImadEc/qJz:A7odbz+iMRub/WHEO9bwLI5tig+nJ12aKCfWHtMU87rJ:/g1rhC8GeaGyWbM1Y0kaT45IKw==:$",
4
"expiry": "ev:debug:Tk9D:oQMusWLR0X2fRX3s:Ay7B8AFRrBBWW/3MWXylmY2QGTwBFGADenXUoUQPT845:udPsUUegZeFAsNzimcSTofbtjXKe:$"
5
}
1
<html>
2
<body>
3
<form id="ev-card">
4
<div id="ev-card-reveal">
5
<!-- Evervault will create input elements here -->
6
</div>
7
</form>
8
</body>
9
<script src="https://js.evervault.com/v2"></script>
10
<script>
11
const request = new Request('https://example-com.relay.evervault.com', {
12
method: 'POST',
13
body: '{"foo": "bar"}',
14
headers: {
15
Authorization: 'Bearer <Some JWT>',
16
},
17
});
18
const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
19
let config = {
20
revealFontSize: '20px',
21
revealFontWeight: 200,
22
revealTextColor: '#d1dce6',
23
};
24
let reveal = evervault.reveal('ev-card-reveal', request, config, () =>
25
alert('Copied to Clipboard!')
26
);
27
28
reveal.isRevealLoaded.then(() => {
29
console.log('Reveal loaded');
30
});
31
</script>
32
</html>

Styling

When passing a config object to style Reveal, the following key-value pairs are supported.

By default, the Reveal iframe doesn't include labels. Setting any of the label config options will add a label to the relevant section.

heightString

The height of the Evervault Inputs iframe.

revealFontSizeString

Set the font-size property of the text in Reveal.

revealFontWeightString

Set the font-weight property of the text in Reveal.

revealTextColorString

The color CSS property applied to Reveal.

fontUrlString

Load a custom font with the Google Fonts API

fontFamilyString

Set the font-family for the fontUrl

cardNumberLabelString

Adds a label above the card number, it will display the text passed in to this option field.

expirationDateLabelString

Adds a label above the expiration date, it will display the text passed in to this option field.

securityCodeLabelString

Adds a label above the security code, it will display the text passed in to this option field.

labelFontSizeString

Set the font-size property of the text in the labels in Reveal.

labelFontWeightString

Set the font-weight property of the text in the labels in Reveal.

labelColorString

The color CSS property applied to the labels in Reveal.

customStylesObject

Ad advanced config option, that allows you to directly apply CSS styling to your Reveal iframe.

Advanced styling

The styling options above are designed to solve for the most common styling needs of Evervault users. However, we recognize that additional styling parameters are often required.

To apply more granular styling, you can add CSS attributes to each element of the Reveal component using the customStyles parameter. The diagram below shows the arrangement of DOM elements within the iframe where CSS styles can be applied.

To minimize PCI Compliance scope, and to ensure that untrusted code can't run within the Reveal iframe, we don't allow any custom CSS to use the url() function. Any CSS values using url() will be removed from the config.

Reveal DOM Elements

To style an element, add the customStyles argument to the config object. customStyles is an object where the keys are the elements of the DOM that you can style, and the values are objects containing all of the custom styles for a given DOM element.

For instance, consider a scenario where you need to create a 40px margin between the topRow and the bottomRow, and also italicize the CVV. In this case, the following parameters would be applied:

1
const config = {
2
customStyles: {
3
topRow: {
4
marginBottom: '40px',
5
},
6
securityGroupText: {
7
fontStyle: 'italic',
8
},
9
},
10
};
11
12
let reveal = evervault.reveal('ev-card-reveal', request, config);

Error handling

Because Reveal fetches card data from your server via Inbound Relay, it's structured to provide your application with insights into any errors that occur. This design allows you to determine the appropriate response of your application when there's a failure in retrieving card details. To understand how to manage errors using our React and Javascript SDKs, see the examples below.

1
const request = new Request('https://example-com.relay.evervault.com');
2
3
let reveal = evervault.reveal('ev-card-reveal', request, config, () =>
4
alert('Copied to Clipboard!')
5
);
6
7
reveal.isRevealLoaded
8
.then(() => {
9
console.log('Reveal loaded');
10
})
11
.catch((error) => {
12
console.error(`Reveal has failed to load: ${e}`);
13
});
1
export default function Reveal() {
2
const request = {
3
url: 'https://example-com.relay.evervault.com',
4
};
5
6
const onLoad = () => console.log('Reveal Loaded!');
7
const onError = (e) => console.error(`Reveal has failed to load: ${e}`);
8
9
return (
10
<main>
11
<EvervaultReveal
12
request={request}
13
onRevealLoad={onLoad}
14
onRevealError={onError}
15
></EvervaultReveal>
16
</main>
17
);
18
}

Security

Evervault Inputs and Reveal are served through an iframe hosted on Evervault's compliant (PCI DSS Level 1) infrastructure.

Evervault is responsible for the security of the servers providing the iframe, meaning your cardholder data environment is reduced to the smallest size possible.

All credit card data is encrypted client-side using the Web Crypto API, so no cardholder data leaves your user's device without being encrypted using Evervault Encryption.