Card Collection

Pricing

You can collect card information in a few ways with Evervault, but our prebuilt UI components are the most common. Cardholder data that's encrypted with Evervault can be safely stored in your database and then shared with third-party payment processors using Relay. This guide walks you through the entire process using our Card component for collection.

1{
2  card: {
3    number: "",
4    cvc: "",
5    expiry: {
6      month: "",
7      year: ""
8    }
9  }
10}

The Card component

The Card component is a secure iframe, hosted by Evervault, that you embed in your product to collect card data. When customers input their card information, it's encrypted within the iframe before being returned to you for storage. This approach reduces your PCI DSS scope because Evervault hosts the iframe, and you never handle plaintext card data.

Get started with the Card component

1<script src="https://js.evervault.com/v2"></script>

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");

1import { loadEvervault } from "@evervault/js";
2
3const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");

1const card = evervault.card({
2  theme: evervault.ui.themes.clean(),
3});
4card.mount("#card-details");

1function handleSubmit() {
2  // Pass the encrypted card data to your backend
3  fetch("my-api.com/checkout", {
4    method: "POST",
5    headers: {
6      "Content-Type": "application/json",
7    },
8    body: JSON.stringify({
9      number: card.values.card.number,
10      expiry: card.values.card.expiry,
11      cvc: card.values.card.cvc,
12    }),
13  });
14}

Forwarding encrypted card data

Now that you have the encrypted card data, you need to pass it to a third-party payment processor (Stripe, Adyen, etc.). To do this, you use Relay to decrypt the data after it leaves your infrastructure, and before it reaches the third-party API.

Relay is a network proxy that can be configured to decrypt data during a request. When you proxy a request through Relay, the encrypted card holder data is decrypted, allowing the request to be processed as normal when it reaches the third-party. This means the encrypted card data you collect reaches the PSP as plaintext data, without you ever handling the raw form.

Create a Relay

To simplify this example, we'll use PutsReq to simulate a third-party API. PutsReq provides a temporary endpoint that we can send requests to, however, in practice, this would be an endpoint from a third-party service.

To create a relay for your PutsReq endpoint, navigate to the Relays tab in the Evervault Dashboard, click Create Relay, and add the PutsReq endpoint to the destination field.

Configure the relay

By default, relays are just transparent proxies that don't decrypt any data. They can be configured to perform encrypt and decrypt operations on request or response. For this example, the relay needs to decrypt encrypted card data on request as it's proxied to the third-party endpoint.

In the Dashboard, 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 any encrypted data in the request body. Select Add Request Action -> Decrypt -> JSON, and enter $..* in the fields to decrypt. This configures the relay to match any encrypted JSON fields in the request body and decrypts them.

You can learn more about field selection in the Relay documentation.

Integrate the relay

Finally, we can implement our API endpoint to pass encrypted card data to the third-party payment processor using the relay you just created. When requests are sent, card data is automaitcally detected and decrypted before it reaches the third-party API.

1// Replace with Relay URL
2const relayURL = "<PUTSREQ_RELAY_URL>";
3
4// POST /checkout
5router.post("/checkout", async (req, res) => {
6  try {
7    const response = await fetch(relayURL, {
8      method: "POST",
9      headers: {
10        "Content-Type": "application/json",
11        "X-Evervault-App-Id": "<APP_ID>",
12        "X-Evervault-Api-Key": "<API_KEY>",
13      },
14      body: JSON.stringify({
15        number: req.body.number,
16        expiry: req.body.expiry,
17        cvc: req.body.cvc,
18      }),
19    });
20
21    const data = await response.json();
22    res.json(data);
23  } catch (error) {
24    res.status(500).json({ error: error.message });
25  }
26});

1evervault.card({
2  theme: evervault.ui.themes.clean(),
3});

1const theme = {
2  styles: {
3    ":root": {
4      "color-scheme": "light",
5    },
6    label: {
7      fontSize: 11,
8      fontWeight: 500,
9      textTransform: "uppercase",
10    },
11    ".error": {
12      color: "red",
13      fontSize: 12,
14      marginTop: 5,
15    },
16    ".field input": {
17      marginTop: 5,
18      padding: "8px 12px",
19      border: "2px solid #dddddd",
20    },
21    ".field:focus-within input": {
22      borderColor: "#6633ee",
23    },
24  },
25};

1evervault.ui.themes.clean({
2  styles: {
3    label: {
4      color: "#6633ee",
5    },
6  },
7});

1const theme = {
2  fonts: ["https://fonts.googleapis.com/css2?family=Comic+Neue"],
3  styles: {
4    input: {
5      fontFamily: "'Comic Neue'",
6    },
7  },
8};

1const theme = (utilities) => {
2  return {
3    styles: {
4      label: {
5        fontSize: 16,
6      },
7      ...utilities.media("(max-width: 400px)", {
8        label: {
9          fontSize: 20,
10        },
11      }),
12    },
13  };
14};

1const acmeBrand = evervault.brands.create("acme-card", {
2  numberValidationRules: {
3    ranges: [[88000, 88999]],
4    lengths: [16],
5  },
6  securityCodeValidationRules: {
7    lengths: [3],
8  },
9  iconSrc: "https://your-cdn.com/acme-icon.svg",
10});
11
12const card = evervault.ui.card({
13  customBrands: [acmeBrand],
14});
15
16card.on("change", (data) => {
17  // "acme-card" appears in data.card.localBrands when a matching number is entered
18  console.log(data.card.localBrands);
19});

Other collection methods

For card collection, we generally recommend using our UI components, but if those don't work for your use case, you can also collect card information server to server and with our SDKs (each SDK has an encrypt method). These options can impact your compliance scope depending on what you implement. If the flow you build exposes you to plaintext card data, it can increase your PCI DSS scope.

For server to server, create a relay that encrypts data for inbound requests to your server. The external server making the call needs to send the request to your relay, which encrypts the sensitive data and then forwards the request to your server. For client side encryption with the SDK, use the encrypt method.