Evervault Inputs makes it easy to collect cardholder data securely in the browser with our client-side SDKs.

Evervault Inputs is served within an iFrame retrieved directly from Evervault’s PCI-compliant infrastructure, and all operations on card data (such as validity checks) also occur within the Evervault environment.

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

Evervault Inputs is fully customizable and can be updated to match your design system with simple CSS configuration.

Getting Started

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.

Install the Evervault SDK

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
}

Themes

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.

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

Displaying card details to a user is possible with the Reveal functionality of Inputs. The Reveal function requires creating an Inbound Relay to point to your API. The request parameter of the Reveal function receives a Request object pointing at the Inbound Relay URL, along with the Authentication headers required to access the endpoint which will return encrypted card data. Inbound Relay will automatically decrypt the card data before it arrives at the in the Inputs iFrame. It is important that the response from the API endpoint is in the following json format.

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, () => alert("Copied to Clipboard!"));
25
26
    reveal.isRevealLoaded.then(() => {
27
      console.log("Reveal loaded");
28
    });
29
  </script>
30
</html>

Styling

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

By default the Reveal iframe doesn't have any labels in it, setting any of the label config options adds a label above the string.

Advanced styling

The styling options above are designed to solve for the most common styling needs of our customers, however we recognise that sometimes more customization is needed to make your product look its very best.

To help you build a beautiful card reveal component, we support directly providing CSS attributes to be applied to elements within the iframe by configuring the customStyles option. The diagram below shows the arrangement of DOM elements within the iframe, so you can apply styles to the correct element.

To style an element, add a custom styles argument to the config object. Custom Styles 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 example, say I wanted to add a margin of 40px between the topRow and the bottomRow and make the CVV italic, this is what I'd pass in:

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

Since Reveal makes a request to your backend to get the card details through Relay, it has been designed to give your application visibility in to its errors. This way you can decide how your application should react to a failed attempt to pull the card details. See the example below to understand how to handle errors in our React and Javascript SDKs.

1
  const request = new Request("https://example-com.relay.evervault.com");
2
  
3
  let reveal = evervault.reveal('ev-card-reveal', request, config, () => alert("Copied to Clipboard!"));
4
5
  reveal.isRevealLoaded.then(() => {
6
    console.log("Reveal loaded");
7
  }).catch((error) => {
8
    console.error(`Reveal has failed to load: ${e}`);
9
  });

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 request={request} onRevealLoad={onLoad} onRevealError={onError}></EvervaultReveal>
12
    </main>
13
  );
14
}

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.