Relay

Pricing

Relay is a network proxy that encrypts and decrypts sensitive data in transit between a client and a destination server. It works with your own APIs and third-party services, and requires minimal changes to your existing code.

How Relay works

You can use Relay in a few ways:

• Outbound from your server: you hold encrypted data (such as card details) and forward it to a third-party API. Relay decrypts the data as the request passes through it, so your infrastructure never handles sensitive data directly.
• Inbound to your server: data arrives from an external source and needs to be encrypted before it reaches your server. Relay encrypts the fields you specify on the way in.
• Outbound from your server to your frontend (specifically for revealing card details in a browser): encrypted card details are decrypted on the way out so they can be displayed to customers through the Reveal component.

Relay is most commonly used for outbound decryption. Here's what that looks like for collecting and sharing card data for a payment.

1. Your customer enters their card details into our Card component. The data is encrypted within the iframe before it's returned to your application.
2. Your backend receives and stores the encrypted card information. Because the data is encrypted, it's safe to store on your side.
3. Using the encrypted data, you send an API request through Relay to your payment processor.
4. Relay detects the encrypted card fields and decrypts them in transit.
5. The payment processor receives the card data in plaintext, completes the payment, and the response is piped back to you through Relay.

Evervault doesn't do anything with the response from your payment processor. If needed, you can configure Relay to encrypt any sensitive values before the response is forwarded to your server.

Getting started

This example focuses on creating a relay and how you can send encrypted data through it. See the Card Collection page for an end-to-end guide that covers collecting, encrypting, and forwarding card data.

Create a relay

Open the Relays section in the dashboard and click Create Relay. Provide the base URL (example.com) for the API you want to proxy requests to and create the relay.

Evervault provisions a domain for your relay after creating it. This is the domain you'll send requests to when you want to proxy API calls to downstream partners. You can find the domain in the dashboard (it looks this: [DESTINATION_URL].relay.evervault.app).

Configure a route

Routes define what to do with requests that match a given URL path, and you can have multiple routes for each relay. You configure the data type and fields (JSON, form data, etc.) to operate on, as well as what to do with that data. To create a route, click + Add Route in the dashboard and then set the path (e.g., /charge), actions, etc.

You configure relays to encrypt or decrypt data with route actions. These actions can be applied to requests (data being sent to the destination) or the response (data being returned to you). The combination you configure depends on your use case.

• Decrypt on request: your backend holds encrypted data and forwards it to a third-party API. Relay decrypts the fields in transit.
• Decrypt on response: used with the Reveal component to display card details to your customers.
• Encrypt on request: Encrypt data that you collect before storing it (outside of card data which you should use our card collection for)
• Encrypt on response: encrypt data returned by a third party, such as a card issuer returning PANs, before it reaches your server.

Sending a request

Pass your relay's domain into your requests to proxy them to the target endpoint.

1curl -X POST [YOUR_RELAY_URL] \
2    -H "Content-Type: application/json" \
3    -d '{ "message": "Hello, World!" }'

As an example, when you collect a card number with Evervault, it's encrypted on the frontend before being sent to your backend. So a card number like 4242 4242 4242 4242 is turned into something like this.

1ev:QkTC:LUZWpxaiu16W1DJT:AnzlRtDd/kWFWuOsQH+HE0oqZHKCYZst+yZAQAFVBiXh:xsbavmwYTzgtKFWEcA8o9eMT+9olCFYKkTOtyFX158IrXn+G8MAtALr0pZrxBh0:$

You store this value instead of the plaintext card number. When you want to charge the card, you send the request through relay with the encrypted string. Relay decrypts it in transit, and your downstream partner receives the plaintext card number.

Path matching

Route actions will only be applied to requests that match the request path. Paths can be configured to match a specific path or multiple paths with a wildcard.

Selecting fields

Route actions are only applied to data that matches the list of selected fields defined on an action. Field selection can be configured on a per-content type basis.

JSON

Use JSONPath to select fields according to their path in the JSON object. JSON values must only contain encrypted strings (e.g., { "ssn": "ev:...1a2bc$" }). If the value contains other data like raw text (e.g.,{ "ssn": "User SSN: ev:...1a2bc$" }), decryption fails.

JSON payloads are supported for requests where the content-type subtype is JSON. The subtype is the part of the content-type header after the /. For example, a content-type of application/json+charset=utf8 has a subtype of JSON.

JSON selector examples