Collect and Process Card Data
A common payments workflow involves collecting card data from your users, then processing that data with a third-party payment processor like Stripe or Adyen. Without Evervault, this workflow would require the product to handle card data in plaintext, which would drastically increase the PCI Compliance scope of the environment.
Evervault offers two Primitives to support this workflow while ensuring that plaintext card data never touches your infrastructure. Adhering to this pattern significantly reduces your PCI Compliance scope.
Collect and Encrypt Card Data
Collecting card data from your users without handling it in plaintext drastically reduces your PCI Compliance scope. To do this, we're going to use the Card UI Component. The Card Component is a secure iframe form, hosted by Evervault and served from our PCI-compliant infrastructure, which you can embed in your product to collect card data. When your users input their card information, it gets encrypted within the iframe before being returned to your mobile or web app.
Integrate UI Components
To use the Card Component, you first need to install our React.js SDK.
You can initialize the React.js SDK by passing your TeamID and App ID to the <EvervaultProvider/> . The Card Component can be rendered by mounting the <Card/> component in any child of the provider. The <Card/> component accepts an onChange prop which is called every time your user updates their card data within the form and returns the encrypted card data.
Encrypted card data will be returned in JSON format, which can be subsequently passed to your backend and stored without ever handling card data in plaintext. The structure of the returned JSON object can be found here.
Your backend can retrieve additional card metadata like the funding type, segment, issuer, country, etc. from encrypted card data using the Evervault Inspect API
Inputs can be fully customized to match the design of your application. To learn more about styling, check out the styling documentation for UI Components.
Process Encrypted Card Data with a Third-Party API
Processing card data with a third-party API like Stripe or Adyen is a logical next step in this payments workflow. Since our intention is to keep card data encrypted at all times, we need a way to decrypt that data after it leaves our infrastructure, and before it reaches a third-party endpoint. We can achieve this using the Relay primitive.
Relay is a network proxy that can be configured to decrypt data during a request. If we proxy our request to a third-party endpoint through Relay, any encrypted data in the payload will be decrypted, allowing the request to be processed as normal.
First, we’ll integrate the proxy, then we’ll configure Relay to decrypt the encrypted fields.
Create a Relay
We’ll use RequestBin to simulate a third-party API. In practice, this could be an endpoint from any third-party service. We can create a RequestBin by navigating to requestbin.com/r, where we will be given a temporary endpoint that we can send requests to. To create a Relay for your RequestBin endpoint, navigate to the Relays tab in the Evervault Dashboard and click Create Relay. Add the RequestBin endpoint to the destination field.
Integrate the Proxy
To use Relay, first include and initialize the Evervault Node.js SDK in your application and enable Outbound Relay.
Then, using an HTTP client, we can send a request to the RequestBin endpoint, and the Evervault SDK will automatically intercept the request and route it through Relay. Since Relay intercepts HTTP requests, the proxy will work regardless of whether you’re sending a request directly to a REST endpoint, or using a third-party SDK.
For simplicity, we’re going to use the encrypt method to encrypt card data. In production, you should avoid handling plaintext card data on the server to avoid increasing your PCI DSS obligations. Instead you should encrypt the card details in the browser using the UI Components primitive.
If you run the snippet, you’ll see the request in your RequestBin logs. You’ll notice that the card data is still encrypted. Next, we’ll configure Relay to decrypt any encrypted data that gets sent to this endpoint.
Configure the Proxy
Once you have included the Evervault SDK in your application, We can confifgure a Relay to perform encryption and decryption operations for our RequestBin endpoint. In our case, we want to use Relay to decrypt any encrypted data as it's proxied to our RequestBin endpoint. In the Evervault dashboard, navigate to the Relay you created, and click the Add Route button to configure a new route. We want to decrypt any data being sent to this endpoint, so we can enter "/**" in the path field to match all requests sent to the Relay. Next, we can add a request action to decrypt all fields in the request body. Select Add Request Action -> Decrypt -> JSON, and enter $..* in the fields to decrypt. JSON requests use JSONPath to match fields in the request body and $..* will match all fields in the request body. Learn More
If we send request again, we’ll see another request in our RequestBin logs. This time, the encrypted cardNumber, expiry and cvc that we sent from our application was automatically decrypted by Relay before being forwarded to the RequestBin endpoint.
This architecture means you can still interact with any third-party API that requires sensitive data in plaintext, while keeping it encrypted at all times within your application.