Guides
JavaScript SDK
You can use our JavaScript SDK to:
- Encrypt data client-side
- Collect or display card data with UI Components
Quickstart
Install SDK
Our JavaScript SDK is distributed from our CDN, and can be installed just by placing this script tag before the closing </body>
tag in your HTML.
Initialize SDK
Once installed, initialize the JavaScript SDK with your Team and App ID found in the Evervault Dashboard.
Encrypt a string
Now that the SDK is initialized, we can encrypt a string.
Full example
Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key), run it in your own environment and run the encryption and decryption for yourself.
Reference
window.Evervault(appId, teamId)
The SDK constructor accepts two parameters:
- Your Team ID
- Your App ID
The ID of your Evervault app. This can be found inside of your app settings on the Evervault dashboard.
The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.
evervault.encrypt(data)
Encrypts data using Evervault Encryption.
To encrypt strings using the JavaScript SDK, simply pass a String
or an Object
into the evervault.encrypt()
function. To encrypt a file, pass a File
or Blob
.
The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our Primitives. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.
evervault.decrypt(token, data)
Decrypts data previously encrypted with the encrypt()
function or through Relay.
The decrypt()
function allows you to decrypt previously encrypted data using a 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.
evervault.inputs(element, config)
Initializes Evervault's Inputs UI Component. Inputs makes it easy to collect encrypted cardholder data in a completely PCI-compliant environment.
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).
Simply pass the ID of the element in which the iFrame should be embedded.
We also support themes and custom styles so you can customise how Inputs looks in your UI.
Example
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:
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.
getData()
This option is best when you are looking to retrieve card data occasionally, like when your form is submitted.
Localization
The iFrame can be localized by providing a set of labels in the config on initialization. The labels can then be updated as required using the setLabels
method.
Adding labels on initialization:
Updating labels:
iFrame loading status
If you need to wait for the iFrame that serves inputs to load before doing some action, there is an easy way to do so.
isInputsLoaded
This is a Promise
that resolves when the iFrame is loaded. You can listen for the iFrame load event by await
ing this Promise
, or using then
:
evervault.reveal(element, request, config, onCopy)
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!
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.