# Core concepts

_Understand Evervault's model for encrypting and using sensitive data across Relay, Functions, Enclaves, and payments._

 ![...]()

Learn what Evervault does, how it fits into your architecture, and how to start building. This page connects the dots between our platform, your use case, and a secure integration path.

## Understand Evervault from the ground up

Evervault is a developer-first platform for orchestrating secure data flows. You can collect, store, process, and forward sensitive information without increasing your compliance scope. It's designed to fit into your existing stack with minimal effort, so you can focus on building your own data orchestration. At its core, Evervault encrypts sensitive data into ciphertext which can be safely stored in your infrastructure and decrypted at runtime.

## You store encrypted data

Evervault doesn't use a [traditional token vault model](https://evervault.com/blog/encryption-in-payments-evervault-encryption-vs-traditional-encryption). Instead, we use a dual custody encryption model that's faster and more secure. With this architecture, you store encrypted data and we manage the keys.

There's no need for developers to handle encryption keys directly, and data is never stored in Evervault's infrastructure. Instead, sensitive information is collected through our products and instantly returned in an encrypted format, ready to store or pass to downstream systems.

The dual custody model has two key advantages compared to traditional token vaults:

- **It's faster**: There's no need for database lookups on our side, which means lower latency and better throughput.
- **It's more secure**: Even if one side is compromised, the data is still safe. An attacker would need to breach both your infrastructure and Evervault to access decrypted values.

It's tokenization, reimagined for performance, privacy, and stronger architectural boundaries. You can use [Card Collection](/cards/card-collection) to encrypt card holder data or use our [SDKs](/sdks) to encrypt any other data.

## Processing and forwarding data

After your data is encrypted and stored in your infrastructure, the next step is securely processing and sharing it. This is what Evervault's core products are designed for: enabling encrypted data to move, transform, and integrate without compromising security or compliance. These tools open up a wide range of use cases, including:

- Sending decrypted data to third-party services.
- Encrypting incoming data from a third party before storage.
- Fetching and decrypting sensitive data from your own backend, in transit.

- [Relay](/relay): Relay is a configurable network proxy that encrypts or decrypts data in transit—between your app and your own APIs, or any third-party APIs.
- [Functions](/functions): Functions are secure, serverless code environments that decrypt encrypted data at runtime, allowing you to process it without exposing it in your infrastructure.

## Evervault for payments

Evervault gives you flexible tools for collecting card data and using it for self-orchestration, without compromising security or compliance. You can capture and manage your own credit card data, design smart routing logic, run multi-PSP setups, build anti-fraud workflows, etc.

- Run operations on encrypted card data using our payments products, like performing network tokenization, running 3D Secure authentications, or sending and receiving data to and from PSPs—all without ever decrypting it yourself.
- Enable point-to-point encrypted transport to third parties (like payment processors or fraud tools) using Evervault Relay, maintaining full PCI compliance while keeping data completely shielded from your app and infrastructure.
- Stay out of scope for PCI: our Level 1 Service Provider status and architecture let you handle card data workflows without bringing your systems into PCI scope.

Whether you're building a checkout flow, tokenizing cards, or routing data to partners, Evervault makes it secure and compliant, while maintaining high performance and a quality developer experience.

<PaymentProducts />

## Teams, apps, and sandboxes

Evervault accounts are organized around teams, which act as the top-level container for everything you build. Within a team, you can create and manage multiple apps, each with its own configuration, keys, and data flows. Apps can be designated as either Production or Sandbox environments, depending on their purpose.

[Sandboxes](/developers/sandbox) are purpose-built for testing, simulation, and pre-production validation. They provide isolated environments that mirror production behavior, but without risking real data. Every sandbox app includes access to all [Platform](https://evervault.com/pricing) features, including advanced tooling like simulated card updates, webhook event triggers, and custom policy testing. This lets you build and iterate confidently, ensuring that production data stays untouched while you fine-tune your integrations.

> **Production data**
>
> Sandbox environments simulate all values and behaviors. If you require production-level data, such as card scheme responses, ACS server responses, or live webhook payloads, you'll need to contact support to access a production proof-of-concept (POC) environment for live testing.
>
> [Contact Support](mailto:support@evervault.com)

## Start building your integration

You can integrate with Evervault using our client SDKs, server SDKs, REST API or CLI. With developer-friendly tooling and a fast integration path, engineering teams can go from idea to implementation in hours, not weeks.

<SDKS />

## Before going live

There's a [checklist](https://evervault.com/launch) on our website for going live but there are a few things worth noting here. Sandbox and Production apps don't share data, API objects, or encryption access. This means:

- Data collected or created with a Sandbox app can't be used by a Production app
- Any data or API objects you need for a Production app need to be created using that app's UUID and key
- Data that gets encrypted in a Sandbox app can't be decrypted with a Production app

All of that works in the opposite direction as well (e.g., data encrypted by a Production app can't be decrypted with a Sandbox app). If there are feature flags enabled for you during your integration process, [contact support](mailto:support@evervault.com) to ensure they're enabled for production as well.


---

# Relay

_Evervault Relay is a configurable proxy that encrypts or decrypts sensitive data in transit for your APIs and third‑party services._

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](/cards/card-collection)) 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](/cards/reveal).

> To further process data encrypted by Relay, check out [Functions](/functions) and [Enclaves](/enclaves).

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](/cards/card-collection). 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](/cards/card-collection#get-started-with-the-card-component) page for an end-to-end guide that covers collecting, encrypting, and forwarding card data.

> Encrypt and decrypt actions are tied to app keys. If you encrypt data with Relay in a [sandbox app](/developers/sandbox), you can't decrypt that data with Relay from a production app (or the other way around). Data can only be encrypted and decrypted using the same app key.

### Create a relay

Open the [Relays section](http://app.evervault.com/app/relays) 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](#path-matching), and you can have multiple routes for each relay. You configure the [data type and fields](#selecting-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](/cards/reveal) 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](/cards/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.

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.

```
ev: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](/cards/card-collection?backend=node#integrate-the-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.

| Example | Description |
| --- | --- |
| `/` | Matches requests to the root path |
| `/checkout` | Matches requests to /checkout |
| `/patients/*/reports` | Allows for dynamic URL segments such as IDs. Matches requests such as /patients/1/reports, /patients/2/reports, etc. |
| `/**` | Matches all requests |

## 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](https://goessner.net/articles/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

### Form data

Form data is only supported for requests with a `content-type` of `application/x-www-form-urlencoded` or `multipart/form-data`. Form fields are matched directly by name. If a matched value contains multiple pieces of encrypted text, each one is decrypted individually. Global wildcards are supported for form data but not nested ones (e.g., `*` is valid but something like `name.*.last` isn't).

> **Wildcard selectors also decrypt encrypted files**
>
> An `*` form-field decrypt selector also decrypts encrypted files that arrive as octet-streams, including file parts in `multipart/form-data`. This unlocks file-decryption flows and deviates from the field-level model used elsewhere. Only Evervault-encrypted files are decrypted, so plain, non-encrypted octet-streams pass through untouched.

#### Form data selector examples

### Files

Relay supports encrypting and decrypting files in `multipart` and `form-data` requests. Encrypted files are forwarded with an unchanged filename, but the bytes in the file are fully encrypted. There is a per-request limit of 25 MB for encryption and decryption.

An `*` [form data](#form-data) decrypt selector also matches encrypted files, so it isn't always necessary to configure a separate file selector.

#### File selector examples

### Headers

Headers can be selected by name and aren't case sensitive. If the matched header value contains multiple pieces of encrypted text, each one is decrypted individually.

#### Header selector examples

### XML

To work with XML data, configure your relay for JSON and select the fields to encrypt or decrypt using standard JSONPath. To encrypt attributes, use advanced JSONPath selectors.

#### XML selector examples

## Authentication

API key authentication adds an additional layer of security to your relay. When enabled, requests through Relay require a valid Evervault API key in the `X-Evervault-Api-Key` header and your app's ID in the `X-Evervault-App-Id` header.

> **Enable authentication for relays that decrypt data**
>
> Evervault strongly recommends enabling API key authentication for any relay configured to decrypt data. If your relay is pointed at your own API (which already has its own authentication), it may not be strictly necessary. When using Relay with a third-party API, API key authentication ensures that only your application can trigger decryption.

You can enable authentication for your relay in the [Evervault Dashboard](https://app.evervault.com) by navigating to the **Authentication settings** page.

> **Authorize access to decrypted data**
>
> Some flows deliver decrypted data directly to a client (e.g., the [Card Reveal](/cards/reveal) iframe fetching plaintext card data). In these cases, your backend endpoint is the only place where access control is enforced. Evervault has no context for which of your customers can access a given record, so authenticate the request and verify that the caller is authorized before the response is returned.

## Limitations

The following limitations apply to all requests sent through Relay. If your application requires higher limits, contact [support@evervault.com](mailto:support@evervault.com) to discuss your requirements.

| Description | Limit |
| --- | --- |
| Max payload size | 5mb |
| Max file size | 25mb |
| Max chunked size (transfer-encoding: chunked) | 700kb |
| Connection Timeout | 120s |

## Alerts

Alerts allow you to see errors in Slack or be sent to any webhook URL of your choice. You can create an alert for your relay inside of the Evervault Dashboard by navigating to **Relay → Alerts → Add Alert**. When you configure a custom webhook to receive alerts, the following fields will be in the response.

**Payload**

- `relayUuid` — The unique identifier for your relay.
- `teamUuid` — The unique identifier for your team.
- `errorMessage` — Message explaining what went wrong.
- `evMessage` — Message about where the error has occurred.
- `activityLink` — A link to view the failed transaction in the Evervault dashboard.
- `timestamp` — The time the error occurred.
- `errorType` — The relay [error code](#relay-error-codes).
- `statusCode` — The HTTP status code of the response.
- `statusGroup` — 4XX, 5XX, or ERR.
- `inboundDomain` — Your relay domain.

## Error handling

Errors originating from within Relay can be distinguished by the `X-Evervault-Error-Code` header. The responses will have a content type of `application/problem+json` and a payload of the following structure:

```json
{
  "code": "error code used to pinpoint the specific issue in the reference below",
  "title": "human readable title for the error",
  "detail": "longer-form, human readable description of the error",
  "status": 0 // numeric http status code of the response
}
```

**Error Codes**

- `subdomain-not-found` — This error indicates you are sending a request to a relay (e.g., my-api-com.relay.evervault.app) which doesn't exist. Ensure you have entered the Relay subdomain correctly. Also, ensure you have configured your relay correctly by following our Relay documentation.
- `request-timeout` — The target took too long to respond. The error can have many causes ranging from network issues to malformed client requests. Ensure the target domain URL is correct, wait a few moments and try again. If the error persists, reach out to the owner of the target domain through any support channels they have in place.
- `service-unavailable` — The target refused the connection and could not be reached. Ensure the target host is healthy. We recommend that you implement retry behavior to mitigate the impact of brief issues with the network or target host.
- `unsupported-content-type-in-response` — This error occurs when Relay is configured to perform response encryption and receives an unsupported content type as a response from the endpoint. Currently, Relay can only encrypt JSON, XML and multipart/form-data structured data.
- `proxy-auth-failed` — There was an issue authenticating with the provided API key. Ensure that you are using the correct API key.
- `content-length-required` — The Content-Length header is either not present or isn't a number.
- `invalid-request` — This error indicates that an invalid hostname was provided while communicating with Relay in [forward proxy mode](#forward-proxy-mode). Ensure you have entered the downstream hostname correctly, and that it can be resolved when requesting it directly.
- `forbidden` — The API key provided does not have sufficient grants to perform the actions requested. Please review the grants given to your API Key.
- `payload-too-large` — This request exceeds the request size limit in Relay. The current per-request limit is 25 MB for encryption/decryption of multipart data, and 5 MB for all other content types.
- `invalid-content-type` — The content type header received by Relay was malformed, preventing the body from being processed.
- `internal-server-error` — There was an issue with Relay itself. Try again in a few moments.
- `decrypt/forbidden` — A ciphertext's data policy prevented it from being decrypted. Ensure your data policy's configuration is correct.
- `no-hostname-in-request` — This error indicates that Relay received a CONNECT request with no hostname while operating in [forward proxy mode](#forward-proxy-mode). Ensure you have entered the downstream hostname correctly, and that it can be resolved when requesting it directly.
- `relay-not-found` — There was an issue finding a relay for the provided domain. Make sure you are using the correct domain. If your domain is correct but you are still seeing this issue, ensure you have Relay configured correctly.
- `encrypt/pre-encrypted-data` — There was encrypted data where it wasn't expected. This can mean a number of things: - An inbound request header value contained Evervault encrypted data. - An inbound request payload had Evervault encrypted data as the value of one of the fields, which was not going to be encrypted. - The target URI for the inbound request had Evervault encrypted data as part of the path.
- `proxy-error` — Relay experienced an unexpected networking error while communicating with the downstream service. Please confirm that the downstream service is accessible when not routing through Relay, and ensure that any allowlist requirements have been met.
- `http-connect-not-allowed` — Relay received a request using the CONNECT method which is only supported in [forward proxy mode](#forward-proxy-mode).
- `bad-request` — The server is unable (or refuses) to process the request sent by the client, due to an issue that is perceived by the server to be a client problem.
- `proxy-authentication-required` — A relay with authentication enabled was requested without valid credentials.

## Custom domains

Each relay is provisioned with its own unique `relay.evervault.app` domain. You can also configure additional custom domains for your relay in the Evervault Dashboard by navigating to **Relay → Settings → Domains**.

To add a custom domain, add a CNAME record to your DNS provider that points to `custom-dns.relay.evervault.app`. You also need to add an ownership validation TXT record on the `_ev-custom-domain` subdomain of your custom domain.

> DNS propagation can take anywhere from a few minutes to 24 hours depending on your DNS provider and the TTL settings on your domain. If your custom domain isn't resolving after adding the records, check that both the CNAME and TXT records have been added correctly and allow more time for propagation.

## Alternative configurations

These configurations are possible with Evervault, but not generally recommended. They're only used in specific situations where the default options aren't adequate.

### mTLS

mTLS (mutual TLS) lets Relay authenticate with the target server using a client certificate, adding an additional layer of transport security between Relay and the downstream service. This is typically only required by organizations with strict security policies that mandate mutual authentication at the network layer — most integrations don't need it.

> mTLS must be enabled by Evervault. Contact [support@evervault.com](mailto:support@evervault.com) to request it for your relay.

### Forward proxy mode

The [integration described above](#getting-started) is sufficient for most use cases, but there are some scenarios where you might need to use Relay in forward proxy mode (e.g., you can't change the hostname used by a third party library). Forward proxy mode requires installing the Relay certificate chain, and configuring the relevant traffic to route using Evervault Relay acting as [an HTTP CONNECT proxy](https://en.wikipedia.org/wiki/HTTP_tunnel).

To integrate with Relay in forward-proxy mode, you need to:

- Trust the Relay cert chain on your server. The cert can be obtained from [ca.evervault.com](https://ca.evervault.com).
- Identify the best approach for establishing an HTTP tunnel in your preferred language.
  - For example, in Node.js this is likely using an Agent (which can be created using the [Evervault Node.js SDK](sdks/node#createrelayhttpsagent)), or in JVM-based languages this is through the VM's `http.proxyHost` configuration options.
- Supply your proxy authentication credentials to Relay using basic auth. This can be done during either the initial `CONNECT` request or the subsequent proxied request using the `Proxy-Authorization` header. The value should be basic auth credentials, with your app ID as the username and your API key as the password.
  - Relay only proxies requests to hosts that have been explicitly created in your app and can't be treated as a generic forward proxy.

You can test Relay as a forward proxy using curl:

```sh
curl -x https://relay.evervault.com -U app_id:api_key https://example.com/foo -kv
```

### Using fixed regions

> Using fixed regions isn't generally recommended and Evervault doesn't guarantee reliability or provide an SLA when using a fixed region.

Evervault operates an active-active infrastructure across multiple regions and availability zones. If you need to, you can specify specific regions (either `us` or `eu`) to use with Relay, but this doesn't come with an SLA from Evervault's side. To do this, add `us` or `eu` to your relay URL when making a call. For example, if your base URL is `your-prod-app-12345.relay.evervault.app`, change it to `your-prod-app-12345.us.relay.evervault.app` to send requests to the US region.

- [Functions](/functions): Learn how to use Functions to process encrypted data with your own code.
- [Card Collection](/cards/card-collection): Learn how to use Card Collection to collect cardholder data.


---

# Functions

_Evervault Functions are secure serverless runtimes that decrypt Evervault data at runtime so you can run custom logic safely._

Evervault Functions are secure serverless functions which allow you to process data encrypted by Evervault products. When you pass encrypted data to a function, it's automatically decrypted. You can then process this data by running custom logic written in Node.js or Python as you usually would, but without ever handling it in plaintext on your infrastructure.

## Deploying a function

The quickest way to deploy your first function is to create a starter template by connecting your GitHub account.

1. Sign in to the Evervault Dashboard
2. Create or open an app and navigate to the **Functions** tab
3. Click **Create Function**
4. Select **Choose template**
5. Authenticate with GitHub
6. Select a starter template and deploy your function

> **Using the CLI**
>
> You can also use the [Evervault CLI](/sdks/cli) to deploy a function directly
>   from your machine.

### Redeploying a function

Evervault listens for webhooks from GitHub to determine when to redeploy functions. If function code is in the root directory, all changes in that repository redeploy the function. If function code is in a subdirectory, only changes within that subdirectory trigger a redeploy.

## Running a function

Functions can be invoked using our [SDKs](/sdks), or using our [REST API](/api). Any encrypted data within the payload sent to the function is decrypted before being passed to the function handler.

### Client-side execution

API keys are sensitive and shouldn't be used client-side. When invoking functions from frontend applications, we recommend using a run token. Run tokens are single use, time bound tokens for invoking a function with a given payload. Run tokens last five minutes and must be used with the same payload that was used to create the run token.

Run tokens should be created in your backend using our [API](/api) and handed off to your client.

```javascript
await fetch("https://api.evervault.com/functions/:function-name/runs", {
  method: "POST",
  headers: {
    Authorization: "RunToken <RUN_TOKEN>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payload: { message: "ev:tk9d:wjfiw..." },
  }),
});
```

### Responses

The response from a function run will contain a status field. The status field will be either `success` or `failure`, depending on whether the function completed successfully or not. Any payload returned from the function will be inside of the `result` field of the response object.

```json
{
  "id": "func_run_bd9e16a08f18",
  "status": "success",
  "result": {
    "message": "Hello from a Function!"
  }
}
```

#### Error handling

If there is a failure in the course of a function run, the response will contain an error object with a `message` and `stack` field. The `message` field will contain a human readable error message, and the `stack` field will contain a stack trace of the error.

```json
{
  "id": "func_run_6de494a86a7d",
  "status": "failure",
  "error": {
    "message": "Oh no! Something went wrong",
    "stack": "Error: Oh no! Something went wrong\n    at exports.handler (/runtime/app/index.js:26:15)\n    at /runtime/index.js:65:26\n    at new Promise (<anonymous>)\n    at /runtime/index.js:52:16"
  }
}
```

> **FunctionNotReady**
>
> Functions that have been idle for extended periods of time may return
>   `FunctionNotReady HTTP 409` errors. This can be resolved by retrying the
>   request.

## Encryption within a function

An `encrypt` function can be accessed through the context parameter. This allows you to encrypt data in your response using your app’s keys.

## Configuration

Evervault Functions are configured using a `function.toml` configuration file which can be committed to source control. Simply provide a `function.toml` file in the root of your repository and Evervault automatically includes it at build time.

```toml
[function]
# Customize your function's timeout by providing a positive integer value.
# The timeout is defined in seconds.
# Timeouts of greater than 55 seconds are only permitted for asynchronous function runs.
# Default: 30
# Maximum: 900
timeout = 45

# Customize your function's entry point by specifying the handler in the form `<FILE>.<FUNCTION>`
handler = "main.myFunc"

# The name of your function
name = "your-function-name"

# The language of your function
# Node: node@22, node@24
# Python: python@3.9, python@3.10, python@3.11
language = "node@24"
```

### Dependencies

When you deploy a function to Evervault, we locate your `package.json` (for Node.js) and `requirements.txt` file (for Python) and install any non-development dependencies.

When using Node.js, if a `node_modules` folder is included then dependency installation is skipped; this can be used to include private dependencies.

If there are any issues with your dependencies, for example if you have missed one in your `package.json`, an `InitializationError` is thrown.

Python runtime images (`python@3.9`, `python@3.10`, `python@3.11`) include the `gpg` command line tool, so your function can shell out to it for operations that Python's PGP libraries don't support natively.

### Environment variables

You configure environment variables for functions in the [Evervault Dashboard](https://app.evervault.com) or with the [CLI](/sdks/cli). To use environment variables to store secrets, there're some specific steps you need to take.

#### Encrypted secrets

> Mark all sensitive values (API keys, access tokens, credentials, etc.) as
>   secrets when adding them as environment variables.

You can set an environment variable as a secret when you create it (either in the Dashboard or with the CLI). This encrypts the value at creation time using your app's keys.

Secrets are stored and displayed in their encrypted form in every context except the function handler. At startup, the function runtime decrypts secrets and injects them as environment variables that you can access with `process.env` in Node.js or `os.environ` in Python.

| Context | Value visibility |
| --- | --- |
| Evervault Dashboard | Encrypted |
| CLI `Get` Command | Encrypted |
| Function handler (runtime) | Plaintext |

#### Storing partner API keys

If your function calls a third-party, store its API key, credentials, or any other sensitive data as an environment variable and make sure to [set it as a secret](#encrypted-secrets). This ensures the key is never visible in plaintext in the Dashboard or logs, and is only decrypted inside the function.

### Networking

#### Limiting access to your function

By default, functions respond to requests invoked from any client with a valid Evervault API key or run token. You can limit access to your functions by adding IP addresses to the allowlist in the [Dashboard](https://app.evervault.com). This only allows your functions to be invoked when requests are made from IPs in that list.

#### Limiting egress from your function

By default, functions can send requests to any third-party endpoint. You can add domain names to the allowlist in the [Dashboard](https://app.evervault.com) to limit network access to the hostnames you specify.

### Limitations

Evervault Functions have a maximum memory consumption of `1024MB`, 2 available CPU cores, and 512MB of ephemeral filesystem storage. If you require more memory or CPU cores, check out [Evervault Enclaves](/enclaves) — the easiest way to build, deploy, and scale Secure Enclaves.

> Don't use ephemeral storage for sensitive data. It's possible for ephemeral
>   data to be available to future function invocations, which increases the
>   risk of an accidental data leak.

There are two ways to pass data into functions, and each one has its own limit on the amount you can include. When you run a function with our SDKs or REST API, the payload used for invocation should be kept below 1MB. Separately, after the function is running, you can pull data into it (e.g., downloading and processing files, making an API call to retrieve some information). Data pulled into functions this way should be kept below 1GB.

Rate limits are set at 100 RPM for [Sandbox apps](/developers/sandbox) and 6000 RPM in production. If you need higher rate limits, contact [support@evervault.com](mailto:support@evervault.com).

### Execution time

Evervault Functions have a default execution time of 30 seconds. This can be increased to a maximum of 55 seconds (for synchronous invocations) by setting the `timeout` in the [function.toml](#configuration).

#### Asynchronous functions

Asynchronous function runs up to 15 minutes are also permitted. To execute a function in async mode, you must set the [async argument](/api#createFunctionRun-request-async) on your request payload to `true`.

```javascript
fetch("https://api.evervault.com/functions/hello-function/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic <credentials>",
  },
  body: JSON.stringify({
    async: true,
    payload: {
      name: "ev:Tk9D:oVPHsPvwFHNk73DU:AglNWOgZekolcrxdxSpZJOusBgE+C9eWSapGIZkgTsUj:JKeSkdhVE9SCXqQINID4oBRCE/VhTb56VWGqyObP:$",
    },
  }),
});
```

## Observability

Logs for all function runs can be viewed inside of the [Evervault Dashboard](https://app.evervault.com). You can learn more about observability in our [observability guide](/developers/observability).

- [Relay](/relay): Encrypt or decrypt data in transit—between your app and your own APIs, or any third-party APIs.
- [Card Collection](/cards/card-collection): Learn how to use Card Collection to collect cardholder data.


---

# Enclaves

_Evervault Enclaves let you deploy Docker workloads in AWS Nitro Enclaves with built‑in TLS attestation, networking and tooling._

Evervault Enclaves are the easiest way to build, deploy, and scale applications in a [confidential computing](#what-is-confidential-computing) environment. They allow developers to easily deploy Docker containers in a secure enclave, powered by AWS Nitro Enclaves. They offer easy deployment, invocation, and attestation of secure enclaves without the engineering overhead.

## What is a secure enclave?

A secure enclave — otherwise referred to as a trusted execution environment (TEE) — is a highly constrained compute environment which supports cryptographic attestation of the code that it's running. They have no persistent storage, no shell access, and no networking by default. They allow you to run sensitive workloads in completely segregated environments with heavily restricted external access.

Evervault uses secure enclaves extensively throughout our stack, and they're used to secure parts of our infrastructure which handle sensitive data and key material. This includes the Evervault Encryption Engine (E3), which is powered by AWS Nitro Enclaves.

### Why use secure enclaves?

Secure enclaves are essential for developers seeking strong security guarantees for sensitive workloads. They enable developers to ensure that their code remains untampered by malicious actors through attestation.

Secure enclaves offer all the benefits of standard containerized compute environments, such as Amazon ECS or Kubernetes, while providing additional security through attestation and significantly restricted I/O (e.g., no persistent storage and no networking by default).

Companies that often need to reassure clients about their security posture can delegate much of that responsibility to the secure enclaves architecture. This helps them secure deals with the most security-conscious customers without altering their software development processes.

More importantly, secure enclaves provide developers with the most secure method for deploying sensitive workloads. They significantly reduce the risk exposure of data, applications, and storage from insiders and third parties. As a result, they're rapidly gaining traction among security-conscious businesses and attracting substantial investment from cloud and hardware vendors like AWS, Google Cloud, and Microsoft Azure.

### The anatomy of an enclave

![An illustration of the anatomy of an enclave.]()

Evervault Enclaves are built on top of AWS Nitro Enclaves. A Nitro Enclave is an isolated set of cores on an AWS EC2 instance which provides a segregated environment for running sensitive workloads. Nitro Enclaves are only accessible from the parent EC2 instance over a local VSock channel, and they have no persistence or networking support.

Evervault Enclaves build on this by making it easy to migrate existing Docker-based workloads by abstracting away VSock, supporting optional egress networking, and exposing attestation measures that can be verified by our open source clients. An Evervault Enclave is comprised of two processes to make this possible: the control plane, and the data plane.

#### Control plane

The control plane is a daemon process which runs on the host EC2 instance. The main function of the control plane is to act as a TCP passthrough for incoming TLS connections to the enclave. The control plane also proxies any outgoing network connections for the enclave, enforcing the defined allowlist, and produces the transaction logs for the enclave.

#### Data plane

The data plane runs within the enclave as a sidecar. The data plane performs several functions to allow your process to run without any major changes:

- Proxies traffic from VSock to TCP: One of the biggest barriers to enclave adoption is the ability to use VSock with popular frameworks and languages. The data plane abstracts away the in-enclave networking and forwards incoming traffic to the loopback interface. Your process can bind to a TCP port as normal.
- Terminating TLS: The data plane provisions a trusted TLS certificate to the enclave on start-up. This certificate is used to terminate TLS on incoming connections, ensuring that your requests are only decrypted within the enclave itself.
- Authenticates requests: The data plane ensures that incoming requests have a valid Evervault API key with permissions to invoke the enclave. This feature can be disabled to support invoking the enclave from an untrusted client.
- Decrypts Evervault encrypted data: Evervault encrypted data that's sent to an enclave is transparently decrypted within the data plane before forwarding to your process. This allows you to share encrypted data with your process and handle it in plaintext.
- Enables easy attestation: The Evervault SDKs help you to ensure every request to your enclave is attested within the TLS handshake. This attestation protocol is enabled by the data plane's position in the enclave. When an Evervault client needs to attest an enclave, it pulls an attestation document from the data plane, and uses it to validate every subsequent connection. You can read more about our attestation protocol [here](/enclaves#attestation-in-tls).
- Produces request transaction logs: Running scalable, production services within an enclave can be challenging due to the lack of observability. To combat this, the data plane produces a transaction log of every request. The transaction logs cover a minimal amount of information (status code, request path, standard HTTP headers etc.) to aid debugging without eroding the secure enclave's security model. This feature is configurable, and can be disabled.

## Getting started

All accounts are enrolled in a trial which starts when you deploy your first enclave. The steps below get you up and running with a `Hello World` service, and a client capable of attesting it.

### Set up the Evervault CLI

You can install the Evervault CLI by running the following command in your terminal:

```bash
curl https://cli.evervault.com/v4/install -sL | sh
```

You will also need to have [Docker](https://docs.docker.com/get-docker/) installed on your system as the Enclaves CLI needs to perform Docker builds using the Docker CLI.

**Authenticating the CLI**

The Enclaves CLI currently only supports API key authentication. To set up a session in your terminal, you need to create a scoped app API key in the Evervault Dashboard. After you have the API key, you can authenticate the CLI by setting the following environment variables:

```bash
export EV_API_KEY=<API_KEY> export EV_APP_UUID=<APP_UUID>
```

### Initialize your enclave

To create your first enclave, you’ll need a server and a `Dockerfile`. If you don’t have one already, then you can use our [Hello, Enclave](https://github.com/evervault/hello-enclave) repository as a starting point. You can clone it by running the following command:

```bash
git clone https://github.com/evervault/hello-enclave
```

After you have a server and a `Dockerfile`, you can initialize a new Evervault Enclave using the following command:

```bash
ev enclave init -f ./Dockerfile \
                --name hello-enclave \
                --egress
```

This command generates a new `enclave.toml` [configuration file](#configuration) and registers a new enclave inside of your Evervault app.

Note that we use the `--egress` flag to allow the enclave to make outgoing network requests. This is optional, and you can omit it if you want to create an enclave that only accepts incoming requests.

> **Debug mode**
>
> During development, you may want to enable debug mode to access the logs from
>   the enclave.

### Build your enclave

Now that we have our `enclave.toml`, we can build our enclave. The build command converts the service’s `Dockerfile` into an enclave image file (`.eif`). An `.eif` file is a binary image that we'll use to initialize an AWS Nitro Enclave. All attestation measures are based on the `.eif` binary.

```bash
ev enclave build -v --output .
```

The first build can be slow (approximately 2 minutes) as the CLI has to build several Docker images. Subsequent builds should be faster because the images get cached.

After the enclave is built, its PCRs are written to the `enclave.toml` file. This helps with tracking changes in attestation measures within source control.

Our `enclave.toml` should now have a section that looks something like this at the end of it:

```toml
[attestation]
HashAlgorithm = "Sha384 { ... }"
PCR0 = "8576aa759528d6dc82b6a35504edf491bcf245266acb5745f7f15801e15988a5abbc8c637af3edeb96efcbe8e8a433a1"
PCR1 = "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f"
PCR2 = "4ffe3d8b0211341c9eac73abccfcfed63f694a4a84b7758e70d1941d0ac6c0a7091c7860aa1ff2e4d39bbdd2b220608f"
PCR8 = "9f357c7861268d124143701d30fbd0401f4f2854db7698851c51a08bc719abe9cc89645324d24cdbac1f216b482d6ad8"
```

These four PCR values are the attestation measurements that we will use to trust the remote server (the enclave) before we share any sensitive data with it. The four measurements reflect various aspects of the image you are running in the enclave.

| PCR | Measures | Description |
| --- | --- | --- |
| PCR0 | Enclave Image File | A measure of the Image that will be run within the Enclave. |
| PCR1 | Linux Kernel and Bootstrap | A measure of the kernel and boot ramfs data. |
| PCR2 | User Application | A measure of the User Application without the boot ramfs. |
| PCR8 | Signing Certificate | A measure of the certificate used to sign the Enclave Image File. |

You can read more about attestation for enclaves [here](#attestation).

The build command will also create two files: `enclave.eif` and `ev-user.Dockerfile`. The `enclave.eif` file is the image that the enclave runs in the AWS Nitro Enclave, and the `ev-user.Dockerfile` is the Dockerfile that was used to generate it.

### Deploy your enclave

To deploy your enclave using an existing `.eif` you can run the following command:

```bash
ev enclave deploy -v --eif-path $EIF_PATH
```

The CLI tracks your enclave deployment. After the deployment has stabilized, you should see a log which includes the domain for your enclave:

```bash
Enclave deployed successfully. Your Enclave is now available at https://<enclave_name>.<app_id>.enclave.evervault.com
```

> You can build a fresh `.eif` for a deployment by omitting the `--eif-path`
>   argument. This means you can skip the `ev enclave build` step and deploy in one
>   command.

You can now call your enclave over the internet. If you deployed the Evervault `Hello, Enclave` template, you can use the following cURL command to try it out:

```bash
curl https://<enclave_name>.<app_uuid>.enclave.evervault.com/hello \
  -H "API-Key: <API_KEY>"
```

You should now see an echo response from your enclave:

```json
{
  "response": "Hello! I'm writing to you from within an enclave"
}
```

### Attest your enclave

With your enclave deployed and accessible, we can attest it to verify that its running the code we deployed.

> **Debug mode**
>
> If your enclave is running in debug mode, the attestation measures will be all
>   zeroes. We strongly advise against running in debug mode in a production
>   setting.

To attest the enclave, we'll take the PCR values that we emitted during our deployment and supply them to the Node SDK's `createEnclaveHttpsAgent` function. This function returns an HTTP Agent which can be used to validate that any connections to your enclave's hostname pass an attestation check before establishing a TLS connection.

```javascript
const AttestationBindings = require("@evervault/attestation-bindings");
const encrypted = await evervault.encrypt("Your Data");

const enclaveHttpsAgent = await evervaultClient.createEnclaveHttpsAgent(
  {
    "my-enclave": [{ pcr8: "PCR8FULLHASH" }, { pcr0: "PCR0FULLHASH" }],
  },
  AttestationBindings
);

const response = await axios.post(
  "https://my-enclave.my-app.enclave.evervault.com",
  encrypted,
  {
    httpsAgent: enclaveHttpsAgent,
  }
);
```

You can read more about attestation for enclaves [here](#attestation).

## Encryption and decryption

By design, data that is encrypted with Evervault that passes into the enclave is automatically decrypted. There is no further action required to decrypt and start using the data. If you need to manually encrypt or decrypt data within the enclave, you can use the [internal API](#internal-api).

## Internal API

Evervault exposes a simple internal API within the enclave which allows you to encrypt or decrypt Evervault encrypted strings, as well as manually retrieve an attestation document if you wish to implement your own attestation protocol. This internal API runs on port `9999` by default, and is only accessible from within the enclave.

### /encrypt

To encrypt data, you can make a request to `/encrypt`

```javascript
app.post("/keys", async (req, res) => {
  const { publicKey, privateKey } = crypto.generateKeyPair();
  const encryptedPrivateKey = await axios.post(
    "http://127.0.0.1:9999/encrypt",
    privateKey.toString("base64")
  );
  return res.json({ publicKey, encryptedPrivateKey });
});
```

### /decrypt

> By design, data that is encrypted with Evervault that passes into the enclave
>   is automatically decrypted. There is no further action required to
>   decrypt and start using the data.

The purpose of the decryption API is to offer flexibility with applications built inside the Enclave. Examples could be if you need to upload a list of large files of encrypted data to be decrypted on start up of the enclave or a process that pulls in encrypted data from an external source.

Another point to note is that when TLS termination is turned off in the data plane, it’s not possible for the request to be scanned for encrypted strings. This is another instance where the Decrypt API could be used.

```javascript
const result = await axios.post("http://127.0.0.1:9999/decrypt", {
  encrypted: "ENCRYPTED_STRING",
});
```

> **Files aren't supported**
>
> These endpoints support strings, not files. To decrypt a file, use the
>   [Decrypt endpoint](/api#decrypt) or [Relay](/relay).

### /attestation-doc

To fetch the attestation document for the enclave, you can make a request to `/attestation-doc`. You can provide a challenge, nonce, and public key to be included in the attestation document. Each field is optional.

The challenge and nonce are taken as UTF-8 encoded values, and the `publicKey` is taken as a base64 encoded value.

```javascript
const response = await axios.post("http://127.0.0.1:9999/attestation-doc", {
  challenge: "abc",
  nonce: "123",
  publicKey: "def",
});
```

## Ports

By default, traffic within the enclave is forwarded to port `8008` on loopback. This can be configured by supplying an `EXPOSE` directive in your Dockerfile.

Certain ports are reserved within enclaves for internal services. In certain cases, these ports are only reserved when a feature is enabled. The reserved ports are as follows:

| Port | Reason | Feature |
| --- | --- | --- |
| 9999 | Used by the Internal API | -- |
| 53 | Used to proxy egress DNS calls | [Egress](#egress) |
| 4444 | Used to proxy egress TCP traffic | [Egress](#egress) |

## Environment variables

Environment variables can be configured using the UI or CLI. Secrets can be encrypted on creation and are made available to your enclave environment in plaintext on startup. When you create or modify an environment variable for your enclave, it only takes effect after you redeploy the enclave. You can [restart your enclave's current deployment](/sdks/cli#restart) to redeploy your existing enclave image without affecting it's PCRs.

Details on how to update your enclave's environment variables are detailed in the [Enclaves CLI reference](/sdks/cli#enclaves)

## TLS termination

TLS termination is enabled by default on your enclave. When enabled, any requests to your enclave terminate TLS within the enclave using a cert signed by a trusted CA. With TLS termination enabled, you have access to features like automatic field decryption, authentication using your Evervault API key, and transaction logging. You can disable TLS termination by setting `tls_termination=false` in your `enclave.toml` configuration file.

With TLS termination disabled, you need to terminate TLS on all incoming connections within your own process. This allows for enclaves to perform client authentication for mTLS, or to use self-signed certificates.

> If you disable TLS, you need to configure your Enclave to perform its
>   `healthcheck` on a different port to incoming traffic. This can be done using
>   the healthcheck section of the `enclave.toml` file.

## HTTP transaction logging

When TLS termination is enabled on your enclave, you can enable HTTP transaction logging which propagates request logs to the Evervault **Activity Screen** within the dashboard. These logs contain HTTP status codes, methods, timestamps etc. This can be configured within the `enclave.toml` by setting `trx_logging = false` (default is true).

A unique ID is also appended to each request. This ID can be found in the response headers under `x-evervault-ctx`. You can then search for this ID in the **Activity Screen**.

## Trusted headers

By default, your Enclave's transaction logs obfuscate any non-standard HTTP headers. You can specify a list of headers to pass through using the `trusted_headers` key in the `enclave.toml` file. This can be used to surface error codes or similar diagnostic information from your enclave. For example:

```toml
trusted_headers = ["X-Error-*", "X-Trace-Id"]
```

Certain headers cannot be trusted to avoid accidentally leaking credentials. This currently includes: `api-key`, `authorization`, and `proxy-authorization`.

## Debug mode

If you want to test your Docker Image in an enclave and see the output, you can run your enclave in `debug` mode. Transaction logs are emitted and viewable through the Evervault Dashboard. Raw logs from your enclave can be viewed using the `ev enclave logs` command in the [CLI](/sdks/cli).

> When running an enclave in Debug mode, the attestation measure returned consists entirely of zeroes. This means that an enclave in debug mode is not attestable.

## Egress

By default there is no networking out of an enclave. If you wish to make requests out of the enclave, turn on egress by including `--egress` on enclave init or update the `enclave.toml`.

You can also configure the allowed domains that requests out of the enclave should be allowed to with `--egress-destinations`. The list is enforced in both the data plane and the control plane. Requests to domains that are not explicitly allowed will fail during the DNS lookup. You can specify exact domains or wildcards to allow all subdomains, for example `enclave.evervault.com` or `*.evervault.com`. The default behavior is to allow requests to any domain but we recommend restricting them in production environments.

## Authentication

Enclaves expect an Evervault API key in the `api-key` request header by default. This can be disabled if you wish to implement your own form of authentication to the enclave. This can be useful if your enclave is exposed directly to end users.

## Healthchecks

By default, enclaves perform a shallow healthcheck. The communication between the host instance and the enclave is tested, and the enclave environment is validated to ensure that initialization completed successfully.

This healthcheck can be extended to include a `GET` to the service running in the enclave. Every second, the `Evervault-Healthcheck-Agent` sends a `GET` request to your process. Your process is regarded as healthy if it responds with a successful status code (e.g., 2XX).

You can configure your enclave to perform healthchecks on a dedicated port using the `healthcheck` section of the `enclave.toml` as shown in the toml reference below. This is particularly useful for enclaves that perform their own TLS termination.

## Concurrent request processing

By default, the data plane accepts incoming connections serially. Each connection completes its TLS handshake before the next one is accepted, so a single slow client can delay every other connection waiting behind it.

For workloads that handle many simultaneous connections, you can enable concurrent processing of connection acceptance and TLS handshakes. This improves networking performance by letting handshakes proceed in parallel instead of one at a time.

Concurrent processing is opt-in and configured through the `[acceptor]` table in your `enclave.toml`. When the table is absent, the data plane keeps its serial behavior, so existing enclaves are unaffected.

```toml
[acceptor]
# The maximum number of connections to process concurrently.
max_concurrent_connections = 1024
# The maximum number of TLS handshakes to perform concurrently.
max_concurrent_handshakes = 256
# The timeout for a single TLS handshake, in milliseconds.
handshake_timeout = 10000
```

Each field is optional:

- `max_concurrent_connections` caps the number of connections the data plane processes at once. Connections beyond this limit are terminated (meaning they aren't queued or processed at all).
- `max_concurrent_handshakes` caps the number of in-progress TLS handshakes so the enclave isn't overloaded.
- `handshake_timeout` limits how long a single TLS handshake can take, in milliseconds. Stalled handshakes are dropped after the timeout, freeing the slot for other clients.

Two rules apply when setting these values:

- Any value you set must be greater than zero.
- `max_concurrent_handshakes` must not exceed `max_concurrent_connections`. A connection is accepted before its handshake begins, so extra handshake slots can never be used.

An invalid `[acceptor]` table is rejected when you run `ev enclave init` and at build time, so misconfigurations fail fast rather than producing a broken enclave.

> Tuning the connection cap is a tradeoff. A higher cap admits more concurrent
>   clients, but each connection holds a slot for its full lifetime. Set the cap
>   based on the resources available to your enclave and your expected connection
>   volume.

## Configuration

Enclaves allow configuration to be embedded within the source code, so it is easily attestable and can't be tampered with. Simply include an `enclave.toml` file in the root of your repository and Evervault automatically includes it at build time.

The `enclave.toml` can be used to configure rules such as network egress and debug mode. It also includes dynamic attestation measures so each time your enclave is built, the PCR measures can be verified by comparing the result of the attestation with the measures included in Evervault's TLS attestation.

```toml
# The major version of Enclaves being used
version = 1
# The name of your enclave
name = "hello-enclave"

# The ID of your enclave
uuid = "<YOUR_ENCLAVE_ID>"

# The ID of the Evervault app which is hosting the enclave
app_uuid = "<APP_ID>"

# The ID of the Evervault team which owns the app
team_uuid = "<TEAM_ID>"

# Whether `debug` mode should be enabled.
# Logs are only available in `debug` mode.
debug = true

# Whether API key auth is enabled for the enclave
api_key_auth = true

# Whether transaction logging is enabled for the enclave.
# Note: Requires TLS termination to be enabled
trx_logging = true

# Define a list of headers to ignore during obfuscation of transaction logs.
# Supports absolute matches and suffix wildcards.
trusted_headers = ["X-Error-*", "X-Trace-Id"]

# Turn off TLS termination in the data plane.
# Note: you will have to handle TLS termination within your process.
tls_termination = false

# Enables forwarding proxy protocol when TLS termination is disabled.
# Note: this prepends incoming requests with the binary proxy protocol.
# If your in-enclave process does not expect proxy protocol, it will likely fail to parse requests.
forward_proxy_protocol = false

# The path to your enclave's `Dockerfile`
dockerfile = "Dockerfile"

# Whether or not to enable outbound network requests from your enclave
# If enabled, the networking layer will be bundled at build time
[egress]
enabled = true
destinations = ["*.evervault.com"]

# Configuration for the in-enclave healthcheck.
[healthcheck]
# An endpoint exposed by your service to track its health within the enclave.
# This endpoint will receive a `GET` request every second.
# The healthcheck's user agent will be: "Evervault-Healthcheck-Agent"
path = "/health"
# The port that the healthcheck is being exposed on.
# If unset, the healthcheck will be sent over the same port as incoming requests.
port = 8081

# The amount of replicas you would like to run for your enclave.
# Note: If only running one replica, there will be downtime
# between deployments. (Default 2)
[scaling]
desired_replicas=2

# Opt-in configuration for concurrent connection acceptance and TLS handshakes.
# If unset, the data plane accepts connections serially.
[acceptor]
# The maximum number of connections to process concurrently.
max_concurrent_connections = 1024
# The maximum number of TLS handshakes to perform concurrently.
max_concurrent_handshakes = 256
# The timeout for a single TLS handshake, in milliseconds.
handshake_timeout = 10000

# The configuration for your in-enclave service.
# If unset, the port will be taken as the last exposed port in the Dockerfile.
[service]
port = 8080

# The path to the signing key and certificate for your enclave
[signing]
certPath = "~/.ev/enclaves/cert.pem"
keyPath = "~/.ev/enclaves/key.pem"
```

## Best practices

### Writing the Dockerfile

Since enclaves are built using Docker, a good place to start is making sure that you are [formatting your Dockerfile correctly](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/).

First you need to use the `FROM` command which creates a layer from the Docker image you want to use. It’s best to use one of the container images available on [Docker Hub](https://hub.docker.com/) to ensure you are using a trusted source. You can also opt for using the `slim` version of the container which can help reduce the image size, however the `slim` versions may not contain all of the common packages in the default tag.

```
FROM node:24-alpine3.23
```

Next you need to copy any files from your local source to the filesystem of the container. It’s best to use absolute paths in the Dockerfile. When your Docker container is converted to an enclave, your commands might not be run in the directory you expect them to be, so it is safer to reference your files as absolute paths.

```
COPY ./index.js /index.js
COPY ./package.json /package.json
COPY ./package-lock.json /package-lock.json
```

Make sure that you are exposing the non-reserved port you want to listen on since that is where traffic within the enclave is forwarded. The enclaves documentation uses PORT `8008` as an example, but this can be any available port that you define.

```
EXPOSE 8008
```

Here are some examples of what your Dockerfile might look like.

### Dependency management

Some of the instructions in your Dockerfile install required packages. You can use whichever package manager makes sense for your application.

In some cases, you may want to use a manifest file that contains the required packages and their versions, like a `package.json` for Node or `requirements.txt` for Python.

For Python specifically, it can also be helpful to use a [virtual environment](https://docs.python.org/3/library/venv.html). You can run the virtual environment within the container and then install the packages within the environment. This also helps with minimizing image size.

Here is an example:

```
FROM python:3.13-slim

RUN python3 -m venv /opt/venv
COPY requirements.txt requirements.txt
RUN /opt/venv/bin/pip install -r requirements.txt

COPY app.py /app.py

EXPOSE 8008

ENTRYPOINT ["/opt/venv/bin/python", "/app.py"]
```

## What is confidential computing?

Confidential computing allows teams to run their services in highly constrained compute environments, known as secure enclaves. While confidential computing can take many forms, they typically share two common features — restricted I/O and attestation. These two features are powerful building blocks in creating trustworthy, and secure services.

### Restricted I/O

Secure enclaves have no persistent storage which dramatically reduces the attack surface for data exposure. They also prevent external access — meaning there’s no way for an attacker to gain direct access to a service at runtime. The only interface that the secure enclave exposes is the API that your service offers.

### Attestation

Attestation is a way for the integrity of a service running in a secure enclave to be validated at runtime. This offers teams a guarantee that they're talking to a known version of their service.

In practice, attestation is typically a two step process. Before a service is deployed to a secure enclave, it's measured and signed. Measuring the service involves computing checksums over the bundle that's deployed, and the signature allows teams to lock down deployments to trusted sources (e.g., environments that can sign the bundle using a known private key).

When a client interacts with the service, they can request the attestation document and validate that it contains the expected checksums, and is signed by a known key pair.

Allowing clients to verify the integrity of services that process sensitive data, can massively improve the security of a system by preventing sensitive data from being leaked to unknown or untrusted deployments.

The Evervault Client SDKs for [Node](/sdks/node), [Python](/sdks/python), [Go](/sdks/go), [iOS](/sdks/ios), and [Android](/sdks/android) all expose attestation helpers which perform attestation on every connection to your enclave. This is done by pulling an attestation document from the enclave, and comparing its signed PCRs against the set of PCRs provided to the SDKs. If the PCRs are found to match, the challenge from the attestation document is compared against the certificate public key to confirm that the TLS connection is being terminated inside the enclave.

You can then validate it locally using the `ev enclave attest` command in the CLI. This validates that the PCRs in the `enclave.toml` file match the PCRs returned in the handshake.

The attestation doc for an enclave is publicly accessible through the `/.well-known/attestation` endpoint. This allows the Evervault SDKs to poll the attestation document and detect any changes resulting from deployments.

You can request the attestation document using the following curl command:

```bash
curl https://<enclave_name>.<app_uuid>.enclave.evervault.com/.well-known/attestation-doc
```

#### Attestation in TLS

Attesting a remote server can be difficult to get right, but can be extremely powerful. Evervault Enclaves embed the attestation check within the TLS handshake. This ensures that, when using an Evervault client, you cannot connect to an enclave that fails attestation.

##### CA provisioning

![A flowchart diagram of the CA provisioning flow]()

When your enclave boots within Evervault's infrastructure for the first time, it generates a key pair to use for terminating TLS. The public key for this pair is then used to create an order with a trusted CA using the ACME process. The generated private key never leaves the enclave in plaintext. The Evervault managed process that runs on the host EC2 instance forwards this ACME order to the trusted CA. The trusted CA then returns an ACME challenge which is used to prove ownership over the requested domain. The enclave begins to poll the order status with the trusted CA, which eventually resolves to the issued cert.

The ACME challenge, the generated public key, and the encrypted private key are uploaded to an AWS S3 bucket by the host process. This allows us to reuse the same key pair across deployments of your enclave, and speeds up subsequent deployments.

The trusted CA then sends an HTTP challenge to the enclave's domain. This is routed to an Evervault managed service, which maps the challenge request to the challenge value stored in S3. We serve the challenge in the response to the trusted CA who then issues an end-entity certificate for our enclave.

The order status being polled then resolves with a link to the location of our newly issued certificate. The enclave downloads the certificate and can use it to begin terminating TLS. The enclave also uploads this certificate to S3 via the host process to allow subsequent deployments, or other instances of the enclave to download and reuse the same certificate.

##### Performing attestation from the client

![A flowchart diagram of the attestion flow]()

Now that the enclave has a trusted TLS certificate, we can walk through the process of how a client attests the enclave.

First, when initializing a client, you map a set of enclave names to accepted PCRs. While the implementation differs based on the language being used, the client begins intermittently polling the enclave hostnames in the background. The polling requests hit the publicly available `/.well-known/attestation` endpoint which returns an attestation document. These attestation documents are then stored in an in-memory cache which is checked on every enclave call.

So, when a client is sending a request to an enclave, it begins by performing a standard TLS handshake:

- Validates the hostname corresponds with the requested domain
- Validates that there is a valid trust chain going back to a trusted root CA.

The client then attests the connection:

- Checks the attestation document Cache for the requested enclave.
- Validates the signature over the attestation document against the public AWS Nitro CA.
- Validates that the embedded PCRs match a set of PCRs given to the client on initialization — the remote Enclave is running the expected service.
- Confirms that the public key of the server cert is embedded within the attestation document.

After all of the above checks have passed, the client can begin sending sensitive data into the enclave. This guarantees that the data is sent over a TLS connection directly to the enclave which is running the expected code.

## Enclaves trial

All accounts are enrolled in a trial which starts when you deploy your first enclave. The terms of the trial are given below.

### How long is the trial program?

Starting from the day you deploy your first enclave, you have full access to the Evervault platform (free plan) and enclaves for 14 days, so you can try building and deploying enclaves. After that period, you’ll have the option to sign up for monthly pricing to continue testing.

If you’re unsure how long you have — you can always check the countdown timer in your Evervault Dashboard to see how much time is left in the allotment. If you need to adjust the timing or have any questions regarding the trial, feel free to reach out to our team.

### How many enclaves can I create?

During the 14 day trial period, a team can run one Enclave. Enclaves are run as a single instance which may cause downtime for deployments, however this is only for your trial period.

Following the initial trial, if you upgrade to a paid plan and start using enclaves in production, we will provide multiple instances with high availability and zero downtime deployments.

### What happens during the trial?

You can play around with enclaves to see if it fits your use-case, free of charge. [Start here](#getting-started) if you’re not sure where to get started.

We would love to know more about the use cases you are building for, any errors or bugs you encounter, and any feedback you have. You can contact us at [support@evervault.com](mailto:support@evervault.com).

### What happens after the trial?

At the end of the 14-day period, we’ll notify you that your trial access has ended, and any active enclaves will be deactivated.

Once deactivated, you will no longer be able to send requests to your enclave but it will remain visible in the Evervault Dashboard. If at any time you’d like to continue using enclaves, you can upgrade to a paid plan and we will restart your enclave instances.

Upgrading to the paid plan will give you access to all of the [Evervault Pro](https://evervault.com/pricing) features and allow you to run multiple enclave instances with high availability and zero downtime deployments.

## Frequently asked questions

##### What is an AWS Nitro Enclave?

[AWS Nitro Enclaves](https://aws.amazon.com/ec2/nitro/nitro-enclaves/) is a product from Amazon Web Services that allows you to create isolated Amazon EC2 instances with all of the security characteristics of a Secure Enclave.

    AWS Nitro Enclaves is available by default to customers of Amazon EC2, but building, deploying and scaling Nitro Enclaves can be a major time investment for engineering teams that have competing priorities.

##### How can I access the client IP address?

There are two ways to see the original IP on the connection.

    When using TLS termination, the IP is included in the HTTP `X-Forwarded-For` header.

    If you have TLS termination disabled, you can receive the client IP via proxy protocol by setting the `FORWARD_PROXY_PROTOCOL` environment variable in your enclave.

##### How large can an enclave be?

The current limit for enclaves is `16 vCPUs` and `64 gigabytes` of RAM. For trial usage, enclaves are capped at `4 vCPUs` and `16 gigabytes` of RAM.

    Enclaves use a RAM-based filesystem. This means that the memory allocated to your enclave is used for both storage and RAM.

##### Can I run an enclave on my own infrastructure?

Evervault Enclaves are managed and run by Evervault on our infrastructure. A major advantage of using Enclaves is that the burden of hosting and scaling all of the infrastructure necessary to run secure enclaves is handled by Evervault.

    Evervault running your enclaves doesn't weaken the security guarantees provided by secure enclaves, thanks to attestation. You are still provided with the attestation measure at build-time and can verify that these haven't been tampered with — all within the TLS handshake.

##### Can I run multiple instances of an enclave?

Yes, the number of instances an enclave runs on can be configured using the `desired_replicas` option in the `enclave.toml`. The EC2 instances running the enclave are split between two availability zones in a region for greater resiliency.

    During the trial period, enclaves run as a single instance. During this time, deployments result in downtime.

##### Can I restart my enclave?

Enclaves can be restarted from either the **Versions** tab in the **Enclaves** section of the dashboard or by using the [CLI](/sdks/cli).

##### Why does my enclave perform decrypt requests on start-up?

Enclaves order a trusted TLS certificate on their first deployment. The private key is encrypted in the enclave, and backed-up so it can be loaded in on every subsequent start-up. As a result, when each instance of the enclave launches, they perform a single decrypt request to load in their private key in plaintext.


---

# Browser Tokens

_Use sensitive data in browser automations without exposing it to your application code, your agent, or your browser platform._

> **Alpha**
>
> Browser Tokens are in alpha and subject to change. Contact
>   [support@evervault.com](mailto:support@evervault.com) for access.

Browser Tokens let you use sensitive data in browser automation workflows without exposing that data to your application code, your agent, or your browser infrastructure. They're designed for agentic workflows and headless browser automations that need to enter payment cards, passwords, account credentials, API keys, or other sensitive values into third-party websites.

You send sensitive values to Evervault and receive format-preserving token values along with proxy credentials. Only those tokens are passed to your agent or browser. When the browser submits a request through Evervault's browser proxy, Evervault replaces the token values with the original plaintext over the wire.

## Why use browser tokens

Browser automations increasingly act on behalf of customers in real websites by logging into accounts, buying products, filling forms, and completing workflows. These flows often need sensitive data, which leaves three unappealing options.

- **Give the sensitive data to the agent.** Your application, prompt context, model provider, and browser automation code all become part of the sensitive data handling path.
- **Give the sensitive data to the browser platform.** Headless browser providers are strong at browser infrastructure, but they're rarely designed to handle PCI, credentials, or other regulated data.
- **Use network or issuer-specific agentic payment tokens.** These carry issuer, country, and card brand availability constraints, and each one needs its own integration and user experience.

Browser tokens are a compatibility layer instead. They work with any browser platform, and with any site where the sensitive value is ultimately submitted over the network. For payment flows, that value is usually a card number or CVV. For account access flows, it can be a password, recovery code, API key, or any other credential that shouldn't reach your agent, browser platform, logs, or automation code.

### Comparison to alternatives

| Approach | How it works | Trade-offs |
| --- | --- | --- |
| Raw card data in the agent or browser | The agent or browser automation receives the card number and CVV directly, and enters them into the site. | Simple, but it expands PCI scope to the agent, browser scripts, browser platform, logs, and surrounding infrastructure. Most model providers and browser automation platforms aren't PCI compliant, so this isn't a practical option. |
| Browser platform secret vault | The browser provider stores or injects sensitive values into the session. | Reduces prompt exposure, but puts the browser infrastructure provider in the sensitive data path. Values can still leak to the agent or automation scripts through the Chrome DevTools Protocol (CDP). |
| Issuer or network agentic payment token | A card network or issuer creates a payment-specific token for supported transactions. | Strong where available, but coverage depends on issuer, card brand, geography, and merchant acceptance. Each card brand needs a separate integration, and behavior varies between them. |
| Evervault Browser Tokens | Evervault returns format-preserving tokens, and reveals plaintext only through the browser proxy to allowed hostnames. | Works with existing browser platforms and merchant checkout flows, while keeping the agent and browser platform out of plaintext cardholder data handling. |

## How browser tokens work

1. **Collect and encrypt sensitive data.** Use [Card Collection](/cards/card-collection), a client-side or server-side SDK, or [Relay](/relay) to collect and encrypt sensitive values. These values can be considered non-sensitive and stored in your existing database. You can also provide plaintext values directly when that suits your integration.
2. **Create browser tokens.** Send the sensitive values to [`POST /browser-tokens`](#create-browser-tokens) with [policies](#permissions) that define where the values can be revealed, and optional [egress configuration](#egress-configuration).
3. **Pass token values to your browser automation.** Evervault returns [format-preserving tokens](#token-formats) that look like the original data, so card tokens are Luhn-valid and preserve the original BIN.
4. **Launch your browser through Evervault's proxy.** Route the session through the [browser proxy](#browser-proxy) using the returned credentials. This works with platforms such as Browserbase, Browserless, Kernel, and Steel, as well as local Chromium and Playwright flows.
5. **Evervault replaces tokens over the wire.** Your browser enters token values into the page. Evervault scans requests sent through the proxy and replaces tokens with the original plaintext, but only for allowed destinations.

Evervault doesn't control, inspect, or interfere with the browser session itself beyond the proxy boundary.

## Security model

Browser tokens are designed so that sensitive data never needs to be exposed to:

- your application logic after token creation
- your agent
- your prompt context
- your browser automation script
- your browser platform

This applies to credentials as well as card data. The browser automation can fill a password token into a login form. The agent, model provider, browser platform, and workflow logs only ever see the token value.

Evervault never stores the plaintext or a server-side token mapping. Instead, the encrypted payload is embedded in a time-bound JSON Web Encryption (JWE) token, which is used as the authentication value for the browser proxy. The proxy uses the JWE to determine:

- which token values exist for the session
- what plaintext values they map to
- which hostnames can receive decrypted values
- when the token expires
- what egress configuration to use

If a request is sent to a hostname that isn't allowed by policy, the proxy behaves like a normal forward proxy and doesn't reveal the sensitive value.

## PCI scope reduction

When implemented correctly, browser tokens can keep your browser automation platform, agent, and backend automation infrastructure out of PCI scope. Those systems never transmit, process, or store cardholder data.

In this flow, cardholder data is collected and encrypted using Evervault-controlled collection surfaces before it reaches your automation stack. Your backend creates short-lived browser tokens from encrypted card data, receives format-preserving token values, and passes only those tokens to the agent or browser automation platform. The important boundary is that the systems driving the browser only ever handle tokens.

- **Your agent** sees and reasons over token values, not the card number or CVV.
- **Your browser automation code** fills token values into the page, not cardholder data.
- **Your browser automation platform** renders, stores, logs, and transmits token values through the browser session, not plaintext cardholder data.
- **Your backend infrastructure** stores encrypted values and creates scoped tokens, but doesn't need to store, log, or transmit plaintext cardholder data as part of the browser workflow.

Plaintext cardholder data is revealed only inside Evervault's browser proxy, and only when a request is sent to a destination hostname allowed by policy. The merchant or PSP receives the original cardholder data over the network. The agent, browser platform, and automation backend stay outside the cardholder data environment because they never touch the plaintext value.

To preserve this scope reduction, production integrations should:

1. Collect card data with [Card Collection](/cards/card-collection), an Evervault SDK, or [Relay](/relay).
2. Store only Evervault-encrypted card data in your systems.
3. Create short-lived browser tokens immediately before the automation session.
4. Pass only token values to the agent, browser runtime, logs, queues, and workflow systems.
5. Route the browser session through Evervault's browser proxy using the returned proxy credentials.
6. Scope reveal policies to the exact merchant or PSP hostnames the workflow needs.
7. Avoid logging, persisting, screenshotting, or otherwise exposing plaintext cardholder data anywhere in the automation stack.

## Create browser tokens

Create browser tokens just in time for a specific browser automation session.

```bash
curl -X POST 'https://api.evervault.com/browser-tokens' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "data": [
      { "category": "card.number", "value": "ev:encrypted:...", "id": "user-5577e072-primary-card-pan" },
      { "category": "card.cvv", "value": "ev:encrypted:...", "id": "user-5577e072-primary-card-cvv" },
      { "category": "credential.password", "value": "ev:encrypted:...". "id": "user-5577e072-merchant-login" }
    ],
    "ttl": 300,
    "permissions": [
      {
        "action": "reveal",
        "target": "www.example-merchant.com"
      },
      {
        "action": "decrypt",
        "target": "api.payment-gateway.com"
      }
    ],
    "proxySettings": {
      "type": "custom",
      "scheme": "https",
      "username": "egress-proxy-user-1ef0172b",
      "password": "egress-proxy-password",
      "hostname": "residential-ip-proxy.com",
      "port": 443
    }
  }'
```

**Request body**

- `data` `array` _(required)_ — The sensitive values to convert into browser-safe token values. Values can be Evervault-encrypted or plaintext.
  - `category` `string` _(required)_ — The semantic type of the value, such as `card.number`, `card.cvv`, `credential.password`.
  - `value` `string` _(required)_ — The sensitive value. Use Evervault-encrypted values for production integrations.
  - `id` `string` _(required)_ — The identifier for the data being tokenized. Used to correlate tokens within your system, and reflected in the Evervault logs.
- `permissions` `array` _(required)_ — The rules that define where token values can be revealed as plaintext. See [Permissions](#permissions).
  - `action` `string` _(required)_ — The action to allow. Use `reveal`.
  - `target` `string` _(required)_ — The hostname that can receive the plaintext value. Use `*` to support open egress. We recommend restricting hostnames wherever possible to prevent data leakage.
- `ttl` `number` — How long the tokens remain valid, in seconds. Defaults to `300`.
- `proxySettings` `object` — The egress proxy configuration for the session. See [Egress configuration](#egress-configuration).
  - `type` `string` — Either `custom`, `datacenter` or `residential`. Use `custom` to bring your own egress proxy.
  - `scheme` `string` — Either `http` or `https`. Use `https` if your egress proxy supports CONNECT-over-TLS, otherwise use `http`.
  - `username` `string` — Required for `custom` proxySettings. Used as the username in basic auth with the CONNECT proxy.
  - `password` `string` — Required for `custom` proxySettings. Used as the password in basic auth with the CONNECT proxy.
  - `hostname` `string` — Required for `custom` proxySettings. The hostname of the CONNECT proxy for all egress calls.
  - `port` `number` — Required for `custom` proxySettings. The port of the CONNECT proxy for all egress calls.
  - `country` `string` — The ISO country code to use for geographic routing.
  - `region` `string` — The region or state to route through, where supported.
  - `city` `string` — The city to route through, where supported.
  - `postalCode` `string` — The postal or ZIP code to route through, where supported.

The response contains a token for each value you sent, along with the proxy credentials for the session.

```json
{
  "sessionId": "browser_3eecefc9ac41",
  "data": [
    { "category": "card.number", "value": "4242424242424242", "id": "user-5577e072-primary-card-pan" },
    { "category": "card.cvv", "value": "123", "id": "user-5577e072-primary-card-cvv" },
    { "category": "password", "value": "uG7q9vK2pL", "id": "user-5577e072-merchant-login" }
  ],
  "proxyConfiguration": {
    "hostname": "us-va.browser.relay.evervault.app",
    "port": 443,
    "username": "app_...",
    "password": "eyJ..."
  },
  "expiresAt": "2026-08-20T21:46:14Z"
}
```

The `proxy.password` is a time-bound encrypted JWE. Evervault doesn't store the mapping between token values and plaintext values.

## Token formats

Browser tokens are format-preserving where applicable, so they pass browser and merchant-side validation.

| Data type | Token format |
| --- | --- |
| Card number | Luhn-valid, and preserves the original card length and BIN where applicable. |
| Card CVV | Preserves digit length, including three-digit and four-digit CVVs. |
| Expiry date | Usually doesn't need tokenization. The expiry month and year can typically be passed through as non-sensitive values. |
| Email | Preserves email shape. |
| Phone number | Preserves country or region shape and digit count where applicable. |
| Password | Preserves a browser-compatible string shape. |

## Permissions

Permissions define where token values can be revealed as plaintext. Scope each policy as tightly as possible.

```json
{
  "action": "reveal",
  "target": "payments.example.com"
}
```

- A token is revealed only when the browser request is routed through Evervault's browser proxy, and the destination hostname matches an allowed policy.
- Multiple policies allow multiple destinations. Treat them as an allowlist.
- If a merchant checkout posts card data to a PSP, gateway, or embedded payment iframe, include the hostnames that actually receive the cardholder data.
- If the browser navigates or redirects to a hostname that isn't allowed, Evervault doesn't reveal the plaintext value to that hostname.
- Keep policies environment-specific. For example, use separate hostnames for sandbox and production payment flows.

Avoid broad policy rules. The intended production posture is to reveal only to the exact merchant, PSP, or gateway endpoints the workflow needs.

## Token lifecycle

Token values are useful only with the matching proxy credentials and policy context. After expiry, the proxy credentials can no longer be used to reveal the underlying plaintext.

1. Store the underlying sensitive value as Evervault-encrypted data.
2. Create browser tokens immediately before launching or attaching to the browser session.
3. Pass token values and proxy credentials only to the systems that need them for that session.
4. Use the shortest `ttl` that gives the automation enough time to complete.
5. Discard token values and proxy credentials once the workflow finishes or the `ttl` expires.

A workflow can take longer than expected because of login, multi-factor authentication (MFA), queueing, or human takeover. Set the `ttl` to cover that expected session duration rather than creating long-lived reusable tokens.

## Browser proxy

Browser tokens use Evervault's browser proxy, which is exposed as an HTTP `CONNECT` proxy.

```
us-va.browser.relay.evervault.app # US Proxy
eu-ie.browser.relay.evervault.app # EU Proxy
```

When launching your browser, configure the platform's proxy settings with the credentials returned by the Browser Tokens API.

### Trust the Evervault CA

Because the browser proxy replaces token values with plaintext over the wire, the browser session must trust Evervault's certificate authority. Download the Evervault CA certificate from `https://ca.evervault.com`, then install it as a trusted root CA in the browser runtime before routing traffic through the proxy. The exact setup depends on the browser provider.

- For local Chromium or Playwright, add the CA certificate to the operating system or browser trust store used by the automation runtime.
- For hosted browser platforms, configure the session to trust the Evervault CA if the platform supports custom root certificates.
- If the platform doesn't support custom root certificates, confirm whether it offers an equivalent certificate trust or proxy configuration path.

> **Don't bypass certificate errors**
>
> Without the Evervault CA in the browser's trust store, HTTPS pages can show
>   certificate errors or block requests routed through the proxy. Configure CA
>   trust explicitly instead of disabling certificate verification.

## Launch a browser session

The safest production pattern splits collection, token creation, and browser automation into separate steps. Your database stores encrypted card data, and your backend creates short-lived tokens. The agent and browser see only token values, so Evervault reveals plaintext to the allowed payment hostname alone.

### Hosted browser platforms

Most browser platforms let you provide proxy configuration when creating or connecting to a session. The exact launch configuration depends on your platform.

For example, using [Browserbase](https://browserbase.com) the integration would look like this:

Connect your automation to the session, then use the token values returned by Evervault in your browser steps.

## Credential and account access flows

Browser tokens aren't limited to payment data. The same pattern works anywhere a browser automation needs to submit a secret to a third-party website without exposing that secret to the agent or browser platform. Common credential use cases include:

- logging into a customer account with a password
- entering a recovery code or one-time backup code
- submitting an API key into a developer portal
- filling tax IDs, identity numbers, or other sensitive form fields
- completing internal admin workflows that need privileged credentials

The flow is the same as a payment flow. Collect or store the credential as an Evervault-encrypted value, then create a short-lived browser token scoped to the destination hostname. Give the agent and browser automation only the token value, and route the browser session through the browser proxy. Evervault reveals the plaintext credential over the wire to the allowed hostname.

For example, if an automation needs to log into `accounts.example.com`, the agent can navigate the site and fill a password token into the password field. The browser platform sees a browser-compatible token string, and Evervault reveals the original password only when the login request is sent through the proxy to the allowed hostname. This keeps credentials out of prompts, traces, screenshots, session recordings, browser-provider logs, and application logs, provided those systems only receive token values.

## Egress configuration

Browser tokens can be used with Evervault-managed egress IP configuration. Set the `proxySettings` object when creating tokens to control the type and location of the IP the session routes through.

```json
{
  "proxySettings": {
    "type": "residential",
    "country": "us",
    "city": "ny",
    "postalCode": "10013"
  }
}
```

Browser tokens only handle network egress. If your browser automation also needs timezone, locale, viewport, or geolocation alignment, configure those settings in your browser platform.

## Anti-bot compatibility

Evervault's proxy is designed to preserve compatibility with real browser traffic. It uses TLS and HTTP client impersonation techniques, so network fingerprints such as JA4 match expected browser behavior.

Evervault doesn't attempt to solve browser-level automation challenges such as CAPTCHAs, MFA, 3D Secure, or human-in-the-loop flows. Browser platforms often provide session takeover or human intervention features for those cases.

## Limitations

Browser tokens are a network-layer compatibility layer. They don't replace browser automation, fraud controls, or checkout orchestration.

- **Client-side encryption can require site-specific handling.** Some sites encrypt sensitive values in the browser before sending them over the network. Browser tokens still work where the site accepts raw values, but some PSP-specific flows need shims, which Evervault manages on your behalf.
- **3D Secure and MFA remain application and browser concerns.** Frictionless 3D Secure works normally, but challenge flows usually require user interruption or browser-platform session takeover.
- **Spending controls aren't enforced at the network layer.** Browser tokens can restrict where values are revealed, but transaction authorization stays with the issuer or payment processor.
- **Tokens are time-bound rather than single-use.** A token can be used more than once within its `ttl`, so keep the `ttl` as short as the workflow allows.
- **The browser session is outside Evervault's security boundary.** Evervault doesn't drive or inspect the browser session beyond proxying network traffic. Policies still ensure that sensitive data is never decrypted and revealed to a hostname you haven't explicitly allowed.

## Recommended integration pattern

For production use:

1. Collect card or sensitive data with [Card Collection](/cards/card-collection), an Evervault SDK, or [Relay](/relay).
2. Store only Evervault-encrypted values in your database.
3. Create short-lived browser tokens when starting a browser automation session.
4. Scope policies to the exact hostnames the workflow needs.
5. Use the shortest `ttl` that gives your automation enough time to complete.
6. Configure the browser session with Evervault's proxy credentials.
7. Pass only token values to the browser automation or agent.
8. Log which token categories were revealed, and to which destinations, after the session completes.


---

# Fingerprint

_Use Evervault's Fingerprint API retrieve metadata for encrypted values._

> The Inspect API is now called [Fingerprint](/api#fingerprint). Existing integrations using the `/inspect` endpoint will continue to work, but migrate to `/fingerprint` when possible. Pricing is unchanged (Inspect pricing hasn't changed, and Fingerprint costs the same as Inspect).

Use the [Fingerprint API](/api#fingerprint) to retrieve metadata about any encrypted value. For example, if you pass an encrypted card, you can retrieve the card brand, the last four digits, etc.

```javascript
const response = await fetch("https://api.evervault.com/fingerprint", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    token:
      "ev:debug:Tk9D:HBpzdbFWXbX/N2cC:AyjMY/SKO49SlkXcDPtCGs+DxnUn/F8/lAtajCYZ/xT7:KV7AUn9vJJkZDtL8PKdOc8Y11yTL2vZQasFuHqM=:$",
  }),
});
```

The API responds with an object containing details about the encrypted data, as well as the card metadata inside of the `metadata` field.

```json
{
  "type": "string",
  "category": "card-number",
  "encryptedAt": 1700067122000,
  "role": null,
  "fingerprint": "u0ljSwrqhhUv7GykyCHB/A2bgVGXq06fnG9bOI27Sbg/tAOz3myr5zsfbasEWuMLiH6jZayu3AHGfiB7l+Bbjg",
  "metadata": {
    "bin": "424242",
    "lastFour": "4242",
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp",
    "issuer": "Gringotts Wizarding Bank and Trust Company"
  }
}
```

## BIN Lookup vs. Fingerprint

| Metadata | Description | Fingerprint | BIN Lookup |
| --- | --- | --- | --- |
| Fingerprint | A unique identifier for the encrypted card. This can be used to detect card reuse. | ✓ | ✗ |
| BIN | The first 6 or 8 digits of the card number. | ✓ | ✗ |
| Last 4 | The last 4 digits of the card number. | ✓ | ✗ |
| Brand | The card brand, such as Visa or Mastercard. | ✓ | ✓ |
| Funding | The card funding type specifies the method by which transactions are financed (e.g. debit, credit). | ✓ | ✓ |
| Segment | The card segment indicates the primary market or usage category of the card (e.g. consumer, etc.). | ✓ | ✓ |
| Country | The country where the card was issued. | ✓ | ✓ |
| Currency | The currency of the card. | ✓ | ✓ |
| Issuer | The name of the card issuer. | ✓ | ✓ |
| Product Name | The name of the card product. | ✗ | ✓ |
| Fast Funds | Indicates whether the card supports fast funds (e.g. domestic, cross-border). | ✗ | ✓ |
| Match Precision | Indicates how many leading digits of the submitted BIN are confirmed by the matched data. A higher value means a more specific match. When multiple matches are found, the value represents the least precise BIN range the submitted BIN could belong to. | ✗ | ✓ |
| Three DS | Details on supported 3D Secure versions and ACS indicators for the card range. | ✗ | ✓ |

See [BIN Lookup](/cards/insights-and-verification#bin-lookup) for retrieving metadata for a BIN range instead of a single encrypted card.

- [Relay](/relay): Learn how to use Relay to encrypt or decrypt data in transit, without changing your application code.
- [Functions](/functions): Learn how to use Functions to process encrypted data with your own code.


---

# Card Collection

_Collect and encrypt cardholder data in a PCI-compliant iframe, then safely use it with your APIs and processors via Relay._

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](/relay). This guide walks you through the entire process using our Card component for collection.

<CornerFrame>
  <CardCollection />
</CornerFrame>

## 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](https://www.pcisecuritystandards.org/standards/pci-dss/) scope because Evervault hosts the iframe, and you never handle plaintext card data.

## Get started with the Card component
### Install the Evervault SDK

#### Browser

Our [JavaScript SDK](/sdks/javascript) is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the [Evervault Dashboard](https://app.evervault.com).

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

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

#### Frequently Asked Questions

##### Why does the SDK need to be loaded from the CDN?

The SDK must be loaded directly from our CDN in order to be PCI Compliant.

##### How do I get my Team ID and App ID?

You can find your Team ID and App ID in the [Evervault Dashboard](https://app.evervault.com).

##### Can I load the SDK asynchronously?

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <script src="https://js.evervault.com/v2" onload="onEvervaultReady()" async></script>
        <script>
          function onEvervaultReady() {
            const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
          }
        </script>
      </head>
    </html>
    ```

#### React

Our React SDK is distributed via npm and can be installed using your preferred package manager.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

#### Browser

### Create a Card component

Initialize the Card component and mount it to a DOM element. See the [SDK documentation](/sdks/javascript#uicard) for available parameters.

```javascript
const card = evervault.ui.card({
  theme: evervault.ui.themes.clean(),
});
card.mount("#card-details");
```

#### React

### Render the Card component

The `<Card />` component can be mounted in any child of the `EvervaultProvider`. The `onChange` prop is called every time the customer updates their card data, and includes the encrypted card data as well as validation information. You can use this to store the card data in state and pass it to your backend to process a payment. See the [SDK documentation](/sdks/react#card) for other available props.

```jsx
import { Card } from "@evervault/react";

export function Checkout() {
  const [cardData, setCardData] = useState(null);

  const handleCheckout = () => {
    if (!cardData.isValid) {
      // The user has entered an invalid card.
      return;
    }

    // Pass the encrypted card data to your backend
    fetch("my-api.com/checkout", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        number: cardData.card.number,
        expiry: cardData.card.expiry,
        cvc: cardData.card.cvc,
      }),
    });
  };

  return (
    <>
      <Card onChange={setCardData} />
      <button onClick={handleCheckout}>Checkout</button>
    </>
  );
}
```

You can customize the appearance of the Card component by passing a custom theme or extending one of our prebuilt themes. Read more about [customization](/cards/card-collection#customization).

#### Browser

### Submit the encrypted card data to your API

The encrypted card values can be accessed from the `card.values` object or by subscribing to the `change` event with the `card.on` method.

Inside your submit handler, you can access the encrypted card data and pass it to your backend.

```javascript
function handleSubmit() {
  // Pass the encrypted card data to your backend
  fetch("my-api.com/checkout", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      number: card.values.card.number,
      expiry: card.values.card.expiry,
      cvc: card.values.card.cvc,
    }),
  });
}
```

#### React Native

Our React Native SDK provides a set of premade components for collecting and encrypting card data in a safe and secure way.

### Install the Evervault SDK

Our React Native SDK is distributed via `npm` and can be installed using your preferred package manager. The [react-native-webview](https://www.npmjs.com/package/react-native-webview) package is a peer dependency and will need to be installed as well.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react-native";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

### Render the Card component

The `<Card />` component can be mounted in any child of the `EvervaultProvider`. The `onChange` prop is called every time your customer updates their card data, and includes the encrypted card data as well as validation information. You can use this to store the card data in state and pass it to your backend to process a payment.

```tsx
import { Card, type CardPayload } from '@evervault/react-native';
import { Button, Form } from '@your/ui";

type CardFormProps = {
  onSubmit: () => void;
};

function CardForm({ onSubmit }: CardFormProps) {
  const [data, setData] = useState<CardPayload | null>(null);

  return (
    <Form>
      <Card onChange={setData}>
        <Card.Number />
        <Card.Expiry />
        <Card.Cvc />
      </Card>

      <Button disabled={!data?.isValid || !data?.isComplete} onPress={onSubmit}>
        Pay
      </Button>
    </Form>
  );
}
```

Learn more about the Card component in the [React Native SDK documentation](/sdks/react-native#card).

### Submit the encrypted card data to your API

The last step is to submit the encrypted card details to your API so they can be forwarded on to your payment processor.

```tsx
function Checkout() {
  const handleSubmit = (data: CardPayload) => {
    // Pass the encrypted card data to your backend
    fetch("my-api.com/checkout", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        number: data.card.number,
        expiry: data.card.expiry,
        cvc: data.card.cvc,
      }),
    });
  };

  return (
    <>
      <CardForm onSubmit={handleSubmit} />
    </>
  );
}
```

#### Swift

The Evervault iOS SDK includes an `EvervaultInputs` module, which provides a SwiftUI view called `PaymentCardInput`. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data.

### Install the Evervault SDK

The Evervault iOS SDK can be installed using the Swift Package Manager.

1. Open your Xcode project.
2. Navigate to _File > Swift Packages > Add Package Dependency_.
3. Enter the repository URL for the Evervault iOS SDK: `https://github.com/evervault/evervault-ios.git`
4. Choose the latest available version or specify a version rule.

After you install the SDK, you can initialize it with your Team ID and App ID.

```swift
import EvervaultCore

Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

### Render the Card component

To use `PaymentCardInput`, make sure you import the `EvervaultInputs` module in your file, and then add the view to your SwiftUI hierarchy. See the [SDK documentation](/sdks/ios#inputs) for available parameters.

```swift
import EvervaultInputs

struct ContentView: View {

    @State private var cardData = PaymentCardData()

    var body: some View {
        VStack {
            PaymentCardInput(cardData: $cardData)

            // Data captured:
            Text("Encrypted credit card number: \(cardData.card.number)")
        }
    }
}
```

#### Android

The Android SDK provides a Compose view called `PaymentCard`. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data.

### Install the Evervault SDK

Our Android SDK distributed via [maven](https://central.sonatype.com/search?q=com.evervault.sdk), and can be installed using your preferred build tool.

#### Android

Before using the Evervault Android SDK, you need to configure it with your Evervault Team ID and App ID. This step is essential for establishing a connection with the Evervault encryption service. You can find these in the [Evervault Dashboard](https://app.evervault.com).

```java
Evervault.shared.configure("<TEAM_ID>", "<APP_ID>")
```

### Render the PaymentCard view

Once the SDK is installed and configured, you can use the `PaymentCard` view to capture encrypted card data.

```java
UserParentLayout {
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    // ...
    PaymentCard(onDataChange = onDataChange) {
        // User custom payment card layout using the [PaymentCardInputScope] components with a combination of user own components and modifiers
    }
}
```

You can learn more about the `PaymentCard` view in the [Android SDK documentation](/sdks/android#inputs).

## 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](/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.

![An illustration of a credit card being decrypted by a relay.]()

### Create a Relay

To simplify this example, we'll use [PutsReq](https://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](https://app.evervault.com), click **Create Relay**, and add the PutsReq endpoint to the destination field.

![Screenshot of the Relay creation form in the Evervault Dashboard.]()

### 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](/relay#selecting-fields).

![Screenshot of a Relay configured to decrypt all data in the request body.]()

### 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.

#### Node

```javascript
// Replace with Relay URL
const relayURL = "<PUTSREQ_RELAY_URL>";

// POST /checkout
router.post("/checkout", async (req, res) => {
  try {
    const response = await fetch(relayURL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Evervault-App-Id": "<APP_ID>",
        "X-Evervault-Api-Key": "<API_KEY>",
      },
      body: JSON.stringify({
        number: req.body.number,
        expiry: req.body.expiry,
        cvc: req.body.cvc,
      }),
    });

    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
```

#### Python

```python
# Replace with Relay URL
relay_url = "<PUTSREQ_RELAY_URL>"

# Route handler for /checkout
@app.route("/checkout", methods=["POST"])
def checkout():
    try:
        payload = {
            "number": request.json["number"],
            "expiry": request.json["expiry"],
            "cvc": request.json["cvc"]
        }

        headers = {
            "Content-Type": "application/json",
            "X-Evervault-App-Id": "<APP_ID>",
            "X-Evervault-Api-Key": "<API_KEY>"
        }

        response = requests.post(relay_url, json=payload, headers=headers)
        return jsonify(response.json())
    except Exception as e:
        return jsonify({"error": str(e)}), 500
```

#### Ruby

```ruby
# Replace with Relay URL
relay_url = "<PUTSREQ_RELAY_URL>"

# POST /checkout
post "/checkout" do
  begin
    payload = {
      number: params[:number],
      expiry: params[:expiry],
      cvc: params[:cvc]
    }

    headers = {
      "Content-Type" => "application/json",
      "X-Evervault-App-Id" => "<APP_ID>",
      "X-Evervault-Api-Key" => "<API_KEY>"
    }

    response = HTTParty.post(
      relay_url,
      body: payload.to_json,
      headers: headers
    )

    content_type :json
    response.body
  rescue => e
    status 500
    { error: e.message }.to_json
  end
end
```

#### Java

```java
// Replace with Relay URL
private static final String RELAY_URL = "<PUTSREQ_RELAY_URL>";

@PostMapping("/checkout")
public ResponseEntity<?> checkout(@RequestBody Map<String, String> requestBody) {
    try {
        // Create request payload
        Map<String, String> payload = new HashMap<>();
        payload.put("number", requestBody.get("number"));
        payload.put("expiry", requestBody.get("expiry"));
        payload.put("cvc", requestBody.get("cvc"));

        // Set up HTTP client
        HttpClient client = HttpClient.newHttpClient();

        // Create request with headers
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(RELAY_URL))
            .header("Content-Type", "application/json")
            .header("X-Evervault-App-Id", "<APP_ID>")
            .header("X-Evervault-Api-Key", "<API_KEY>")
            .POST(HttpRequest.BodyPublishers.ofString(new ObjectMapper().writeValueAsString(payload)))
            .build();

        // Send request and get response
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        return ResponseEntity.ok(response.body());
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(Map.of("error", e.getMessage()));
    }
}
```

#### PHP

```php
// Replace with Relay URL
$relayUrl = "<PUTSREQ_RELAY_URL>";

// POST /checkout
app->post('/checkout', function ($request, $response) use ($relayUrl) {
    try {
        $data = $request->getParsedBody();

        $payload = json_encode([
            'number' => $data['number'],
            'expiry' => $data['expiry'],
            'cvc' => $data['cvc']
        ]);

        $ch = curl_init($relayUrl);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-Evervault-App-Id: <APP_ID>',
            'X-Evervault-Api-Key: <API_KEY>'
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $result = curl_exec($ch);
        curl_close($ch);

        $response->getBody()->write($result);
        return $response->withHeader('Content-Type', 'application/json');
    } catch (Exception $e) {
        $response->getBody()->write(json_encode(['error' => $e->getMessage()]));
        return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
});
```

#### Go

```go
// Replace with Relay URL
var relayURL = "<PUTSREQ_RELAY_URL>"

// POST /checkout
func checkoutHandler(w http.ResponseWriter, r *http.Request) {
	var requestBody map[string]string
	if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	payload := map[string]string{
		"number": requestBody["number"],
		"expiry": requestBody["expiry"],
		"cvc":    requestBody["cvc"],
	}

	payloadBytes, err := json.Marshal(payload)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	req, err := http.NewRequest("POST", relayURL, bytes.NewBuffer(payloadBytes))
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Evervault-App-Id", "<APP_ID>")
	req.Header.Set("X-Evervault-Api-Key", "<API_KEY>")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
	defer resp.Body.Close()

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(resp.StatusCode)
	io.Copy(w, resp.Body)
}
```

> **Relay authentication**
>
> Notice we are sending the `X-Evervault-App-Id` and `X-Evervault-Api-Key`
>   headers to the Relay. These headers are used to authenticate the request to
>   the Relay. We recommend enabling [Relay
>   authentication](/relay#authentication) when sending requests to third-party
>   APIs.

## Customization

The Card component can be fully customized to match the design of your application. By default, the Card component has no styling applied. You can use one of our prebuilt themes to get up and running or build your own theme from scratch.

### Prebuilt themes

The SDK has three themes to get you started: `clean`, `minimal`, and `material`.

#### Browser

```javascript
evervault.ui.card({
  theme: evervault.ui.themes.clean(),
});
```

#### React

```jsx
import { Card, themes } from "@evervault/react";

function Checkout() {
  return <Card theme={themes.clean()} />;
}
```

### Custom themes

A theme is just an object with a `styles` property. The `styles` property uses a CSS-as-JS format to define CSS rules for the component. These rules are compiled to CSS and injected into the iframe.

<CornerFrame style={{ marginBottom: "2rem" }}>
  <CardTheme theme="custom" editable />
</CornerFrame>

You can pass a custom theme as an argument to any of the prebuilt themes to extend them.

```javascript
evervault.ui.themes.clean({
  styles: {
    label: {
      color: "#6633ee",
    },
  },
});
```

#### Element attributes

Although you can customize the CSS inside of the iframe, you can't modify the HTML. We know that layout can have a big impact on style definitions and so to help with this, we apply custom attributes to various elements within the iframe. These attributes are prefixed with `ev-`.

You can see our premade [UI component themes](https://github.com/evervault/evervault-js/tree/master/packages/themes) for an example of how these attributes can be used when creating themes.

**fieldset attributes**

The following attributes are added to the `<fieldset />` tag that wraps the entire component.

- `ev-component` `Card` — The name of the component.
- `ev-valid` `true | false` — Whether or not all of the fields within the component are valid.

**.field Attributes**

Each field in the component is wrapped in a <div /> with a '.field' class and the following attributes.

- `ev-name` `name | number | expiry | cvc` — The name for the individual field within the component.
- `ev-valid` `true | false` — Whether or not the field is valid.
- `ev-has-value` `true | false` — Whether or not the input has a value.

### Custom fonts

You can load additional fonts from Google Fonts by providing a `fonts` array in the theme definition. Currently, we only support custom fonts via Google Fonts.

```javascript
const theme = {
  fonts: ["https://fonts.googleapis.com/css2?family=Comic+Neue"],
  styles: {
    input: {
      fontFamily: "'Comic Neue'",
    },
  },
};
```

### Responsive styling

You can define media queries inside of the themes `styles` object, however, this may lead to unexpected behaviour as the media queries are matched against the iframe document, not the parent document. To get around this, we provide a `media` utility which allows you to define styles based on media queries that match the parent document.

To access the media utility, you need to define your theme as a function that returns a theme object. This function is passed a utilities object as an argument, which contains the `media` utility. The media utility should be spread into the styles object of the returned theme.

```javascript
const theme = (utilities) => {
  return {
    styles: {
      label: {
        fontSize: 16,
      },
      ...utilities.media("(max-width: 400px)", {
        label: {
          fontSize: 20,
        },
      }),
    },
  };
};
```

### Custom card brands

By default, the card component recognizes a fixed set of card networks but you can extend it with your own brands using `evervault.brands.create`. This creates a brand which you can then pass into the card component with the `customBrands` option.

#### Browser

```javascript
const acmeBrand = evervault.brands.create("acme-card", {
  numberValidationRules: {
    ranges: [[88000, 88999]],
    lengths: [16],
  },
  securityCodeValidationRules: {
    lengths: [3],
  },
  iconSrc: "https://your-cdn.com/acme-icon.svg",
});

const card = evervault.ui.card({
  customBrands: [acmeBrand],
});

card.on("change", (data) => {
  // "acme-card" appears in data.card.localBrands when a matching number is entered
  console.log(data.card.localBrands);
});
```

#### React

```jsx
import { useMemo } from "react";
import { Card, useEvervault, BrandOptions } from "@evervault/react";

const acmeBrand: BrandOptions = {
  numberValidationRules: {
    luhnCheck: true,
    ranges: [9900, [88000, 88999]],
    lengths: [16],
  },
  securityCodeValidationRules: {
    lengths: [4],
  },
  iconSrc: "https://example.com/logo.png",
};

export function Checkout() {
  const evervault = useEvervault();

  const customBrands = useMemo(() => {
    if (!evervault) return;

    return [evervault.brands.create("acme-card", acmeBrand)];
  }, [evervault]);

  return (
    <Card
      customBrands={customBrands}
      onChange={(data) => {
        // "acme-card" appears in data.card.localBrands when a matching number is entered
        console.log(data.card.localBrands);
      }}
    />
  );
}
```

The `ranges` argument accepts a BIN prefix (e.g., `9900`) or an inclusive range of prefixes (e.g., `[88000, 88999]`). The card component always accepts custom brands, even if `acceptedBrands` is set to restrict standard networks.

#### Swift

## Customization

Internally, the `PaymentCardInput` view uses SwiftUI `TextField`. These can be customized using SwiftUI modifiers like any other `TextField` in your application:

```swift
PaymentCardInput(cardData: $cardData)
    .font(.footnote)
    .foregroundColor(.blue)
```

### Built-in styles

To provide more customization options, the `PaymentCardInput` can be styled using a `PaymentCardInputStyle`. There are two built-in styles:

#### Inline

![Inline card input]()

The inline style renders the credit card number, expiry and cvc fields all on a single row.

```swift
PaymentCardInput(cardData: $cardData)
  .paymentCardInputStyle(.inline)
```

#### Rows

![Rows card input]()

The rows style renders the credit card number on a single line with the expiry and cvc fields next to each other below.

```swift
PaymentCardInput(cardData: $cardData)
  .paymentCardInputStyle(.rows)
```

### Custom styles

If these two styles do not match your use case, you can create your own style:

```swift
struct CustomPaymentCardInputStyle: PaymentCardInputStyle {
    func makeBody(configuration: Configuration) -> some View {
        VStack(alignment: .center) {
            configuration.cardImage

            Text("CC Number").font(.title3)
            configuration.cardNumberField

            Divider()

            Text("Expiry").font(.title3)
            configuration.expiryField

            Divider()

            Text("CVC").font(.title3)
            configuration.cvcField
        }
    }
}
```

#### Android

## Customization

The `PaymentCard` and its components can be customized to fit your application's design. The view accepts a number of parameters that enable you to customize the modifier, text, and placeholder styles. The content parameter accepts a `@Composable PaymentCardInputScope.()` function, which can be used to customize the view's layout. The `PaymentCardInputScope` components can be customized with a modifier (Modifier), label (String or `@Composable`), placeholder (String or `@Composable`), text style (TextStyle), and input field colors (TextFieldColors).

### Prebuilt themes

The SDK has two prebuilt styles to get you started.

#### Inline

![Inline card input]()

The inline style renders the credit card number, expiry, and cvc fields on a single row.

```kotlin
@Composable
fun InlinePaymentCard(
    modifier: Modifier = Modifier,
    textStyle: TextStyle = TextStyle.Default,
    placeholderTexts: PlaceholderTexts = PlaceholderDefaults.texts(),
    placeholderTextStyle: TextStyle = textStyle.copy(color = MaterialTheme.colorScheme.secondary),
    onDataChange: (PaymentCardData) -> Unit = {}
)
```

#### Rows

![Rows card input]()

The rows style renders the credit card number on a single line with the expiry and cvc fields next to each other below.

```kotlin
@Composable
fun RowsPaymentCard(
    modifier: Modifier = Modifier,
    textStyle: TextStyle = TextStyle.Default,
    placeholderTexts: PlaceholderTexts = PlaceholderDefaults.texts(),
    placeholderTextStyle: TextStyle = textStyle.copy(color = MaterialTheme.colorScheme.secondary),
    onDataChange: (PaymentCardData) -> Unit = {}
)
```

### Custom styles

If these two layouts do not fit your application's design, you can create your own layout by passing a `@Composable` function to the content parameter. The `@Composable` function receives a `PaymentCardInputScope` (together with the `PaymentCard` Modifier) object, which contains the `CardImage`, `CardNumberField`, `ExpiryField` and `CVCField` fields. You can use these fields to create your own layout.

```kotlin
UserParentLayout {
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    // ...
    PaymentCard(onDataChange = onDataChange) { modifier ->
        Column(
            modifier = modifier
                .border(BorderStroke(1.dp, Color.LightGray), RoundedCornerShape(8.dp))
                .padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            CardImage()

            CardNumberField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.CreditCardText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.CreditCardText,
                        color = Color(0x75757575),
                        fontSize = 12.sp
                    )
                },
                textStyle = MaterialTheme.typography.titleLarge,
                textFieldColors = customTextFieldColors()
            )

            ExpiryField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.ExpirationDateText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.ExpirationDateText,
                        color = Color(0x9E9E9E9E),
                        fontSize = 10.sp
                    )
                },
                textStyle = MaterialTheme.typography.titleMedium,
                textFieldColors = customTextFieldColors()
            )

            CVCField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.CvcText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.CvcText,
                        color = Color(0xBDBDBDBD),
                        fontSize = 8.sp
                    )
                },
                textStyle = MaterialTheme.typography.bodyMedium,
                textFieldColors = customTextFieldColors()
            )
        }
    }
}

@Composable
private fun customTextFieldColors(): TextFieldColors = TextFieldDefaults.colors(
    focusedIndicatorColor = Color.Transparent,
    unfocusedIndicatorColor = Color.Transparent,
    disabledIndicatorColor = Color.Transparent,
    focusedContainerColor = Color.Transparent,
    unfocusedContainerColor = Color.Transparent,
    disabledContainerColor = Color.Transparent,
)
```

- [3D Secure](/cards/3d-secure): Learn how to use 3D Secure to authenticate your customers and reduce fraud.
- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to protect your customers' cards and improve authorization rates.

## 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.


---

# 3D Secure

_3D Secure is an online payment security protocol designed to reduce fraud and provide an additional layer of authentication for online transactions._

![An illustration of a 3D Secure authentication process]()

3D Secure is an online payment security protocol designed to reduce fraud and provide an additional layer of authentication for online transactions. When a customer makes an online purchase, 3D Secure requires them to complete an additional verification step with the card issuer, typically through a password, biometric authentication, or a one-time passcode sent over SMS.

## The benefits of 3D Secure

Implementing 3D Secure for online payments provides several benefits for both merchants and customers, enhancing overall transaction security and achieving regulatory compliance.

- **Reduced fraud**: By requiring an additional authentication step, 3D Secure significantly decreases the risk of unauthorized transactions. This added security measure helps to ensure that the person using the card online is the legitimate cardholder.
- **Liability shift**: One of the key advantages for merchants using 3D Secure is the liability shift. If a transaction is authenticated using 3D Secure and later turns out to be fraudulent, the liability for the chargeback shifts from the merchant to the card issuer. This can result in substantial cost savings and reduced chargeback rates for merchants.
- **Regulatory compliance**: With the increasing emphasis on online transaction security and regulations such as PSD2/SCA in Europe, implementing 3D Secure helps merchants comply with these regulations and avoid potential fines and penalties.

## How 3D Secure works

3D Secure consists of several steps involving merchants, card networks, and card issuers to allow customers to be authenticated during online purchases. At a high level, a standard challenge flow looks like this.

![A visual flow diagram depicting the 3D Secure payment process in three steps, Payment initialized, Issuer Challenge and Process Payment.]()

1. **Payment initiation**: When a customer initiates an online purchase and enters their card details on the merchant's website, the merchant recognizes that the card is enrolled in 3D Secure and triggers the authentication process.
2. **Issuer challenge**: The customer is redirected to a web page hosted by their card issuer where the customer is asked to authenticate themselves. This can be done through various methods, such as entering a static password, a one-time password (OTP) sent over SMS, or using biometric authentication (e.g., fingerprint or facial recognition).
3. **Process payment**: If the authentication is successful, the merchant processes the authenticated transaction and the customer is redirected back to the merchant's website with a confirmation of their purchase. If the authentication fails or isn't completed, the transaction is typically declined, and the customer is informed of the failure.

3DS supports frictionless authentications as well, which require no interaction from the customer. A frictionless flow is initiated when the issuer determines that a transaction is low-risk, eliminating the need for additional verification steps. Frictionless authentications aren't always possible, but they provide a much smoother customer experience because there's no challenge displayed to the customer, meaning there's no action for them to take.

### 3DS with Evervault

Although the 3DS protocol is known for being difficult to work with, we built our solution from scratch (and we run our own 3DS server). We did this to make our API straightforward to use. We don't wrap other solutions, and our API isn't just a one-to-one mapping of the 3DS protocol. We manage a lot of the complexity for you, and surface just the parts you need to configure and control 3DS the way you want to. Completing a 3DS authentication with Evervault takes three steps:

1. Create the session
2. Run the session on your frontend
3. Retrieve and forward authentication credentials as needed

That last step is an important differentiator. Because our solution is standalone, you can use 3DS authentications with any downstream partner. This is especially important for integrating with multiple payment service providers (PSPs). You could integrate with each PSP and use their 3DS solutions, but there are some issues with that. You're limited on the configuration side to whatever the PSPs allow, and it makes for an inconsistent customer experience because each 3DS implementation is different. Evervault lets you configure your own 3DS flows, and then share the results with any PSP, and customers always see the same interface.

## Get started with 3D Secure

To start, you need to create a [Sandbox app](/developers/sandbox). Sandbox apps allow you to test 3D Secure without affecting live data. When you're ready to go live, [contact our support team](mailto:support@evervault.com) to enable 3D Secure on your production app.

> **Configuring acquirers**
>
> Acquirer details aren't required when testing in [Sandbox](/developers/sandbox) mode. However, you must [configure acquirer details](#configuring-acquirer-details) before moving to production.

### 1. Create a 3DS session

Use the [create session](/api#createThreeDSSession) endpoint by providing the card (in encrypted form using our [card collection](/cards/card-collection), as a network token, or in plaintext), merchant, and payment details. Do this from your backend and then pass the session ID to your client code.

#### Node

```javascript
const response = await fetch("https://api.evervault.com/payments/3ds-sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic <credentials>"
  },
  body: {
    card: {
      number: "4242424242424242",
      expiry: {
        month: "05",
        year: "25"
      }
    },
    merchant: {
      name: "Ollivanders Wand Shop",
      website: "https://www.ollivanders.co.uk",
      categoryCode: "5945",
      country: "ie"
    },
    payment: {
      type: "one-off",
      amount: 1000,
      currency: "eur"
    }
  }
})

const session = await response.json();

[ANNOTATION lines=9-9]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

```

#### Ruby

```ruby
response = HTTParty.post(
  "https://api.evervault.com/payments/3ds-sessions",
  headers: {
    "Content-Type" => "application/json",
    "Authorization" => "Basic <credentials>"
  },
  body: {
    card: {
      number: "4242424242424242",
      expiry: {
        month: "05",
        year: "25"
      }
    },
    merchant: {
      name: "Ollivanders Wand Shop",
      website: "https://www.ollivanders.co.uk",
      categoryCode: "5945",
      country: "ie"
    },
    payment: {
      type: "one-off",
      amount: 1000,
      currency: "eur"
    }
  }.to_json
)

session = JSON.parse(response.body)

[ANNOTATION lines=9-9]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

```

#### Python

```python
import requests
import json

response = requests.post(
  "https://api.evervault.com/payments/3ds-sessions",
  headers={
    "Content-Type": "application/json",
    "Authorization": "Basic <credentials>"
  },
  json={
    "card": {
      "number": "4242424242424242",
      "expiry": {
        "month": "05",
        "year": "25"
      }
    },
    "merchant": {
      "name": "Ollivanders Wand Shop",
      "website": "https://www.ollivanders.co.uk",
      "categoryCode": "5945",
      "country": "ie"
    },
    "payment": {
      "type": "one-off",
      "amount": 1000,
      "currency": "eur"
    }
  }
)

session = response.json()

[ANNOTATION lines=12-12]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

```

#### PHP

```php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.evervault.com/payments/3ds-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Basic {credentials}"
  ],
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "card" => [
      "number" => "4242424242424242",
      "expiry" => [
        "month" => "05",
        "year" => "25"
      ]
    ],
    "merchant" => [
      "name" => "Ollivanders Wand Shop",
      "website" => "https://www.ollivanders.co.uk",
      "categoryCode" => "5945",
      "country" => "ie"
    ],
    "payment" => [
      "type" => "one-off",
      "amount" => 1000,
      "currency" => "eur"
    ]
  ])
]);

$response = curl_exec($curl);
$session = json_decode($response, true);

curl_close($curl);

[ANNOTATION lines=13-13]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

```

#### Java

```java
URL url = new URL("https://api.evervault.com/payments/3ds-sessions");

HttpURLConnection conn = (HttpURLConnection) url.openConnection();

conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Authorization", "Basic <credentials>");
conn.setDoOutput(true);

String jsonInputString = "{"
    + "\"card\": {"
    + "    \"number\": \"4242424242424242\","
    + "    \"expiry\": {"
    + "        \"month\": \"05\","
    + "        \"year\": \"25\""
    + "    }"
    + "},"
    + "\"merchant\": {"
    + "    \"name\": \"Ollivanders Wand Shop\","
    + "    \"website\": \"https://www.ollivanders.co.uk\","
    + "    \"categoryCode\": \"5945\","
    + "    \"country\": \"ie\""
    + "},"
    + "\"payment\": {"
    + "    \"type\": \"one-off\","
    + "    \"amount\": 1000,"
    + "    \"currency\": \"eur\""
    + "}"
+ "}";

try(OutputStream os = conn.getOutputStream()) {
    byte[] input = jsonInputString.getBytes("utf-8");
    os.write(input, 0, input.length);
}

try(BufferedReader br = new BufferedReader(
    new InputStreamReader(conn.getInputStream(), "utf-8"))) {
    StringBuilder response = new StringBuilder();
    String responseLine = null;
    while ((responseLine = br.readLine()) != null) {
        response.append(responseLine.trim());
    }
    JSONObject session = new JSONObject(response.toString());
}

[ANNOTATION lines=12-12]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

```

#### Go

```go
client := &http.Client{}
jsonData := map[string]interface{}{
    "card": map[string]interface{}{
        "number": "4242424242424242",
        "expiry": map[string]interface{}{
            "month": "05",
            "year": "25",
        },
    },
    "merchant": map[string]interface{}{
        "name": "Ollivanders Wand Shop",
        "website": "https://www.ollivanders.co.uk",
        "categoryCode": "5945",
        "country": "ie",
    },
    "payment": map[string]interface{}{
        "type": "one-off",
        "amount": 1000,
        "currency": "eur",
    },
}

jsonValue, _ := json.Marshal(jsonData)
req, _ := http.NewRequest("POST", "https://api.evervault.com/payments/3ds-sessions", bytes.NewBuffer(jsonValue))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Basic <credentials>")

resp, _ := client.Do(req)
defer resp.Body.Close()

body, _ := ioutil.ReadAll(resp.Body)
var session map[string]interface{}
json.Unmarshal(body, &session)

[ANNOTATION lines=4-4]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### 3DS Requestor Initiated (3RI) transactions

Merchant-initiated transactions (MIT) are commonly used to charge customers for subscriptions, installment payments, etc. 3RIs are a form of MIT that include a 3DS authentication without the cardholder being present (flows are frictionless and either succeed or fail, there's no challenge involved). These 3RIs are often used instead of standard MITs because they can improve acceptance rates and may still result in liability shift (moving chargeback liability from you to the issuer).

To use 3RIs, you still complete initial 3DS sessions with customers. You keep track of the session ID, and then you use it later to create a 3RI which carries over the authentication. To create a 3RI transaction, set the:

- [Initiator type](/api#createThreeDSSession-request-initiator) to `merchant`
- [initialSession](/api#createThreeDSSession-request-initiator-initialsession) to the [ID returned from the original session](/api#createThreeDSSession-response-initiator-initialsession) or a `threeDSServerTransactionID`
- [Payment type](/api#createThreeDSSession-request-payment) to `recurring` or `installment`

#### Visa Data Only authentication

Visa's Digital Commerce Authentication Program (DCAP) lowers interchange fees on transactions authenticated through Visa's Data Only flow. Rather than challenging the cardholder, Data Only sends enriched transaction data to Visa for risk assessment. The customer sees no challenge, and you pay a lower interchange rate.

Like 3RIs, a Data Only session authenticates as soon as it's created, so you don't mount the SDK on your frontend. Collect the extra data points along with the usual 3DS data, and Evervault authenticates the session when you create it.

To create a Data Only session for a Visa card, set the [challenge preference](/api#createThreeDSSession-request-challenge) to `no-challenge-requested` and the [reason](/api#createThreeDSSession-request-challenge-reason) to `data-sharing`, and supply all of the following:

- The customer's full [billing address](/api#createThreeDSSession-request-customer-billing), including `state`
- The customer's [phone](/api#createThreeDSSession-request-customer-phone) and [email](/api#createThreeDSSession-request-customer-email)
- A [deviceId](/api#createThreeDSSession-request-deviceid) you generate for the customer's device
- The customer's [clientIp](/api#createThreeDSSession-request-clientip)

> **State is required**
>
> `state` is optional on most 3DS sessions, but a Data Only session won't qualify without it. Supply it even for countries where you'd usually leave it out.

Evervault reports the outcome on the `dcap` object, which is present on every Visa session created with a `data-sharing` reason.

**The dcap object**

- `qualified` `boolean` — Whether you supplied every data point the program requires, so the transaction was submitted to Visa for DCAP.
- `accepted` `boolean` — Whether Visa reported your data as meeting the program's quality requirements. A session can be `qualified` but not `accepted` — for example, when the billing address and IP address resolve to different places.

[Retrieve and forward the authentication credentials](#3-retrieve-and-forward-authentication-credentials) after creating the session, as you would for any other session. Evervault also recommends combining Data Only with [network tokens](/cards/network-tokens), which reduce interchange further.

### 2. Run the session on your frontend

After creating the session, use our client-side SDKs to complete the authentication flow on your frontend. If for some reason you can't use our SDKs, you can try [using a redirect](#using-a-page-redirect) but Evervault doesn't generally recommend this (redirects add friction to the customer experience).

#### Browser

#### Install the SDK

Our [JavaScript SDK](/sdks/javascript) is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the [Evervault Dashboard](https://app.evervault.com).

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

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

#### Frequently Asked Questions

##### Why does the SDK need to be loaded from the CDN?

The SDK must be loaded directly from our CDN in order to be PCI Compliant.

##### How do I get my Team ID and App ID?

You can find your Team ID and App ID in the [Evervault Dashboard](https://app.evervault.com).

##### Can I load the SDK asynchronously?

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <script src="https://js.evervault.com/v2" onload="onEvervaultReady()" async></script>
        <script>
          function onEvervaultReady() {
            const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
          }
        </script>
      </head>
    </html>
    ```

#### Start the authentication

The `ThreeDSecure` component can be initiated using the `evervault.ui.threeDSecure` method by passing the session ID obtained in the previous step. After you initialize the `ThreeDSecure` component, call the `.mount()` method to open the 3DS modal in the customer's browser to start the authentication process. The `success` event will be fired after the authentication process completes. The `failure` event will be fired if the authentication process fails (e.g., the customer failed to authenticate). These callbacks occur regardless of whether there was a challenge or if the flow was frictionless.

```javascript
const evervault = new Evervault("{{TEAM_ID}}", "{{APP_ID}}");
const threeDSecure = evervault.ui.threeDSecure("tds_visa_5a9a7b0a574c");

threeDSecure.on("success", () => {
  // 3DS is complete and payment can be finalized
});

threeDSecure.on("failure", () => {
  // 3DS failed. Try again.
});

threeDSecure.mount();
```

Learn more about the [JavaScript SDK](/sdks/javascript).

#### React

#### Install the SDK

Our React SDK is distributed via npm and can be installed using your preferred package manager.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

#### Start the authentication

The `useThreeDSecure` hook returns a `ThreeDSecure` object you can use to run the authentication. After you initialize the hook, call the start method with the session ID from the previous step to start the authentication process. The `onSuccess` callback will be fired after the authentication process completes. The `onFailure` callback will be fired if the authentication process fails (e.g., the customer failed to authenticate). These callbacks occur regardless of whether there was a challenge or if the flow was frictionless.

```jsx filename='app.jsx'
import { Card, useThreeDSecure } from "@evervault/react";
import { createThreeDSSession, finalizePayment } from "./api";

function Checkout() {
  const threeDSecure = useThreeDSecure();
  const handlePay = async () => {
    const sessionId = await createThreeDSSession();
    threeDSecure.start(sessionId, {
      onSuccess: () => {
        // 3DS is complete and payment can be finalized
      },
      onFailure: () => {
        // 3DS failed.
      },
    });
  };
  return (
    <>
      <Card />
      <button onClick={handlePay}>Pay</button>
    </>
  );
}
```

Learn more about the [React SDK](/sdks/react).

#### React Native

#### Install the SDK

Our React Native SDK is distributed via `npm` and can be installed using your preferred package manager. The [react-native-webview](https://www.npmjs.com/package/react-native-webview) package is a peer dependency and will need to be installed as well.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react-native";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

#### Start the authentication

The `useThreeDSecure` hook returns a `ThreeDSecure` object you can use to run the authentication. After you initialize the hook, call the start method with the session ID from the previous step to start the authentication process. The `onSuccess` callback will be fired after the authentication process completes. The `onFailure` callback will be fired if the authentication process fails (e.g., the customer failed to authenticate). These callbacks occur regardless of whether there was a challenge or if the flow was frictionless.

```jsx
import { ThreeDSecure, useThreeDSecure } from "@evervault/react-native";
import { createThreeDSSession } from "@your/api";
import { Button, Form, Modal } from "@your/ui";

function CustomCheckout() {
  const tds = useThreeDSecure();

  async function handlePayment() {
    // Create a 3DS session on your backend
    const sessionId = await create3DSecureSession();

    tds.start(sessionId, {
      onSuccess: () => {
        console.log("3DS successful");
      },
      onFailure: (error: Error) => {
        console.error("3DS failed", error);
      },
    });
  }

  return (
    <Form>
      <Button onPress={handlePayment}>Pay</Button>

      <ThreeDSecure state={tds}>
        <Modal onRequestClose={tds.cancel}>
          <ThreeDSecure.Frame />
        </Modal>
      </ThreeDSecure>
    </Form>
  );
}
```

Learn more about the [React Native SDK](/sdks/react-native).

#### Frequently Asked Questions

##### Can I customize the styling for the challenge?

The contents of the modal are controlled by the bank and can't be
    customized.

### 3. Retrieve and forward authentication credentials

After completing the authentication, you can [retrieve](/api#retrieveThreeDSSession) information about the session as needed. To process the transaction and ensure liability is shifted, pass the raw Electronic Commerce Indicator (ECI) and 3DS cryptogram to your payment gateway or PSP.

#### Node

```javascript
const response = await fetch(
  "https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c",
  {
    headers: {
      Authorization: "Basic <credentials>",
    },
  }
);

const session = await response.json();

console.log(session.cryptogram);
// MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

console.log(session.eci);
// { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

#### Ruby

```ruby
response = HTTParty.get('https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c', {
  headers: {
    'Authorization': 'Basic <credentials>'
  }
})

session = JSON.parse(response.body)

puts session.cryptogram
# MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

puts session.eci
# { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

#### Python

```python
import requests

response = requests.get('https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c', headers={'Authorization': 'Basic <credentials>'})

session = response.json()

print(session.cryptogram)
# MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

print(session.eci)
# { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

#### PHP

```php
$response = Http::get('https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c', [
  'headers' => [
    'Authorization' => 'Basic <credentials>'
  ]
]);

$session = json_decode($response->body());

print($session->cryptogram);
# MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

print($session->eci);
# { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

#### Java

```java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(new URI("https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c"))
    .header("Authorization", "Basic <credentials>")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

var session = JsonConvert.DeserializeObject<Dictionary<string, object>>(response.Body);

System.Console.WriteLine(session.cryptogram);
// MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

System.Console.WriteLine(session.eci);
// { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

#### Go

```go
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.evervault.com/payments/3ds-sessions/tds_visa_5a9a7b0a574c", nil)
req.Header.Set("Authorization", "Basic <credentials>")

resp, _ := client.Do(req)
defer resp.Body.Close()

body, _ := ioutil.ReadAll(resp.Body)
var session map[string]interface{}
json.Unmarshal(body, &session)

fmt.Println(session.cryptogram)
// MTIzNDU2Nzg5MDA5ODc2NTQzMjE=

fmt.Println(session.eci)
// { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }
```

In some cases, downstream partners might also require one or more of these IDs:

- [threeDSServer.transactionIdentifier](/api#retrieveThreeDSSession-response-threedsserver-transactionidentifier)
- [directoryServer.transactionIdentifier](/api#retrieveThreeDSSession-response-directoryserver-transactionidentifier)
- [accessControlServer.transactionIdentifier](/api#retrieveThreeDSSession-response-accesscontrolserver-transactionidentifier)

These values are specific to the 3DS protocol, and not Evervault. They're sometimes requested in addition to the ECI and cryptogram, but not every provider requires them.

## Configuring acquirer details

Acquirer details aren't required in [Sandbox](/developers/sandbox) mode but you do need them to use 3DS in production. Evervault automatically passes this information in when 3DS sessions are created, although you can [pass values in manually](#provide-acquirer-details-per-request) yourself.

You can configure acquirers in the [dashboard](https://app.evervault.com/app/payments/acquirers) or with the [API](/api#createAcquirer), and you can set up default acquirers for each card network (Visa, Mastercard, etc.). When creating a 3DS session, Evervault uses the appropriate acquirer configuration based on the card network. Configurations are specific to each app, so you need to configure these for your staging and production apps separately.

### Acquirer info request template

If you need to obtain acquirer information from one of your partners (e.g., PSPs), you can use the template message below to request it. It covers everything you need to configure acquirers within Evervault.

```md
Hi,

We're currently integrating Evervault as our 3D-Secure (3DS) Server provider and need to collect some information related to our merchant account to unblock our integration.
Could you please provide the following details for each network we're set up with? There should be different acquirer BIN values for each of Visa, Mastercard, Discover, and American Express.

- Merchant ID (MID): Our merchant account number/merchant ID.
- Acquirer BIN: The numeric identifier you've received from each card network to represent the underlying acquiring bank. These should be 6-10 digits in length.
- Merchant Name: The official name you have on file for us.
- Merchant Category Code (MCC): Our four-digit business classification assigned by the card networks.

Thank you!
```

### Provide acquirer details per request

Alternatively, you can provide acquirer details when creating each 3DS session by including the [acquirer object](/api#createThreeDSSession-request-acquirer) in your API request. This approach is useful if you work with multiple acquirers or need to specify different acquirer details for different transactions. However, supplying acquirer details per request adds complexity to your integration. You'll likely need to perform a BIN lookup to identify the card network, so that you can then decide which acquirer BIN or MID values to provide for each transaction.

### How Evervault resolves acquirer details

When you create a 3DS session, Evervault follows this process to determine which acquirer configuration to use:

1. If your request includes an `acquirer` object, those details are used.
2. If your request includes an ID of an acquirer configuration in the `acquirer` field, that configuration is used.
3. If no acquirer details are provided in the request, Evervault uses the default acquirer configuration for the card's network, if available.
4. If no acquirer details can be resolved, session creation fails.

## Testing your implementation

Provided you are using a Sandbox app, you can use specific test cards to simulate various real-life scenarios. These cards can be used in conjunction with any valid expiry date or CVC.

| Number | Brand |
| --- | --- |
| **3D Secure challenge flow** | |
| 4242 4242 4242 4242 | Visa |
| 5555 5555 5555 4444 | Mastercard |
| 3714 4963 5398 431 | American Express |
| 6011 1111 1111 1117 | Discover |
| 3622 720627 1667 | Diners Club |
| **Successful frictionless flow** | |
| 4111 1101 1663 8870 | Visa |
| 5555 5501 3065 9057 | Mastercard |
| 3782 8224 6310 005 | American Express |
| 6011 0009 3838 5477 | Discover |
| 3622 720638 3827 | Diners Club |
| **Failed frictionless flow** | |
| 4111 1117 3897 3695 | Visa |
| 5555 5504 8784 7545 | Mastercard |
| 3782 8224 6310 013 | American Express |
| 6011 0009 3838 3100 | Discover |
| 3622 720638 3835 | Diners Club |
| **Attempted authentication** | |
| 4111 1101 4848 6405 | Visa |
| 5555 5588 2481 5604 | Mastercard |
| 3782 8224 6310 021 | American Express |
| 6011 0009 3838 7572 | Discover |
| 3622 720638 3850 | Diners Club |
| **Card not enrolled** | |
| 4111 1101 4848 6413 | Visa |
| 5555 5588 2481 5612 | Mastercard |
| 3782 8224 6310 047 | American Express |
| 6011 0009 3838 6491 | Discover |
| 3622 720638 3868 | Diners Club |

## Alternative configurations

These alternative configurations mostly relate to using redirects and the `failOnChallenge` flag. Both have somewhat niche use cases but can be useful in the right situations.

### Using failOnChallenge

3DS supports frictionless and challenge flows. Frictionless authentication requires no interaction from the customer (and maintains liability shift). The frictionless flow automatically occurs when the issuer determines that a transaction is low-risk, eliminating the need for additional verification steps. This is a much smoother customer experience.

In challenge flows, customers are required to complete an authentication step to verify their identity. This is higher friction and usually requires a password, biometric authentication, etc.

The issuer decides on the flow, but Evervault provides an additional flag that can reduce friction when a challenge is requested. When you create 3DS sessions, you can set `failOnChallenge` to `true`. If a challenge is requested, Evervault automatically fails the 3DS session which prevents the challenge from ever being shown to the customer. This isn't technically a frictionless flow in terms of 3DS, but it does allow you to skip the challenge.

#### Browser

```javascript
const tds = evervault.ui.threeDSecure("tds_visa_5a9a7b0a574c", {
  failOnChallenge: true,
});
```

#### React

```jsx
const threeDSecure = useThreeDSecure({
  failOnChallenge: true,
});
```

> **EU transactions**
>
> The challenge flow is required for EU transactions and as a result
>   frictionless-only 3D Secure isn't supported by banks in the EU.

### Using a page redirect

The 3D Secure challenge can also be loaded directly—either through a full page redirect or served within an `<iframe>` or mobile web view. In this scenario, fingerprinting and challenge windows are presented directly in the user's browser. Once the 3D Secure authentication has been finalized (with either a success, a failure, or an error) the page is redirected back to a callback URL of your choice.

```text
https://3ds.evervault.com/?team=<TEAM>&app=<APP>&session=session&redirect=redirect
```

Once the 3D Secure session has been finalized, the page will redirect back to the URL provided in the redirect parameter with `status` and `session` appended to the URL parameters. More details about the 3D Secure Session can be retrieved from our API.

**URL Parameters**

- `team` — The Team ID found in the [Evervault Dashboard](https://app.evervault.com).
- `app` — The App ID found in the [Evervault Dashboard](https://app.evervault.com).
- `session` — The 3D Secure session ID.
- `redirect` — The URL to redirect to once the 3D Secure session has been completed. Additional URL parameters will be appended to this URL. Deep links are also supported for mobile implementations. For example, if you provided 'https://3ds-redirect.testmerchant.com' as the redirect, the user's browser would redirect to 'https://3ds-redirect.testmerchant.com/?status=success&session=tds_abc123'. Status can be `success`, `failure`, or `error`

### 3DS on mobile apps

Since the `ThreeDSecure` components in our React and JavaScript SDKs are built for the web, native mobile apps can instead complete 3DS by loading the challenge directly in a mobile webview. The hosted challenge page handles fingerprinting and the challenge window, and then redirects back to your app through a deep link after authentication is finalized.

#### 1. Create the session and register a deep link

Create a [3DS session](/api#createThreeDSSession) on your backend, and pass the session ID to your app. In your app, register a custom URL scheme or universal link (e.g., `yourapp://3ds-complete`) to receive the result.

#### 2. Load the hosted challenge in an in-app webview

Open the hosted 3DS page in a webview, such as `SFSafariViewController` or `WKWebView` on iOS, and Chrome Custom Tabs or `WebView` on Android. Pass your deep link as the `redirect` parameter.

```text
https://3ds.evervault.com/?team=<TEAM_ID>&app=<APP_ID>&session=<SESSION_ID>&redirect=yourapp://3ds-complete
```

#### 3. Handle the redirect and retrieve the 3DS credentials

When the session is finalized, the page redirects to your deep link with `status` and `session` appended (e.g., `yourapp://3ds-complete?status=success&session=tds_abc123`). Status can be `success`, `failure`, or `error`. Intercept the deep link, close the webview, and [retrieve the session](/api#retrieveThreeDSSession) using the session ID. After a successful authentication is confirmed, you can forward the ECI and cryptogram to your PSP from your backend to finalize the payment.
> **Verify server-side**
>
> Don't rely on the `status` parameter in the redirect to determine the final outcome of the 3DS session. Instead, [retrieve the session](/api#retrieveThreeDSSession) from your backend and verify the `status` and `eci` from the response to confirm the final result. If successful, you can then forward the cryptogram and ECI to your PSP.

- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.
- [Card Account Updater](/cards/card-account-updater): Learn how to use Card Account Updater to automatically update card details.


---

# Network Tokens

_Create and use network tokens with Evervault to replace PANs with secure, updatable tokens that improve auth rates and reduce fraud._

![An illustration of a credit card being converted into a Network Token]()

Network tokens replace sensitive card details (like the 16-digit card number, expiration date, and security code) with a unique identifier generated by a card network (e.g. Visa or Mastercard). This token is used to process payments without exposing actual card details, thus adding a layer of security. For merchants, this can also result in higher authorization rates and lower authorization fees.

They’re designed to look exactly like a real card number, complete with a similar length and an expiry date, making them compatible with existing payment infrastructure. Since Network Tokens are simple identifiers and not real card numbers, merchants can store them without expanding their compliance obligations, such as those required by PCI standards.

Unlike traditional card details, network tokens are directly linked to specific merchants. When a merchant creates a network token with the card network, it can only be used for transactions by that merchant alone. This restriction introduces an additional security measure: should a token be compromised, it can be deactivated without requiring a new card to be issued or impacting tokens linked to that card across different merchants. This also leads to a significant reduction in fraud risk, as stolen network tokens can't be used with any other merchant.

## How network tokens work

- **Tokenization process**: The tokenization journey commences as the merchant gathers the customer's card information on the checkout page. Once the card details are captured, the merchant creates a network token by submitting the card details to the relevant card network, such as Visa or Mastercard. The card network first authorizes the tokenization request with the issuer of the card. This authorization step ensures that the token is linked accurately to the card with the issuer's approval. Once tokenization is authorized, the card network generates a unique token that is associated with the merchant. The generated network token is then returned to the Merchant and stored for future use. ![A flow diagram showing how a network token is created]()
- **Processing payments using network tokens**: During a transaction, a network token is sent to the payment gateway or card network instead of the original card details. Once a transaction reaches the network, the token is replaced by the original card details and then processed as usual by the card issuer. As a result, the card details are only handled by the card issuer and the card network, minimizing the number of points where this data is exposed. ![A flow diagram showing how a network token is processed]()

## The benefits of network tokens

Using network tokens to process payments offers a number of benefits compared to using raw card details.

- **Improved authorization rate**: Because tokens are issued and recognized by the card networks and are specific to the merchant or transaction type, they often carry additional data that can assist in the authorization process. This data helps issuers more accurately verify the legitimacy of a transaction. As a result, legitimate transactions are less likely to be declined due to suspicion of fraud, improving the overall experience for both customers and merchants. Merchants typically experience a 3% increase in authorization rates when utilizing network tokens instead of traditional card numbers.
- **Automated card updates**: Unlike traditional card numbers (which remain static until manually updated by the cardholder in the event of expiry or reissuance), network tokens are dynamically updated. Card networks ensure that tokens reflect the most up-to-date card information, including automatic updates for expiration dates or replacement card numbers. This automatic renewal feature removes the common friction point of transactions being declined due to outdated card details.
- **Reduced fraud risk**: Since tokens replace sensitive card information with a unique digital identifier associated with a single merchant, the actual card details are never exposed during the transaction process — minimizing exposure to potential fraud. If a token is compromised, it can be suspended or invalidated by the issuing network without affecting the underlying card or the cardholder's ability to make purchases through other channels.
- **Lower interchange fees**: One of the lesser-known yet financially impactful benefits of adopting network tokens in payment processing is the potential reduction in interchange fees. Interchange fees are the costs that merchants pay to card networks for the processing of credit and debit card transactions. Some card networks offer specific incentives and reduced interchange rates for transactions that utilize network tokens, as part of their push towards adopting more secure payment technologies.
- **Reduced PCI compliance scope**: By using tokens instead of storing, processing, or transmitting card numbers directly, merchants handle less sensitive data. This reduction in handling sensitive data can decrease the complexity and costs associated with maintaining PCI DSS compliance, as the stringent security requirements become applicable to a smaller portion of the merchant's payment ecosystem.
- **Simplified payment infrastructure**: Since the tokenization and de-tokenization processes are handled by the card networks (e.g., Visa or Mastercard), merchants can process payments across different payment gateways without depending on each gateway's proprietary tokenization system. Merchants therefore need only a single tokenization integration to work with various payment processors and gateways, significantly simplifying the payment infrastructure.

## Getting started

Evervault provides a set of easy-to-use APIs designed to let you create and use network tokens in minutes without having to integrate directly with the card networks.

The Evervault API enables you to tokenize cards with Visa or Mastercard.

> Support for additional card networks such as American Express are coming soon.
>   Please contact [support@evervault.com](mailto:support@evervault.com) if you
>   are interested in using network tokens with American Express.

### Create a merchant

Network tokens are unique to individual merchants, meaning a token can only be utilized by the merchant for whom it was issued. You can create a merchant from the payments section in the [Evervault Dashboard](https://app.evervault.com) or via the [Merchants API](/api#createMerchant). When you create a Merchant, we will automatically initiate the enrollment process with each [supported card network](#card-schemes-support).

> It can take up to 48 hours to enroll a merchant with each of the card
>   networks. If you are still unable to provision network tokens after this
>   period, please contact [support@evervault.com](mailto:support@evervault.com)

### Create a network token

After successfully enrolling the merchant, you can create network tokens via the [Network Token API](/api#createNetworkToken), making sure to include the merchant ID.

#### Node

```javascript
fetch("https://api.evervault.com/payments/network-tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    card: {
      number: "4242424242424242",
      expiry: {
        month: "09",
        year: "29",
      },
      cvc: "123",
    },
    merchant: "merchant_ddsaJsda9d86",
  }),
});

[ANNOTATION lines=9-9]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=14-14]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### Ruby

```ruby
require 'httparty'

response = HTTParty.post(
  'https://api.evervault.com/payments/network-tokens',
  headers: {
    'Content-Type' => 'application/json',
    'Authorization' => "Basic #{Base64.strict_encode64('<app_id>:<api_key>')}"
  },
  body: {
    card: {
      number: '4242424242424242',
      expiry: {
        month: '09',
        year: '29'
      },
      cvc: '123'
    },
    merchant: 'merchant_ddsaJsda9d86'
  }.to_json
)

[ANNOTATION lines=11-11]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=16-16]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### Python

```python
import requests

response = requests.post(
  'https://api.evervault.com/payments/network-tokens',
  headers={
    'Content-Type': 'application/json',
    'Authorization': "Basic #{Base64.strict_encode64('<app_id>:<api_key>')}"
  },
  json={
    'card': {
      'number': '4242424242424242',
      'expiry': {
        'month': '09',
        'year': '29'
      },
      'cvc': '123'
    },
    'merchant': 'merchant_ddsaJsda9d86'
  }
)

[ANNOTATION lines=11-11]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=16-16]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### PHP

```php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.evervault.com/payments/network-tokens',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: Basic ' . base64_encode('<app_id>:<api_key>')
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'card' => [
      'number' => '4242424242424242',
      'expiry' => [
        'month' => '09',
        'year' => '29'
      ],
      'cvc' => '123'
    ],
    'merchant' => 'merchant_ddsaJsda9d86'
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

[ANNOTATION lines=13-13]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=18-18]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### Java

```java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpStatus;
import java.net.http.HttpHeaders;

String json = "{"
    + "\"card\": {"
        + "\"number\": \"4242424242424242\","
        + "\"expiry\": {"
            + "\"month\": \"09\","
            + "\"year\": \"29\""
        + "},"
        + "\"cvc\": \"123\""
    + "},"
    + "\"merchant\": \"merchant_ddsaJsda9d86\""
+ "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.evervault.com/payments/network-tokens"))
  .header("Content-Type", "application/json")
  .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("<app_id>:<api_key>".getBytes()))
  .POST(HttpRequest.BodyPublishers.ofString(json))
  .build();

[ANNOTATION lines=9-9]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=14-14]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

#### Go

```go
package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	json := `{
		"card": {
			"number": "4242424242424242",
			"expiry": {
				"month": "09",
				"year": "29"
			},
			"cvc": "123"
		},
		"merchant": "merchant_ddsaJsda9d86"
	}`

	req, err := http.NewRequest("POST", "https://api.evervault.com/payments/network-tokens", bytes.NewBuffer([]byte(json)))
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Basic " + base64.StdEncoding.EncodeToString([]byte("<app_id>:<api_key>")))

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
}

[ANNOTATION lines=16-16]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]

[ANNOTATION lines=21-21]
You can also provide an encrypted CVC to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

> This API endpoint is designed to accept both Evervault encrypted values and
>   plaintext values for the card number and the CVC. If card details have been
>   obtained through [Card Collection](/cards/card-collection) or
>   [Relay](/cards/card-collection#processing-encrypted-card-data), these values should be used as received.

Network tokens are issued synchronously. This ensures that the response to the creation request includes all details of the enrolled token, such as the token number and its expiration date. Since the card's issuer is involved in the token issuance process, requests may experience high latency and take several seconds to process. Upon successful tokenization, the network token becomes immediately available for use in processing transactions.

## Process payments with network tokens

Network tokens can be utilized as payment credentials to process charges across several payment gateways for Customer Initiated Transactions (CITs) and Merchant Initiated Transactions (MITs). To utilize network tokens during the payment flow, verify that your payment gateway is equipped with the necessary API support for network tokens, as they often feature dedicated APIs for processing network token transactions.

- **Merchant Initiated Transactions (MITs)**: To process a Merchant Initiated Transaction, the only requirement is the token number and expiry date, both of which can be found in the [Network Token object](/api#networkTokens).
- **Customer Initiated Transactions (CITs)**: Customer Initiated Transactions require the generation of a token cryptogram. This serves as a substitute for the traditional CVC code found on the back of a payment card. The token cryptogram is designed for in-memory use only and must be disposed of after each payment attempt, regardless of whether the attempt succeeds or fails. Token cryptograms can be generated using the [Network Token Cryptogram API](/api#createNetworkTokenCryptogram). #### Node ```javascript const response = await fetch("https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Basic " + btoa("<app_id>:<api_key>"), }, }); const { cryptogram } = await response.json(); console.log(cryptogram); // NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= ``` #### Ruby ```ruby require 'httparty' response = HTTParty.post( 'https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms', headers: { 'Content-Type' => 'application/json', 'Authorization' => "Basic #{Base64.strict_encode64('<app_id>:<api_key>')}" } ) cryptogram = response.parsed_response['cryptogram'] puts cryptogram # NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= ``` #### Python ```python import requests response = requests.post( "https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms", headers={ "Content-Type": "application/json", "Authorization": "Basic " + base64.b64encode("<app_id>:<api_key>").decode("utf-8") } ) cryptogram = response.json()["cryptogram"] print(cryptogram) # NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= ``` #### PHP ```php <?php $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "Authorization: Basic " . base64_encode("<app_id>:<api_key>") ] ]); $response = curl_exec($curl); $data = json_decode($response, true); $cryptogram = $data["cryptogram"]; echo $cryptogram; // NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= curl_close($curl); ``` #### Java ```java // Create HTTP client HttpClient client = HttpClient.newHttpClient(); // Create basic auth header String auth = Base64.getEncoder().encodeToString(("<app_id>:<api_key>").getBytes()); // Build the request HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms")) .POST(HttpRequest.BodyPublishers.noBody()) .header("Content-Type", "application/json") .header("Authorization", "Basic " + auth) .build(); // Send the request HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); // Parse JSON response ObjectMapper mapper = new ObjectMapper(); JsonNode jsonNode = mapper.readTree(response.body()); String cryptogram = jsonNode.get("cryptogram").asText(); System.out.println(cryptogram); // NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= ``` #### Go ```go // Create the request url := "https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms" req, err := http.NewRequest("POST", url, nil) if err != nil { panic(err) } // Set headers req.Header.Set("Content-Type", "application/json") // Create basic auth header (equivalent to btoa in JavaScript) auth := base64.StdEncoding.EncodeToString([]byte("<app_id>:<api_key>")) req.Header.Set("Authorization", "Basic "+auth) // Make the request client := &http.Client{} response, err := client.Do(req) if err != nil { panic(err) } defer response.Body.Close() // Read the response body body, err := io.ReadAll(response.Body) if err != nil { panic(err) } // Parse JSON response var result struct { Cryptogram string `json:"cryptogram"` } err = json.Unmarshal(body, &result) if err != nil { panic(err) } fmt.Println(result.Cryptogram) // NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE= ```

## Network token updates

You can set up the Network Tokens API to update you whenever there's a change to a card. These changes happen when a card is replaced due to loss, theft, expiration, or the renewal of the token itself. You can use these updates to ensure the underlying payment credentials you have on file are up to date.

![A flow diagram showing how a network token is updated]()

To receive network token updates, [create a webhook endpoint](/developers/webhooks) and listen for the `payments.network-token.updated` event. You can [simulate an update](/api#simulateNetworkTokenUpdate) in Sandbox mode to test the process. Depending on the change, the event can include updates to the `number`, `expiry`, `card`, and `status` fields.

> You need a webhook endpoint configured to receive network token updates. You can still create and use network tokens without using webhooks, but you won't receive any updates.

> Network tokens can also be used with [Card Insights](/cards/insights-and-verification). Provide
>   a `networkToken` in place of a `card` to run verification checks against the
>   token.

## Retrieve card art

You can [retrieve art](https://docs.evervault.com/api#getCardArt) for cards issued by Visa and Mastercard. This is a digital version of the art on the front of the card. It's often used during the checkout process to build trust with customers, or as a part of account management to create more personalized experiences for saved cards.

## Error handling

When an issue occurs during the tokenization process, the API generates an error message — each of which are tagged with a distinct code. This feature enables the design of customized error handling strategies, streamlining the resolution of these issues effectively.

**Error Codes**

- `payments/network-tokens/ineligible-card` — The card is not eligible for tokenization. This may be due to the card issuer not supporting tokenization.
- `payments/network-tokens/invalid-card` — The provided card details did not pass verification checks. This may be due to an invalid card number, an incorrect CVC, or a discrepancy between the provided and actual card expiry date. If network tokenization occurs while the cardholder is still present, an error message should be displayed. This ensures immediate feedback for correction or verification.
- `payments/network-tokens/expired-card` — The card has expired. If network tokenization occurs while the cardholder is still present, an error message should be displayed. This ensures immediate feedback for correction or verification.
- `payments/network-tokens/declined-tokenization` — Tokenization for the given card was declined by the card issuer. This may be due to restrictions related to the card type, issuer policies, or the card's current status.
- `payments/network-tokens/merchant-not-ready` — The merchant isn't ready to tokenize cards for this card brand. Enrolment with each card network can take up to 48 hours after the merchant is created. Retry tokenization later.
- `payments/network-tokens/inactive-token` — The network token is inactive, which can happen when the underlying card account is closed or the card is suspended. Inactive tokens can't be used to generate cryptograms.
- `payments/network-tokens/token-not-eligible` — The network token is not eligible for the requested action. This can happen if the token is deactivated or revoked by the card network. The token's `status` is set to `inactive` when this error is returned, so subsequent requests against the same token fail fast. Create a new network token for the cardholder before retrying.
- `payments/network-tokens/unavailable-token-service-provider` — The Token Service Provider is unavailable. Retrying tokenization at a later stage may succeed.
- `payments/network-tokens/token-service-provider-provisioning` — The Token Service Provider is provisioning. Retrying tokenization at a later stage may succeed.
- `payments/network-tokens/token-operation-error` — A token operation against the Token Service Provider failed. You can retry the operation, but if the issue persists for more than 24 hours, contact [support@evervault.com](mailto:support@evervault.com).
- `payments/network-tokens/cryptogram-operation-error` — A cryptogram operation against the Token Service Provider failed. You can retry the operation, but if the issue persists for more than 24 hours, contact [support@evervault.com](mailto:support@evervault.com).

### Fallback to PANs

In the event of a transaction decline with a token, it is advisable to attempt the payment authorization again using the PAN (card number) credentials. This best practice ensures a secondary payment route, enhancing the success rate of transactions.

To benefit from card update notifications, you can set up a webhook endpoint and subscribe that endpoint to the `payments.network-token.updated` Webhook Event. Endpoints can be registered using the Evervault Dashboard or programmatically using the Webhook Endpoints API.

## Testing your implementation

You can leverage [Sandbox apps](/developers/sandbox) to test the full merchant enrollment and token creation process without affecting live data. Once you're ready to transition to Live Mode for processing real network tokens, please contact our support team at [support@evervault.com](mailto:support@evervault.com).

### Test cards

In Sandbox mode, you can use specific test cards to simulate various real-life scenarios. These cards can be used in conjunction with any valid expiry date or CVC.

| Number | Brand |
| --- | --- |
| **Successful network tokenization** | |
| 4242 4242 4242 4242 | Visa |
| 5555 5555 5555 4444 | Mastercard |
| **Ineligible card** | |
| 4111 1101 1663 8870 | Visa |
| 5555 5501 3065 9057 | Mastercard |
| **Invalid card** | |
| 4111 1117 3897 3695 | Visa |
| 5555 5504 8784 7545 | Mastercard |
| **Declined Tokenization** | |
| 4111 1101 4848 6405 | Visa |
| 5555 5588 2481 5604 | Mastercard |
| **Unavailable Token Service Provider** | |
| 4111 1160 2899 8260 | Visa |
| 5555 5581 2243 2110 | Mastercard |

- [3D Secure](/cards/3d-secure): Learn how 3D Secure works and how it can be used to enhance your payment security.
- [Card Account Updater](/cards/card-account-updater): Learn how to use Card Account Updater to automatically update card details.


---

# Card Account Updater

_Automatically keep card-on-file details up to date via card network updates to reduce declines and improve renewals._

![A visual of an expired card being replaced by a new one]()

Card Account Updater is a service offered by major card networks to automatically update card-on-file details. Card Account Updater ensures that merchants always have the latest card information (like updated card numbers and expiration dates) for their customers. This service helps maintain seamless recurring billing and card-on-file transactions without needing the customer to manually update their card details. For merchants, this can result in higher authorization rates and improved customer satisfaction.

Unlike traditional methods of handling card updates, where merchants rely on customers to provide new card details, Card Account Updater automatically updates the card information directly from the card issuer. This proactive approach introduces an additional layer of convenience and security for both merchants and customers. Should a card be updated due to expiration, replacement, or re-issuance, Card Account Updater ensures that the merchant receives the updated details promptly, minimizing the risk of transaction declines.

## How Card Account Updater works

![A diagram showing the Card Account Updater process]()

The Card Account Updater process begins when a customer's card is updated by the card issuer due to reasons like expiration, replacement, or re-issuance. The card issuer sends the updated card details to the card network. The card network then forwards these updates to the merchant through the Card Account Updater service. The merchant's payment system receives these updates and automatically replaces the old card details with the new ones, ensuring continuous service for the customer without interruption. Any card updated or replaced with this process is automatically registered for future updates as well.

## The benefits of Card Account Updater

Using Card Account Updater to manage card details offers several advantages over relying on customers to update their information:

- **Improved authorization rate**: Since Card Account Updater ensures that merchants always have the most current card details, transactions are less likely to be declined due to outdated information. This leads to a higher authorization rate and a smoother customer experience.
- **Seamless customer experience**: Customers no longer need to manually update their card details for recurring payments or card-on-file transactions. Card Account Updater automates this process, reducing friction and enhancing the overall customer experience. This is particularly beneficial for subscription-based services, where up to date payment information is crucial.
- **Reduced operational overhead**: By automating the card update process, Card Account Updater eliminates the need for merchants to manually contact customers for updated card information. This reduces the administrative burden on the merchant's staff and allows them to focus on more critical business operations.
- **Improved customer retention**: By ensuring seamless recurring payments, your customers complete payments at a higher rate and stay subscribed for longer.

## Getting started

Evervault provides a set of easy-to-use APIs designed to let you integrate Card Account Updater in minutes without having to interact directly with the card networks.

### Register a card

You need to [register a card](/api#registerCard) with the card network to receive automatic updates. Card registration is idempotent on card number, so you can use the Card object ID as a unique identifier. Registering an existing card number with a different expiry date updates the stored expiry on the existing Card object, rather than creating a new one.

```bash
curl 'https://api.evervault.com/payments/cards' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "number": "4242424242424242",
  "expiry": {
    "month": "09",
    "year": "26"
  }
}'

[ANNOTATION lines=5-5]
You can also provide an encrypted card number to prevent having plaintext card numbers in your infrastructure.
[/ANNOTATION]
```

> **Plaintext card numbers**
>
> In this example, we are sending a plaintext card number to the API. We highly
>   recommend passing an encrypted card number instead to prevent having plaintext
>   card numbers in your infrastructure.

### Handling card updates

In order to receive updates for a card, you need to setup a webhook to subscribe to the `payments.card.updated` event. Endpoints can be registered from the app settings in the Evervault dashboard or programmatically using the [Webhook Endpoints API](/api#webhookEndpoints).

Upon any update dispatched by the card network, a notification message will be sent to your Webhook Endpoint, which is specifically subscribed to the `payments.card.updated` event. This ensures that your system is immediately notified of any changes, allowing for uninterrupted payment processing.

```json
{
  "id": "webhook_event_sdjaskfsadas",
  "type": "payments.card.updated",
  "data": {
    "id": "card_123456789098",
    "number": "ev:Tk9D:Rgz6lOzw9JaRmUML:AuLdYR+a2dZCWv2ZZt0u9lxf6I6EMzPEF3MZytNmtpky:/Nl5NmpyczVK8TdBBP4skI/DWNtwtVNl6hJj0OPlqUo=:$",
    "bin": "424242",
    "lastFour": "4242",
    "expiry": {
      "month": "10",
      "year": "27"
    },
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp",
    "issuer": "Gringotts Wizarding Bank and Trust Company",
    "status": "replaced",
    "replacement": "card_123456789099",
    "createdAt": 1709293284000,
    "updatedAt": 1711633194688
  },
  "createdAt": 1711633194688
}
```

For new expiry dates and new account numbers, the original card's status will be updated to `replaced` and the card's `replacement` field will be set to the UUID of the replacement card. You can use the [Card Account Updater API](/api#retrieveCard) to retrieve the most up to date card details for the replacement card before attempting to transact.

For an account closure, the card status will be updated to `closed`. In this scenario there may or may not be a replacement card. If not, you may wish to contact the cardholder to request their latest payment details.

In some cases, an account update request may indicate that the card on file is invalid. This could be due to a PAN or expiry mismatch or other inconsistency that we otherwise would not be able to validate at the time the card is registered for updates. In this scenario, the existing card's status will be updated to `invalid`. You might want to check your system of record or contact the cardholder to obtain the correct payment details.

## Testing

You can leverage Evervault's [Sandbox apps](/developers/sandbox) to test the full process of receiving and handling card updates without affecting live data. Once you're ready to transition to Live Mode for processing real card updates, please contact our support team at [support@evervault.com](mailto:support@evervault.com).

When using a Sandbox app, you can use the [Cards Simulation API](/api#simulateCardUpdate) to simulate a card update event.

### Simulating a new expiry date

You can simulate a new expiry number update by triggering a simulation request with the `new-expiry-date` update type. You can either provide a specific expiry date for the update, or you can exclude the `expiry` field and we will generate a random expiry date for the update.

```bash
curl 'https://api.evervault.com/payments/cards/:id/simulate' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "updateType": "new-expiry-date",
  "expiry": {
    "month": "09",
    "year": "32"
  }
}'
```

### Simulating a new account number

You can simulate a new account number update by triggering a simulation request with the `new-account-number` update type. You can either provide a specific account number and expiry date for the update, or you can exclude them and we will generate a random account number and expiry date for the update.

```bash
curl 'https://api.evervault.com/payments/cards/:id/simulate' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "updateType": "new-account-number",
  "number": "4242424242424242",
  "expiry": {
    "month": "09",
    "year": "32"
  }
}'
```

### Simulating an account closure

You can simulate an account closure by triggering a simulation request with the `account-closure` update type.

```bash
curl 'https://api.evervault.com/payments/cards/:id/simulate' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "updateType": "account-closure"
}'
```

## Supported card networks

Evervault supports Card Account Updates for Visa, Mastercard, and American Express cards.

- [Insights](/cards/insights-and-verification): Learn how to gain additional insights into the cardholder and the card itself.
- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.


---

# Card Reveal

_Securely display decrypted data in your app using an Evervault-hosted iframe without exposing plaintext to your infrastructure._

![An illustration of an encrypted card being revealed]()

Once you have collected encrypted cardholder data, you may need to display the plaintext card number to your users. Our Card Reveal product allows you to do this safely, without ever handling the card data in plaintext.

## Getting started

The Reveal component allows you to request and display decrypted card data inside of an iframe served from our PCI-compliant infrastructure. Because the request is made from within the Evervault iframe, the plaintext card data is never exposed to your application.

### Retrieving the encrypted card data

To use Reveal, you will first need to have a JSON endpoint that returns the encrypted card data. It is important that this endpoint returns encrypted data, not plaintext. For example, let's say you have the following endpoint to retrieve a stored card:

```text
// GET https://your-api.com/cards/:id

{
  "card": {
      "number": "ev:debug:Tk9D:number:mqrANWE1KMapRVCX:A8Gse2iNxLKy8WLnBDkqtkt+TTSaJFNyc+R/toYd2d8n:FUM5vwjOIrHI+3Jk7QnVCUpHVS0aZQC80ih/wpHtR2o=:$",
      "cvv": "ev:debug:Tk9D:number:YG1KlyImadEc/qJz:A7odbz+iMRub/WHEO9bwLI5tig+nJ12aKCfWHtMU87rJ:/g1rhC8GeaGyWbM1Y0kaT45IKw==:$",
      "expiry": "09/28"
    }
  }
}
```

It's also important that the endpoint that you create sets applicable CORS headers so that it can be accessed from the Reveal component iframe. Otherwise your requests will fail.

```
Access-Control-Allow-Methods: POST, GET
Access-Control-Allow-Origin: https://ui-components.evervault.com
```

Next, you need to create a new [Relay](/relay) for your endpoint, and configure it to decrypt the card data on response. Reveal only accepts requests made to Evervault Relay domains so you must proxy your request through a Relay.

![Reveal Relay Configuration]()

> **Enforce authentication and authorization**
>
> After Relay decrypts the response, your endpoint returns the plaintext card number to the client that made the request. Evervault has no context for which of your customers can access a given card. Your backend must authenticate the request and verify that the caller is authorized to view the card before responding. Treat this endpoint with the same controls you'd apply to any other source of sensitive data.

### Install the Evervault SDK

Once you have an endpoint configured through Relay to retrieve the encrypted data, you can use our client side SDK to display the card data.

#### Browser

Our [JavaScript SDK](/sdks/javascript) is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the [Evervault Dashboard](https://app.evervault.com).

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

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

#### Frequently Asked Questions

##### Why does the SDK need to be loaded from the CDN?

The SDK must be loaded directly from our CDN in order to be PCI Compliant.

##### How do I get my Team ID and App ID?

You can find your Team ID and App ID in the [Evervault Dashboard](https://app.evervault.com).

##### Can I load the SDK asynchronously?

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <script src="https://js.evervault.com/v2" onload="onEvervaultReady()" async></script>
        <script>
          function onEvervaultReady() {
            const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
          }
        </script>
      </head>
    </html>
    ```

#### React

Our React SDK is distributed via npm and can be installed using your preferred package manager.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

### Create a Reveal component

#### Browser

To create an instance of the Reveal component, you will need to pass in a request to your relay endpoint.

```js
// construct a request to your relay endpoint
const request = new Request("https://your-relay-domain.com/cards/:id", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
  },
});

const reveal = evervault.ui.reveal(request);
```

Once you have created an instance of the Reveal component, you can use the `text` method to display data that is returned from the decrypted response. The `text` method accepts a JSON path to the field inside of the response that you want to display. Once you have created a text instance, you must mount it to the DOM using the `mount` method. This will render an iframe that displays only the field data matching the provided JSON path.

```js
// Display text from the decrypted response card.number field
const text = reveal.text("$.card.number", {
format: {{
    regex: /(.{4})/g,
    replace: '$1 ',
  }}
})
text.mount('.card')

```

Learn more about the Reveal component in the [JavaScript SDK](/sdks/javascript#reveal) documentation.

#### React

The `Reveal` component accepts a `request` prop, which is a `Request` object that is used to fetch the encrypted card data. You can then use the `Reveal.Text` component to display the decrypted card number. The `Reveal.Text` component accepts a `path` prop, which is a JSON path to the field inside of the response that you want to display. The `Reveal.Text` component will render an iFrame that displays only the field data matching the provided JSON path.

```jsx
import { Reveal } from "@evervault/react";

function MyComponent() {
  const request = useMemo(() => {
    return new Request("https://your-relay-domain.com/cards/:id", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
      },
    });
  }, []);

  return (
    <Reveal request={request}>
      <h4>Card Number:</h4>
      <Reveal.Text path="$.card.number" />
    </Reveal>
  );
}
```

Learn more about the Reveal component in the [React SDK](/sdks/react#reveal) documentation.

## Styling

The reveal component can be fully customised to match the design of your application. This can be done by passing a `theme` option when rendering the component. A theme is just an object with a styles property. This styles property uses a CSS-as-JS format to define CSS rules for the component. These rules will be compiled to CSS and injected into the iframe.

```js
const text = reveal.text("$.card.number", {
  theme: {
    styles: {
      ":root": {
        "color-scheme": "dark",
      },
      body: {
        fontSize: 14,
        color: "white",
        fontFamily: "monospace",
      },
    },
  },
});
```

- [Card Collection](/cards/card-collection): Learn how to use Card Collection to collect cardholder data.
- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.


---

# Apple Pay

_Integrate Apple Pay with Evervault to capture encrypted payment credentials._

![An illustration of an Apple Pay payment]()

Apple Pay allows customers to securely complete payments using credit or debit cards linked to their Apple account. Evervault has built-in support for Apple Pay. Our Apple Pay component will intercept the Apple Pay token and provide you with direct access to the encrypted payment method, which can then be sent to any payment processor using [Relay](/relay).

> **Sandbox testing**
>
> You can use [Sandbox apps](/developers/sandbox) and Apple's [test cards](https://developer.apple.com/apple-pay/sandbox-testing/) to test Apple Pay end-to-end without charging a real card. Evervault decrypts the Apple Pay payment credentials, the same as in production. For backward compatibility, some existing sandbox apps still receive a substituted test card instead of the real network token. See [Testing (sandbox)](#testing-sandbox) for more details.

## Getting started

All users of Apple pay must adhere to the [Apple Pay Terms and Conditions](https://www.apple.com/legal/internet-services/apple-pay-wallet/us/).

#### Browser

### Create a merchant

Before you can use Apple Pay, you need to create a Merchant record to use for the transaction. You can create a merchant from inside the payments tab in the [Evervault Dashboard](https://app.evervault.com) or via the [Merchants API](/api#createMerchant).

### Verify your domain with Apple

After creating a merchant, Apple needs to verify the domains associated with it. You can add and verify your domains using the Evervault Dashboard under **Payments** > **Apple Pay**.

Alternatively, you can serve [this identifier file](/apple-pay/apple-developer-merchantid-domain-association) from `/.well-known/apple-developer-merchantid-domain-association` on your domain, then register your domain via the [Merchant API](/api#updateMerchant).

You can check the status of your domain verification with Apple via the Dashboard or by using the [Merchant API](/api#merchant). **It may take up to 10 minutes for the verification to complete.**

> **Reverification**
>
> Once a domain is verified, you must ensure that the validation token is always
>   available at the specified URL. If the validation token is not available when
>   Apple periodically attempts to retrieve it, Apple will not be able to verify
>   the domain, and Apple Pay will not work on your website.

### Install the SDK

Our [JavaScript SDK](/sdks/javascript) is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the [Evervault Dashboard](https://app.evervault.com).

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

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

#### Frequently Asked Questions

##### Why does the SDK need to be loaded from the CDN?

The SDK must be loaded directly from our CDN in order to be PCI Compliant.

##### How do I get my Team ID and App ID?

You can find your Team ID and App ID in the [Evervault Dashboard](https://app.evervault.com).

##### Can I load the SDK asynchronously?

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <script src="https://js.evervault.com/v2" onload="onEvervaultReady()" async></script>
        <script>
          function onEvervaultReady() {
            const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
          }
        </script>
      </head>
    </html>
    ```

### Create a transaction

Next, you will need to create a transaction to describe the payment you want to process. You will need to provide the amount, currency, country, and merchant details for the transaction. With Apple Pay a transaction can be a Payment Transaction or a Disbursement Transaction. You can pass either transaction type to the Apple Pay component.

### Pending line items

Line items default to a final amount. For estimates such as tax or shipping that aren't final yet, set `type: "pending"` on the line item. The Apple Pay sheet shows the line as pending instead of displaying the amount. You can also return pending line items from `onShippingAddressChange`, `onPaymentMethodChange`, `onCouponCodeChange`, and `prepareTransaction`.

```javascript
const transaction = evervault.transactions.create({
  amount: 1000,
  currency: "USD",
  country: "US",
  merchantId: "merchant_8f3dc605aa5d",
  lineItems: [
    { label: "Item", amount: 900 },
    { label: "Estimated tax", amount: 100, type: "pending" },
  ],
});
```

### Mount the Apple Pay component

Now that you have created a transaction, you can create and mount the Apple Pay component to display the Apple Pay button to your users. The Apple Pay component takes the transaction you created as a first argument and an options object with a `process` function that will be called with the encrypted payment method when the user completes the payment. The process function is an asynchronous function that takes the encrypted payment method as the first argument and an object with a `fail` function as the second argument. The `fail` function can be called with an error message to display an error to the user.

```javascript
const apple = evervault.ui.applePay(transaction, {
  process: async (paymentMethod, { fail }) => {
    try {
      console.log(paymentMethod.networkToken.number);
      // ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$

      // Send the encrypted payment method to your backend for processing
    } catch (error) {
      fail({
        message: "Cannot pay with payment credentials",
      });
    }
  },
});

apple.on("cancel", () => {
  console.log("Apple Pay canceled");
});

apple.on("error", (error) => {
  console.error("Apple Pay error", error);
});

apple.on("success", () => {
  console.log("Apple Pay success");
});

apple.on("ready", () => {
  console.log("Apple Pay button is ready!");
});

const availability = await apple.availability();

// Only "unsupported" means Apple Pay can't be used on this device/browser at all.
if (availability !== "unsupported") {
  // mount() already handles the difference between "available" and "unavailable" internally.
  apple.mount("#apple-pay");
} else {
  // Apple Pay isn't supported on this device or browser
}
```

### Abort an active session

If the user changes their shipping address to a country that uses a different currency, you cannot update the currency on an open Apple Pay sheet. Call `abort()` to dismiss the sheet, update your transaction with the new currency and country, then let the user tap the Apple Pay button again. Note that `abort()` only works before the user authorizes payment — once they've authorized, use `fail()` in the `process` callback instead.

```javascript
const apple = evervault.ui.applePay(transaction, {
  requestShipping: true,
  onShippingAddressChange: async (address) => {
    const newCurrency = currencyForCountry(address.country);

    if (newCurrency !== transaction.details.currency) {
      await apple.abort();
      return { amount: 0, lineItems: [] };
    }

    return {
      amount: calculateTotal(address),
      lineItems: getLineItems(address),
    };
  },
  process: async (paymentMethod) => {
    // ...
  },
});

apple.on("cancel", () => {
  // Update checkout form currency/country and recreate the transaction if needed
});
```

> **Availability**
>
> There are several requirements that must be met for Apple Pay to be available
>   on the device. If you are having issues with the Apple Pay component not
>   rendering, please check the [Availability](#availability) section below to
>   ensure your device meets all the requirements.

### Process the payment

The `process` function is called when the user authorizes the payment. This is where you should finalize the payment with your payment processor. The encrypted payment method will be passed to the `process` function as the first argument. This should be sent to your backend which can then use [Relay](/relay) to safely send the decrypted payment method to any payment provider.

The full encrypted payment method object contains the following data:

```json
{
  "networkToken": {
    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
    "expiry": {
      "month": "12",
      "year": "31"
    },
    "tokenServiceProvider": "Apple"
  },
  "card": {
    "brand": "visa",
    "lastFour": "1234",
    "displayName": "visa 1234",
    "paymentMethodType": "debit",
    "funding": "debit",
    "segment": "consumer",
    "country": "ie",
    "currency": "eur",
    "issuer": "Revolut Bank Uab"
  },
  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",

  // The ECI value is optional with Apple Pay.
  // Learn more here: https://developer.apple.com/documentation/passkit/payment-token-format-reference#Detailed-payment-data-keys-3D-Secure
  "eci": "5",

  "paymentDataType": "3DSecure",
  "transactionType": "oneOff",
  "transactionId": "5ee9e294a2e79032ca7529b2050c2a878187c54a54f07559cff8281fb9b4716c",

  "billingContact": {
    "familyName": "Doe",
    "givenName": "John",
    "phoneticFamilyName": null,
    "phoneticGivenName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890",
    "addressLines": ["123 Main St", "Apt 4B"],
    "administrativeArea": "State",
    "country": "Country",
    "countryCode": "XX",
    "locality": "City",
    "postalCode": "12345",
    "subAdministrativeArea": "",
    "subLocality": ""
  },
  "shippingContact": {
    "familyName": "Doe",
    "givenName": "John",
    "phoneticFamilyName": null,
    "phoneticGivenName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890",
    "addressLines": ["123 Main St", "Apt 4B"],
    "administrativeArea": "State",
    "country": "Country",
    "countryCode": "XX",
    "locality": "City",
    "postalCode": "12345",
    "subAdministrativeArea": "",
    "subLocality": ""
  },
  "shippingMethod": {
    "id": "standard",
    "label": "Standard Shipping",
    "amount": 299,
    "detail": "3-5 business days"
  }
}
```

The optional `card.paymentMethodType` field is one of `credit`, `debit`, `prepaid`, or `store`. It reflects the funding type of the **card the customer selected** in Apple Wallet (from the Payment Request API’s payment method). Prefer it over BIN-derived metadata such as `funding` when you need to know how the user intends to pay: for dual-network cards, BIN-based fields can still report `credit` even when the customer picked their debit card. If Apple does not provide a type, the field is omitted.

- `paymentDataType` reflects the Apple token format from the credentials API (for example `3DSecure`).
- `transactionType` indicates the transaction category (`oneOff`, `recurring`, or `disbursement`) based on how you created the transaction.
- `transactionId` is Apple's identifier for the token, and comes from the [PKPaymentToken header](https://developer.apple.com/documentation/passkit/payment-token-format-reference#Header-keys-and-values). Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself.
- `billingContact` and `shippingContact` are only populated when the transaction requested those contact fields. Address fields on `shippingContact` require `requestShipping: true`.
- `shippingMethod` is populated when you configured `shippingMethods` and the customer selected one.
- `phoneticFamilyName` and `phoneticGivenName` are populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). If there's no phonetic reading, then these two values are `null`.

## Use Apple Pay with your PSP

You can use Evervault's Apple Pay integration with any PSP. This means you:

- Don't use your PSP's Apple Pay integration.
- Use network tokens (provided by Evervault) with your PSP's APIs.

Evervault generates network tokens for Apple Pay transactions, not your PSP. After you have the network token, use it for all payments, retries, etc. with your PSP. There's no additional configuration (e.g., certificates) with your PSP or Apple needed. Most PSPs have network token APIs and parameters for passing network token data. Like other 3rd party API calls, use [Relay](/relay) to decrypt network token data and send it to your PSP.

## Availability

You can use the `availability` method to check if Apple Pay is available on the device. This method returns a promise that resolves to a string indicating the availability status.

- `available` - Apple Pay is supported, and the browser can confirm a usable card is already set up on the device.
- `unavailable` - Apple Pay is supported, but the browser can't confirm a usable card on the device. This is still a [state you should support](#handling-the-unavailable-state).
- `unsupported` - Apple Pay isn't supported on the device or the browser.

```javascript
const apple = evervault.ui.applePay(transaction, { ...  })
const availability = await apple.availability();
console.log(availability);
// "available"
```

#### Handling the unavailable state

> `unavailable` doesn't mean the customer can't pay. It means the browser
>   can't verify a card is present on the device. `apple.mount()` already
>   accounts for this: it renders the button for both `available` and
>   `unavailable`, and only skips rendering when `availability()` reports
>   `unsupported`.
>
>   If the customer taps the button while `unavailable`, Apple Pay handles it
>   from there. For example, it might prompt them to add a card to Wallet. On a
>   Mac without Touch ID, it might instead show a QR code to scan with a
>   paired iPhone and authorize the payment from there. Seeing
>   a QR code instead of a Touch ID or Face ID prompt is expected in this case, it's not
>   a bug in your integration.
>
>   Chrome and Edge don't have access to the local Apple Wallet the way Safari
>   does. So `availability()` commonly reports `unavailable` (not `available`)
>   in those browsers, even when Apple Pay works using the QR handoff.

In order for Apple Pay to report `available` (rather than `unavailable`), the user's device or browser must additionally meet the following requirements:

- The web page must be served over HTTPS.
- Have at least one card added to their Apple Wallet.
- The user must be using a compatible browser. Apple Pay is supported on Safari, Chrome, and Edge.
- If using Safari:
  - The user must have Apple Pay enabled in their browser settings. Settings > Advanced > Allow websites to check for Apple Pay and Apple card.
  - The user must have access to the biometric authentication controls on their device. If using a laptop this means the laptop must not be in clamshell mode and the user must have access to the Touch ID sensor.

## Customization

Apple Pay allows you to customize the appearance of the payment button with various predefined styles. These can be passed as additional options when initializing the Apple Pay component. You can see the available options in the [JS SDK documentation](/sdks/javascript#uiapplepay).

```javascript
const apple = evervault.ui.applePay(transaction, {
  style: "black",
  borderRadius: 10,
  ...
});
```

## Configure card networks

Apple Pay allows you to specify the card networks that are supported by your merchant. This can be done by passing the `allowedCardNetworks` options when initializing the Apple Pay component. You can see the available options in the [Apple Pay docs](https://developer.apple.com/documentation/applepayontheweb/supported-networks). Please check with your payment processor to ensure that the card networks you specify are supported.

```javascript
const apple = evervault.ui.applePay(transaction, {
  allowedCardNetworks: ["visa", "masterCard"],
  ...
});
```

## Restrict cards by issuer country

To limit payments to cards issued in specific countries, pass `supportedCountries` when initializing the Apple Pay component. Use ISO 3166 country codes. This maps to Apple Pay's [`supportedCountries`](https://developer.apple.com/documentation/applepayontheweb/applepayrequest/supportedcountries) field.

```javascript
const apple = evervault.ui.applePay(transaction, {
  supportedCountries: ["US", "CA"],
  ...
});
```

## Pass application data

You can attach opaque merchant data to the Apple Pay request with `applicationData`. The value must be a Base64-encoded string. Apple includes a hash of this data in the payment token so you can verify it server-side. See Apple's [`applicationData`](https://developer.apple.com/documentation/applepayontheweb/applepayrequest/applicationdata) documentation.

```javascript
const apple = evervault.ui.applePay(transaction, {
  applicationData: btoa(JSON.stringify({ orderId: "order_123" })),
  ...
});
```

## Apple merchant identifier

By default, Evervault uses `merchant.com.evervault.{merchantId}` as the Apple Pay merchant identifier. This works with Evervault's domain verification and merchant-session API.

You can pass a custom `appleMerchantId` when initializing the component to match the iOS SDK surface:

```javascript
const apple = evervault.ui.applePay(transaction, {
  appleMerchantId: "merchant.com.example.store",
  process: async (paymentMethod) => {
    // ...
  },
});
```

A custom identifier is only used by the browser to open the Apple Pay sheet. It doesn't change merchant validation — that still uses Evervault's registered identifier unless the custom ID is separately registered with Apple for your domain.

## Transaction updates

Apple Pay allows you to update the transaction after a user has launched the Apple Pay modal. This can be done by leveraging the options described below.

### Responding to shipping address changes

You may want to alter the transaction amount based on the shipping address provided by the user. Apple Pay allows you to respond to changes in the shipping address after a user has launched the Apple Pay modal. This can be done by passing the `requestShipping` and `onShippingAddressChange` options when initializing the Apple Pay component. The `onShippingAddressChange` function should return an object with an updated `amount` and `lineItems` array.

```javascript
const apple = evervault.ui.applePay(transaction, {
  requestShipping: true,
  onShippingAddressChange: async (newAddress) => {
    const lineItems = getLineItems();
    const transactionAmount = calculateTransactionAmount(lineItems);

    const shippingAmount = await calculateShipping(newAddress.country);
    const shipping = {
      label: "Shipping",
      amount: shippingAmount,
    };
    return {
      amount: transactionAmount + shippingAmount,
      lineItems: [...lineItems, shipping],
    };
  },
});
```

### Offering shipping methods

For one-off payment transactions, you can pass `shippingType` and a `shippingMethods` list so the Apple Pay sheet lets the customer choose how their order is fulfilled. Amounts use the same smallest-currency-unit convention as line items (for example, cents). Mark one method with `selected: true` when the transaction `amount` already includes that method's cost. If none are marked selected, the first method is selected by default.

`shippingMethods` are only supported on one-off payment transactions — recurring and disbursement transactions reject them. Providing `shippingMethods` enables shipping on the sheet (`requestShipping`).

```javascript
const apple = evervault.ui.applePay(transaction, {
  shippingType: "shipping", // "shipping" | "delivery" | "storePickup" | "servicePickup"
  shippingMethods: [
    {
      id: "standard",
      label: "Standard Shipping",
      amount: 299,
      detail: "3-5 business days",
      selected: true,
    },
    {
      id: "express",
      label: "Express Shipping",
      amount: 999,
      detail: "1-2 business days",
    },
  ],
  process: async (paymentMethod) => {
    console.log(paymentMethod.shippingMethod);
    // { id: "express", label: "Express Shipping", amount: 999, detail: "..." }
  },
});
```

When the customer selects a method, the sheet total is updated. Without a merchant callback, the SDK adjusts the total using the selected method's amount (treating the transaction amount as already including the initially selected method). To control totals yourself — for example when shipping cost depends on tax or address — use `onShippingMethodSelected`.

> When relying on the internal recompute, your initial lineItems must include an entry whose label matches the selected method's label, or the shipping line won't be replaced correctly — use `onShippingMethodSelected` for full control.

### Responding to shipping method changes

Pass `onShippingMethodSelected` to recompute the amount and line items when the customer picks a different shipping method. Return an updated `amount` and optional `lineItems`, the same shape as `onShippingAddressChange`.

```javascript
const apple = evervault.ui.applePay(transaction, {
  shippingType: "shipping",
  shippingMethods: [
    {
      id: "standard",
      label: "Standard Shipping",
      amount: 299,
      detail: "3-5 business days",
      selected: true,
    },
    {
      id: "express",
      label: "Express Shipping",
      amount: 999,
      detail: "1-2 business days",
    },
  ],
  onShippingMethodSelected: async (method) => {
    const lineItems = getLineItems(); // goods only
    return {
      amount: calculateTransactionAmount(lineItems) + method.amount,
      lineItems: [...lineItems, { label: method.label, amount: method.amount }],
    };
  },
});
```

### Responding to billing address changes

You can leverage the `requestBillingAddress` and `onPaymentMethodChange` options when initializing the Apple Pay component to respond to changes in the billing address.

```javascript
const apple = evervault.ui.applePay(transaction, {
  requestBillingAddress: true,
  onPaymentMethodChange: async (event) => {
    const lineItems = getLineItems(1);
    if (event.billingContact?.country === getCurrentCountry()) {
      lineItems.push({ label: "National tax", amount: 1000 });
    } else {
      lineItems.push({ label: "International tax", amount: 2000 });
    }
    const total = lineItems.reduce((acc, item) => acc + item.amount, 0);
    return {
      amount: total,
      lineItems,
    };
  },
});
```

> Due to limitations in the Apple Pay API, if also requesting a shipping
>   address, the `onPaymentMethodChange` event will not return the billing
>   address.

### Prefilling billing and shipping contact

If you know the customer's billing or shipping details (for example, from a logged-in checkout), you can prefill them on the Apple Pay sheet with `billingContact` and `shippingContact`. Set `requestBillingAddress: true` and `requestShipping: true` so the postal address fields appear on the sheet.

These options apply to payment and recurring transactions only. Disbursement transactions use `requiredRecipientDetails` on the transaction instead.

```javascript
const apple = evervault.ui.applePay(transaction, {
  requestBillingAddress: true,
  requestShipping: true,
  billingContact: {
    givenName: "Jane",
    familyName: "Doe",
    addressLines: ["123 Main St"],
    locality: "San Francisco",
    administrativeArea: "CA",
    postalCode: "94105",
    countryCode: "US",
    country: "United States",
  },
  shippingContact: {
    givenName: "Jane",
    familyName: "Doe",
    emailAddress: "jane.doe@example.com",
    phoneNumber: "+14155550100",
    addressLines: ["123 Main St"],
    locality: "San Francisco",
    administrativeArea: "CA",
    postalCode: "94105",
    countryCode: "US",
    country: "United States",
  },
  process: async (paymentMethod) => {
    // ...
  },
});
```

### Responding to coupon code changes

To show a coupon field on the Apple Pay sheet, set `supportsCouponCode: true`. Optionally pass an initial `couponCode`. When the customer changes the code, `onCouponCodeChange` runs — return an updated `amount` and `lineItems`. To reject a code, return `error` with `code` set to `couponCodeInvalid` or `couponCodeExpired`.

```javascript
const apple = evervault.ui.applePay(transaction, {
  supportsCouponCode: true,
  couponCode: "",
  onCouponCodeChange: async (code) => {
    const normalized = code.trim().toUpperCase();

    if (normalized === "SAVE20") {
      return {
        amount: 800,
        lineItems: [
          { label: "Item", amount: 1000 },
          { label: "Coupon SAVE20", amount: -200 },
        ],
      };
    }

    if (normalized === "") {
      return {
        amount: 1000,
        lineItems: [{ label: "Item", amount: 1000 }],
      };
    }

    return {
      amount: 1000,
      lineItems: [{ label: "Item", amount: 1000 }],
      error: {
        code: "couponCodeInvalid",
        message: "Unknown coupon code",
      },
    };
  },
  process: async (paymentMethod) => {
    // ...
  },
});
```

### Updating a transaction when Apple Pay is triggered

In some scenarios, you might want to perform an action before presenting the Apple Pay modal to the customer (e.g., applying a discount collected on your own checkout page). You can do this by passing the `prepareTransaction` option when initializing the Apple Pay component. The `prepareTransaction` function returns a promise that resolves to an object with an updated `amount` and `lineItems` array.

To let customers enter a coupon on the Apple Pay sheet itself, use [`supportsCouponCode`](#responding-to-coupon-code-changes) instead.

```javascript
const apple = evervault.ui.applePay(transaction, {
  prepareTransaction: async () => {
    const updatedTransaction = await offerDiscount();
    return {
      amount: updatedTransaction.amount,
      lineItems: updatedTransaction.lineItems,
    };
  },
});
```

## Content security policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.

```
script-src https://js.evervault.com;
connect-src https://keys.evervault.com https://api.evervault.com;
frame-src https://ui-components.evervault.com;
```

## Notes

- The Apple Pay UI Component is currently not supported on devices in Mainland China.
- The Apple Pay UI Component requires a secure context (HTTPS) to function correctly.

#### Swift

### Register for an Apple Merchant ID

Before you can use Apple Pay for iOS with Evervault you need to obtain an Apple Merchant ID by [registering for a new identifier](https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier) on the Apple Developer portal. Fill out the description and identifier. We recommend you use the name of your app as the identifier e.g. `merchant.com.<YOUR_APPS_NAME>`

### Create a Payment Processing Certificate

Apple Pay needs to encrypt payment data such as card details. You will need a payment processing certificate for your app to allow Apple Pay to encrypt those details within your app.

In the Evervault dashboard, click the `Payments` tab at the top of the page. Then, on the left-hand side of the page click `Apple Pay` and at the bottom of the page under Certificates, click `Add certificate`. Follow the on screen instructions.

As part of this flow, Evervault will provide you with a certificate signing request that you must download.

Then, in a new tab, in the Apple Developer portal, under [Certificates](https://developer.apple.com/account/resources/certificates/add), create an Apple Pay Payment Processing Certificate, select the Merchant ID that you created in the previous step and click Continue. Under the Apple Pay Payment Processing Certificate section, click `Create Certificatea` and upload the certificate signing request you downloaded from the Evervault dashboard.

Download the Apple certificate you just created and go back to the Evervault dashboard and in the certificate set up dialog, upload the certificate you just downloaded from Apple.

### Setup Xcode

Once you have created your merchant identifier and payment processing certificate, you need to add the Apple Pay capability to your app in Xcode.

Open your project settings, click the `Signing & Capabilities` tab, and add the Apple Pay capability. You might be prompted to sign in to your developer account. Select the merchant ID you created earlier, and now your app is ready to accept Apple Pay.

### Install the Evervault SDK

The Evervault iOS SDK can be installed using the Swift Package Manager.

1. Open your Xcode project.
2. Navigate to **File** > **Swift Packages** > **Add Package Dependency**.
3. Enter the repository URL for the Evervault iOS SDK: `https://github.com/evervault/evervault-ios.git`.
4. Choose the latest available version or specify a version rule.
5. Click **Next** and follow the instructions to integrate the package into your project.

#### Initialize SDK

Now, let's initialize the SDK using our App and Team ID. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```swift
import EvervaultCore

Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

If you need multiple instances of the Evervault SDK you can use the initializer as follows:

```swift
import EvervaultCore

let evervault = Evervault.init(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

### Create a transaction (iOS)

Next you will need to create a transaction to describe the payment you want to process. You will need to provide the country, currency, and line items for the transaction. The last item is the total for the transaction.

If the transaction isn't constructed correctly — for example, the `country` or `currency` fields aren't valid, or the transaction has no summary items — Evervault throws `EvervaultError.InvalidCountryError`, `EvervaultError.InvalidCurrencyError`, or `EvervaultError.EmptyTransactionError` respectively.

Please refer to [Apple's documentation](https://developer.apple.com/documentation/passkit/pkpaymentrequest/#Setting-currency-and-region-information) on requirements for country and currency and amount fields.

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

### Pending line items (iOS)

Line items default to a final amount. For estimates such as tax or shipping that aren't final, pass `type: .pending` to `SummaryItem`. The Apple Pay sheet shows an ellipsis (`…`) instead of an amount for that line. This maps to PassKit's [PKPaymentSummaryItemType](https://developer.apple.com/documentation/passkit/pkpaymentsummaryitemtype).

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Estimated Tax", amount: Amount("2.50"), type: .pending),
    SummaryItem(label: "Total", amount: Amount("32.50"))
  ]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

`OneOffPaymentTransaction` and `RecurringPaymentTransaction` also accept a `requestPayerDetails` parameter to request billing contact fields — such as the payer's name, email, phone, or postal address — using PassKit's own `PKContactField` values:

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  requestPayerDetails: [.name, .phoneticName, .phoneNumber, .emailAddress, .postalAddress]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

If you need to collect a shipping address, pass `shippingType`, `shippingMethods`, and `requiredShippingContactFields` to `OneOffPaymentTransaction`. `shippingMethods` are [`PKShippingMethod`](https://developer.apple.com/documentation/passkit/pkshippingmethod) instances the customer can choose between on the payment sheet:

```swift
import EvervaultPayment
import PassKit

let expressShipping = ShippingMethod(label: "Express Shipping", amount: NSDecimalNumber(string: "9.99"))
expressShipping.identifier = "express_1day"
expressShipping.detail = "Arrives in 1–2 business days."

let standardShipping = ShippingMethod(label: "Standard Shipping", amount: NSDecimalNumber(string: "2.99"))
standardShipping.identifier = "standard_3day"
standardShipping.detail = "Arrives in 3-5 business days."

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Standard Shipping", amount: Amount("2.99")),
    SummaryItem(label: "Total", amount: Amount("37.99"))
  ],
  shippingType: .shipping,
  shippingMethods: [expressShipping, standardShipping],
  requiredShippingContactFields: [.postalAddress, .name, .phoneNumber]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

Use the `onShippingAddressChange` modifier on `EvervaultPaymentViewRepresentable` (see [Render the Apple Pay button](#render-the-apple-pay-button)) to update the summary items when the customer picks a different shipping address.

For subscriptions, use `RecurringPaymentTransaction`. You must provide a `managementURL` where customers can manage their subscription, and a `regularBilling` [PKRecurringPaymentSummaryItem](https://developer.apple.com/documentation/passkit/pkrecurringpaymentsummaryitem) describing the billing interval. `trialBilling` and `billingAgreement` are optional and are set on the transaction after it's constructed. It also accepts the same `shippingType` and `requiredShippingContactFields` parameters as `OneOffPaymentTransaction` above. `shippingMethods` are only supported on one-off payment transactions — recurring and disbursement transactions reject them:

```swift
import EvervaultPayment
import PassKit

let regularBilling = PKRecurringPaymentSummaryItem(label: "Pro Subscription", amount: 5.00)
regularBilling.intervalUnit = .month
regularBilling.intervalCount = 1

var recurring = try! RecurringPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [],
  paymentDescription: "Monthly Pro subscription",
  regularBilling: regularBilling,
  managementURL: URL(string: "https://www.merchant.com/manage-subscriptions")!
)

recurring.trialBilling = PKRecurringPaymentSummaryItem(label: "Trial", amount: 0)
recurring.billingAgreement = "https://www.merchant.com/billing-agreement"

let transaction = EvervaultPayment.Transaction.recurringPayment(recurring)
```

Both `OneOffPaymentTransaction` and `RecurringPaymentTransaction` support a coupon code field on the Apple Pay sheet. Set `supportsCouponCode: true`, and optionally pass an initial `couponCode`:

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  supportsCouponCode: true
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

Use the `onCouponCodeChange` modifier on `EvervaultPaymentViewRepresentable` (see [Render the Apple Pay button](#render-the-apple-pay-button)) to recalculate the summary items, or reject the code, when the customer changes it. Coupon codes aren't available on `DisbursementTransaction`, since that's a payout rather than a purchase.

### Restrict issuer countries and pass application data (iOS)

`OneOffPaymentTransaction` and `RecurringPaymentTransaction` accept a `supportedCountries` parameter to limit payments to cards issued in specific countries. Use ISO 3166 country codes. This maps to PassKit's [supportedCountries](https://developer.apple.com/documentation/passkit/pkpaymentrequest/supportedcountries) field. It isn't available on `DisbursementTransaction`, which has no equivalent property.

You can also attach merchant data to the request with `applicationData`. Apple includes a hash of this data in the payment token so you can verify it server-side. This maps to PassKit's [applicationData](https://developer.apple.com/documentation/passkit/pkpaymentrequest/applicationdata) field, and is also available on `DisbursementTransaction` using [PKDisbursementRequest.applicationData](https://developer.apple.com/documentation/passkit/pkdisbursementrequest/applicationdata).

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  supportedCountries: ["US", "CA"],
  applicationData: Data("order_123".utf8)
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

For payouts to a customer's card, use `DisbursementTransaction` and provide:

- a `disbursementItem` describing the payout.
- the `requiredRecipientDetails` you need to collect from the recipient.
- the `merchantCapability` your merchant account supports.

You can optionally pass an `instantOutFee` and [applicationData](#prefilling-billing-and-shipping-contact-ios).

```swift
import EvervaultPayment

let disbursement = try! DisbursementTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Withdrawal Summary", amount: Amount("41.00")),
    SummaryItem(label: "EUR Balance", amount: Amount("41.00"))
  ],
  disbursementItem: SummaryItem(label: "Disbursement", amount: Amount("41.00")),
  instantOutFee: SummaryItem(label: "Instant funds out fee", amount: Amount("1.00")),
  requiredRecipientDetails: [.emailAddress, .phoneNumber],
  merchantCapability: .instantFundsOut,
  applicationData: Data("payout_456".utf8)
)

let transaction = EvervaultPayment.Transaction.disbursement(disbursement)
```

### Prefilling billing and shipping contact (iOS)

If you know the customer's billing or shipping details (for example, from a logged-in checkout), you can prefill them on the Apple Pay sheet with `billingContact` and `shippingContact`. Include `.postalAddress` in `requestPayerDetails` and `requiredShippingContactFields` so the postal address fields appear on the sheet.

These options apply to payments and recurring transactions only. Disbursement transactions use `requiredRecipientDetails` on the transaction instead.

```swift
import EvervaultPayment

let billingContact = ApplePayPaymentContact(
  givenName: "Jane",
  familyName: "Doe",
  addressLines: ["123 Main St"],
  locality: "San Francisco",
  postalCode: "94105",
  administrativeArea: "CA",
  country: "United States",
  countryCode: "US"
)

let shippingContact = ApplePayPaymentContact(
  givenName: "Jane",
  familyName: "Doe",
  emailAddress: "jane.doe@example.com",
  phoneNumber: "+14155550100",
  addressLines: ["123 Main St"],
  locality: "San Francisco",
  postalCode: "94105",
  administrativeArea: "CA",
  country: "United States",
  countryCode: "US"
)

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  shippingType: .shipping,
  shippingMethods: [],
  requiredShippingContactFields: [.postalAddress],
  requestPayerDetails: [.postalAddress],
  billingContact: billingContact,
  shippingContact: shippingContact
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

### Check if Apple Pay is available

Before displaying Apple Pay as a payment option, use the `availability(supportedNetworks:)` method to check whether the device supports Apple Pay, and whether the customer has a card in their wallet. It returns one of three states, matching the [web SDK](#availability):

- `available`: Apple Pay is supported and the customer has a usable card.
- `unavailable`: Apple Pay is supported, but the customer hasn't added a card for the networks you accept.
- `unsupported`: Apple Pay isn't supported on this device.

```swift
let availability = EvervaultPaymentViewRepresentable.availability(supportedNetworks: [.visa, .masterCard, .amex])
```

Use `unsupported` to hide the Apple Pay button entirely. Use `unavailable` to show a **Set Up Apple Pay** button instead of a regular buy button (see [Customise the Apple Pay button](#customise-the-apple-pay-button) for more details).

If you support disbursement transactions, also check `supportsDisbursements()`. Disbursements require iOS 17+, so this returns `false` on earlier versions even if `availability(supportedNetworks:)` reports `available`:

```swift
let canDisburse = EvervaultPaymentViewRepresentable.supportsDisbursements()
```

> **Deprecated**
>
> `isAvailable()` only reports whether the device is capable of Apple Pay. It doesn't tell you whether the customer has a card set up. Because of that, it can't distinguish between "no card added" and "card not supported." Use `availability(supportedNetworks:)` instead.

```swift
let isAvailable = EvervaultPaymentViewRepresentable.isAvailable()
```

### Render the Apple Pay button

Next you can render the Apple Pay button. When you do this, you will need to pass in your Evervault App ID, your Apple Merchant Identifier, the transaction object, the card networks you support, any custom button styles, and a callback closure:

- `authorizedResponse`: Whenever the user successfully authorizes the payment, the decrypted ApplePayResponse (containing token, card info, cryptogram, etc.) will be written into your authorizedResponse variable. You can react to that state change however you like — navigate onward, show a confirmation screen, or send it off to your own backend to be sent via an Evervault Relay to your PSP. Refer to this section for the structure of the response.
- `onResult`: Use this callback to reset UI state or advance your checkout flow after the sheet closes with a definite outcome (either success or failure). Failures can happen when Apple Pay is unavailable, the transaction is invalid, presentation fails, or if Evervault can't decrypt the payment details. The callback returns a `Result<Void, EvervaultError>`. The `EvervaultError` includes a `localizedDescription` you can display in an alert, log for diagnostics, or present however appropriate. `onResult` doesn't fire if the customer cancels.
- `onCancel`: Use this modifier to detect when the customer dismisses the sheet without authorizing a payment (e.g., taps **Cancel**). This is distinct from the success or failure provided by `onResult`.
- `shouldAuthorize`: Use this modifier to inspect the authorized payment and approve or reject it before the sheet reports success. Return `.success(())` to proceed, or `.failure(reason)` to reject the payment, where `reason` is any `Error`. Rejections are reported through `onDecline`, never `onResult`. This closure runs on the main actor, so it's safe to update UI state directly inside it.
- `onDecline`: Use this modifier to handle a payment you rejected from `shouldAuthorize`. It fires only after the sheet closes, so it's safe to present your own UI in response. `onDecline` includes the `reason` passed in `shouldAuthorize`, and is distinct from `onResult`, which only reports SDK-level success or failure and doesn't fire for a decline.
- `onCouponCodeChange`: Use this modifier to react when the customer changes the coupon code on the Apple Pay sheet (shown only when `supportsCouponCode` is set on the transaction). If the coupon code is valid, return a [PKPaymentRequestCouponCodeUpdate](https://developer.apple.com/documentation/passkit/pkpaymentrequestcouponcodeupdate) with the recalculated summary items. If it's invalid, you can return `errors` instead (e.g., `PKPaymentRequest.paymentCouponCodeInvalidError(localizedDescription:)` to reject the coupon code.

```swift
// Example decline reason — conforms to `Error`, so `onDecline` can switch over it exhaustively.
enum DeclineReason: Error, LocalizedError {
  case prepaidCardNotAccepted

  var errorDescription: String? {
    switch self {
    case .prepaidCardNotAccepted:
      return "Prepaid cards are not accepted"
    }
  }
}

struct ContentView: View {
  @State private var applePayResponse: ApplePayResponse? = nil
  let transaction = buildTransaction()

  var body: some View {
    EvervaultPaymentViewRepresentable(
      appId: "YOUR_EVERVAULT_APP_ID",
      appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
      transaction: transaction,
      supportedNetworks: [.visa, .masterCard, .amex],
      authorizedResponse: $applePayResponse) { result in
          switch result {
          case .success(_):
              print("Payment sheet dismissed with success")
              if (applePayResponse != nil) {
                  // Send to PSP via Relay on your backend
              }
              break
          case let .failure(error):
              print("Payment error: \(error.localizedDescription)")
              break
          }
      }
      .onCancel {
          print("Payment sheet cancelled")
      }
      .onDecline { reason in
          print("Payment declined: \(reason.localizedDescription)")
      }
      .shouldAuthorize { response in
          // Example merchant rule: reject prepaid cards.
          if response?.card.funding == "prepaid" {
              return .failure(DeclineReason.prepaidCardNotAccepted)
          }
          return .success(())
      }
  }
}
```

### Processing the Payment

If the payment is handled successfully, the Evervault encrypted payment method is available in `$applePayResponse` (in the example above). The `authorizedResponse` is an `ApplePayResponse` object containing the payment method details encrypted with the Evervault public key. You can send this encrypted payment method to your server and use Evervault Relay to decrypt the payment details when you send them to your PSP.

The ApplePayResponse object represented as JSON contains the following fields:

```json
{
  "networkToken": {
    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
    "expiry": {
      "month": "12",
      "year": "31"
    },
    "rawExpiry": "12/31",
    "tokenServiceProvider": "Apple"
  },
  "card": {
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "ie",
    "currency": "eur",
    "issuer": "Revolut Bank Uab"
  },
  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",
  // The ECI value is optional with Apple Pay.
  // Learn more here: https://developer.apple.com/documentation/passkit/payment-token-format-reference#Detailed-payment-data-keys-3D-Secure
  "eci": "5",
  "paymentDataType": "3DSecure",
  "deviceManufacturerIdentifier": "string",
  "transactionType": "oneOff",
  "transactionId": "5ee9e294a2e79032ca7529b2050c2a878187c54a54f07559cff8281fb9b4716c",

  // Only present if you requested the corresponding contact fields on the transaction
  "billingContact": {
    "givenName": "John",
    "familyName": "Doe",
    "phoneticGivenName": null,
    "phoneticFamilyName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890",
    "postalAddress": {
      "street": "123 Main St",
      "city": "City",
      "state": "State",
      "postalCode": "12345",
      "country": "Country",
      "isoCountryCode": "XX"
    }
  },
  "shippingContact": {
    "givenName": "John",
    "familyName": "Doe",
    "phoneticGivenName": null,
    "phoneticFamilyName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890"
  }
}
```

- `rawExpiry`: the token's expiry in `MM/YY` format, as returned by Apple. Use `expiry.month`/`expiry.year` instead if you need the parsed values.
- `transactionType`: indicates the transaction category (`oneOff`, `recurring`, or `disbursement`) based on how you created the transaction.
- `transactionId`: Apple's identifier for the token, from the [PKPaymentToken header](https://developer.apple.com/documentation/passkit/payment-token-format-reference#Header-keys-and-values). Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself.
- `billingContact` / `shippingContact`: only populated when the transaction requested those contact fields.
- `phoneticFamilyName` / `phoneticGivenName`: populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). `null` otherwise.

### Using EvervaultPaymentView directly (UIKit)

If your app doesn't use SwiftUI, render Apple Pay with the raw `EvervaultPaymentView` — a `UIView` subclass — and its `EvervaultPaymentViewDelegate` protocol, instead of `EvervaultPaymentViewRepresentable`:

```swift
import UIKit
import EvervaultPayment

class CheckoutViewController: UIViewController, EvervaultPaymentViewDelegate {
  private var applePayResponse: ApplePayResponse?

  override func viewDidLoad() {
    super.viewDidLoad()

    let paymentView = EvervaultPaymentView(
      appId: "YOUR_EVERVAULT_APP_ID",
      appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
      transaction: buildTransaction(),
      supportedNetworks: [.visa, .masterCard, .amex],
      buttonStyle: .whiteOutline,
      buttonType: .checkout
    )
    paymentView.delegate = self
    view.addSubview(paymentView)
    // Position `paymentView` with Auto Layout or a frame, as you would any other UIView.
  }

  // Required. Fired when a payment is authorized, before the sheet dismisses.
  func evervaultPaymentView(_ view: EvervaultPaymentView, didAuthorizePayment result: ApplePayResponse?) {
    applePayResponse = result
  }

  // Optional — mirrors the SwiftUI wrapper's `onResult`.
  func evervaultPaymentView(_ view: EvervaultPaymentView, didFinishWithResult result: Result<Void, EvervaultError>) {
    switch result {
    case .success:
      if applePayResponse != nil {
        // Send to PSP via Relay on your backend
      }
    case let .failure(error):
      print("Payment error: \(error.localizedDescription)")
    }
  }

  // Optional — mirrors the SwiftUI wrapper's `onCancel`.
  func evervaultPaymentViewDidCancel(_ view: EvervaultPaymentView) {
    print("Payment sheet cancelled")
  }
}
```

**Delegate methods**

`EvervaultPaymentViewDelegate` has multiple methods, but only `evervaultPaymentView(_:didAuthorizePayment:)` is required. The rest have default no-op implementations, so implement only the ones you need. Each maps to a modifier on the SwiftUI wrapper:

- `didAuthorizePayment`: the only required method. Writes the decrypted `ApplePayResponse` into your own state, in place of the SwiftUI wrapper's `authorizedResponse` binding.
- `didFinishWithResult`: mirrors `onResult`.
- `evervaultPaymentViewDidCancel`: mirrors `onCancel`.
- `didDeclinePayment`: mirrors `onDecline`.
- `shouldAuthorize`: mirrors `shouldAuthorize`.
- `didSelectShippingContact`: mirrors `onShippingAddressChange`.
- `didUpdatePaymentMethod`: mirrors `onPaymentMethodChange`.
- `didChangeCouponCode`: mirrors `onCouponCodeChange`.
- `prepareTransaction`: mirrors `prepareTransaction`.

**Static methods**

- `availability(supportedNetworks:)`: works the same as on `EvervaultPaymentViewRepresentable`.
- `supportsDisbursements()`: no equivalent on `EvervaultPaymentView`. Call PassKit's own `PKPaymentAuthorizationViewController.supportsDisbursements()` (iOS 17+) directly instead.

## Customise the Apple Pay button

When initialising the `EvervaultPaymentViewRepresentable` you can pass two optional parameters — `buttonType` and `buttonStyle`. Please refer to the [Apple PassKit documentation](https://developer.apple.com/documentation/passkit/pkpaymentbutton#Configuring-the-appearance) on what preset button styles and types are available.

```swift
EvervaultPaymentViewRepresentable(
  // other fields...
  buttonStyle: .whiteOutline,
  buttonType: .checkout,
)
```

If `availability(supportedNetworks:)` returns `unavailable`, Apple recommends showing the **Set Up Apple Pay** button instead of the default buy button. This takes the customer through the flow for adding a card rather than opening a payment sheet, which would fail.

```swift
EvervaultPaymentViewRepresentable(
  // other fields...
  buttonStyle: .whiteOutline,
  buttonType: availability == .unavailable ? .setUp : .checkout,
)
```

## Error Handling

All errors from creating the `Transaction` object and the errors surfaced in the `onResult` callback are of type `EvervaultError`.

- `InvalidTransactionError`: This error is thrown when there is an issue with the transaction. As a guideline to help prevent encountering this error:
  - `amount`: The format of this value depends on the `currency`. It follows ISO 4217 and depends on the minor unit of the currency e.g the number of decimal points for `USD` is 2, so the amount must be formatted as "50.00". This error will be thrown if you try to format the `amount` as "50.0". As another example, `JPY` has no minor unit so the `amount` must be formatted as "1000".
- `InvalidCurrencyError`: The currency is the three-letter ISO 4217 currency code that determines the currency the payment request uses. This error is thrown if the currency doesn't match this spec.
- `InvalidCountryError`: The country is the two-letter ISO 3166 country code. This error is thrown if the country doesn't match this spec.
- `EmptyTransactionError`: This error is thrown when a transaction has no summary items. The transaction must have at least 1 summary items, and the final item is the total.
- `ApplePayUnavailableError`: This error is thrown when Apple Pay isn't available on the device.
- `ApplePayPaymentSheetError`: This error is thrown when an underlying error with the Apple Pay payment sheet occurs.
- `UnsupportedVersionError`: This error is thrown when trying to access a method that's not available on the current version of iOS.
- `ApplePayAuthorizationError`: This error is thrown when something goes wrong when authenticating with Apple Pay. The underlying error from Apple Pay is provided.
- `InternalError`: This error is thrown when something goes wrong during the handling of the payment data. An underlying reason is provided in this case.

## Testing (sandbox)

In [Sandbox apps](/developers/sandbox), Apple Pay follows the same integration flow as production. The customer completes a real Apple Pay authorization in Apple Wallet, and Evervault decrypts the real payment credentials from that token.

The Apple Pay sandbox environment allows merchants to test their implementation of Apple Pay with test credit and debit cards.

You’ll need the following to test Apple Pay in the sandbox:

- iPhone 6 or later, iPad mini 3 or later, iPad Air 2, iPad Pro, or Apple Watch
- App Store Connect sandbox tester account
- Supported test credentials

Follow the [Apple Pay sandbox guide](https://developer.apple.com/apple-pay/sandbox-testing/) from Apple for more information on how to set up a sandbox account and add test cards to your Apple Wallet.

This applies to both the [JavaScript SDK](/sdks/javascript#uiapplepay) (web) and [iOS SDK](/sdks/ios#apple-pay). No extra request fields are required — use the Apple Pay component as documented above.

### Legacy test cards

> **Legacy behavior**
>
> In both cases, the value is returned Evervault-encrypted, ready to relay to your payment processor. For backward compatibility, Sandbox apps created before September 2026 receive a substituted test card number instead of the real network token. All other Sandbox apps receive the real network token, matching production functionality. Use [Apple's test cards](https://developer.apple.com/apple-pay/sandbox-testing/) for testing in new Sandbox apps. If your app is on legacy behavior and you'd like to receive the real network token, contact [support@evervault.com](mailto:support@evervault.com).

On legacy apps, based on the brand of the card the customer selects in their Apple Wallet, the encrypted `networkToken.number` you receive corresponds to:

| Number | Brand |
| --- | --- |
| **Supported brands** | |
| 4242 4242 4242 4242 | Visa |
| 5555 5555 5555 4444 | Mastercard |
| 3782 8224 6310 005 | American Express |
| 6011 1111 1111 1117 | Discover |

If the selected card brand is not Visa, Mastercard, American Express, or Discover, Evervault defaults to the Visa test card (`4242 4242 4242 4242`).

- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.
- [Google Pay](/cards/google-pay): Learn how to integrate Google Pay into your app with Evervault.


---

# Google Pay

_Integrate Google Pay with Evervault to capture encrypted payment credentials across web and Android._

![An illustration of a Google Pay payment]()

Google Pay allows customers to securely complete payments using credit or debit cards linked to their Google account. Evervault has built-in support for Google Pay. Our Google Pay component will intercept the Google Pay token and provide you with direct access to the encrypted payment method, which can then be sent to any payment processor using [Relay](/relay).

## Getting started

All users of Google Pay must agree to the [Google Pay Terms and Conditions](https://payments.developers.google.com/terms/sellertos).

### Create a merchant

Before you can use Google Pay, you need to create a merchant record to use for the transaction. You can create a merchant from inside the payments section in the [Evervault Dashboard](https://app.evervault.com) or via the [Merchants API](/api#createMerchant).

### Install the SDK

#### Browser

Our [JavaScript SDK](/sdks/javascript) is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the [Evervault Dashboard](https://app.evervault.com).

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

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

#### Frequently Asked Questions

##### Why does the SDK need to be loaded from the CDN?

The SDK must be loaded directly from our CDN in order to be PCI Compliant.

##### How do I get my Team ID and App ID?

You can find your Team ID and App ID in the [Evervault Dashboard](https://app.evervault.com).

##### Can I load the SDK asynchronously?

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <script src="https://js.evervault.com/v2" onload="onEvervaultReady()" async></script>
        <script>
          function onEvervaultReady() {
            const evervault = new Evervault('<TEAM_ID>', '<APP_ID>');
          }
        </script>
      </head>
    </html>
    ```

#### Android

Our Android SDK distributed via [maven](https://central.sonatype.com/search?q=com.evervault.sdk), and can be installed using your preferred build tool.

If you are installing `evervault-inputs` from version `2.0.0` and onwards you will also need to add the JitPack repository to your build file:

```kotlin
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
  }
}
```

#### Gradle DSL

```kotlin
implementation("com.evervault.sdk:evervault-core:1.2")
implementation("com.evervault.sdk:evervault-inputs:2.0.0")
implementation("com.evervault.sdk:evervault-enclaves:2.0.0")
```

#### Maven

```xml
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-core</artifactId>
  <version>1.2</version>
  </dependency>
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-inputs</artifactId>
  <version>2.0.0</version>
  </dependency>
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-enclaves</artifactId>
  <version>2.0.0</version>
  </dependency>
```

#### Initialize SDK

Before using the Evervault Android SDK, you need to configure it with your Evervault Team ID and App ID. This step is essential for establishing a connection with the Evervault encryption service.

```kotlin
Evervault.shared.configure("<TEAM_ID>", "<APP_ID>")
```

Make sure to replace `<TEAM_ID>` and `<APP_ID>` with your actual Evervault Team ID and App ID which can be found in the [Evervault Dashboard](https://app.evervault.com)

#### Android

### Prerequisites

To support Evervault Google Pay in Android, you need to add the following to your `build.gradle.kts`.

```kotlin
dependencies {
    implementation("com.evervault.sdk:evervault-inputs:2.0.0")
}
```

You will also need to add the JitPack repository to your build file:

```kotlin
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
  }
}
```

To use Google Pay, first you need to enable the Google Pay API by adding the following to the `<application>` tag of your `AndroidManifest.xml`:

```xml
<application>
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>
```

### Instantiate the EvervaultPaymentViewModel

The Evervault Android SDK provides a Google Pay button composable and view model to encapsulate all Google Pay setup, readiness checks, payment data handling, and interception of the Google Pay token to provide you with direct access to the encrypted payment method, which can then be sent to any payment processor using [Evervault Relay](/relay).

To initiate the view model you need to pass a `Config` with a minimum of `appId` and `merchantId`.

```kotlin
private val viewModel: EvervaultPayViewModel by viewModels {
  EvervaultPayViewModelFactory(
    application,
    Config(
      appId = "YOUR_EVERVAULT_APP_ID", // Your Evervault App ID
      merchantId = "YOUR_EVERVAULT_MERCHANT_ID", // Your Evervault Merchant ID
    )
  )
}
```

### React to PaymentState

`PaymentState` is your single source of truth for what should happen in the UI. Handle it reactively so that screens transition automatically as soon as the view model publishes a new state. An example of handling these can be found at the bottom of this section.

| State | Typical timing | What you should do |
| --- | --- | --- |
| `NotStarted` | Immediately after composition, before you call `start()` | Display a progress indicator or a placeholder so users know something is loading. |
| `Unavailable` | `start()` has been called but Google Pay isn't available on the device. | Display other payment options instead. |
| `Available` | `start()` has been called and Google Pay is available on the device. | Display the Google Pay button. |
| `Error` | There was an issue with the payment sheet and it closed with an error. Carries a `code` and an optional `message`. | Display an error message to the user via a toast or similar. |
| `PaymentCompleted` | The user completed the Payment and Evervault has provided encrypted payment details back to you. Carries a `response` of type `NetworkTokenResponse` or `CardResponse`. | Display a success screen or receipt and trigger your server side flow for payment processing with one of your PSPs. |

### Check Google Pay is available on the device

Now that you have created the view model, you need to check that Google Pay is supported and that a payment can be made. If this method fails and Google Pay is not supported then `PaymentState.Unavailable` will be emitted.

```kotlin
viewModel.start()
```

This should be called once (e.g. in a `LaunchEffect(Unit) { ... }`)

This API checks the following minimum requirements to finish a transaction using the Google Pay API:

- Device is running on a supported Android system version and also has a supported version of Google Play services installed.
- Google Pay API has launched in the user's country.
- User either has or can add a card in flow according to the specifications given for the `Config` passed during initialisation of the `EvervaultPaymentViewModel`.

### Create a transaction

Next, you will need to create a transaction to describe the payment you want to process. You will need to provide the amount, currency, country, and merchant details for the transaction.

#### Browser

```javascript
const transaction = evervault.transactions.create({
  amount: 1000,
  currency: "USD",
  country: "US",
  merchantId: "merchant_8f3dc605aa5d",
  lineItems: [
    {
      label: "Example Item",
      amount: 1000,
    },
  ],
});
```

### Categorize line items

Set `category` on a line item to control how it appears on the sheet. Possible values are `line_item`, `subtotal`, `tax`, `discount`, and `shipping_option`. Defaults to `line_item` when omitted.

```javascript
const transaction = evervault.transactions.create({
  amount: 1000,
  currency: "USD",
  country: "US",
  merchantId: "merchant_8f3dc605aa5d",
  lineItems: [
    { label: "Product", amount: 800, category: "subtotal" },
    { label: "Sales Tax", amount: 200, category: "tax" },
  ],
});
```

#### Android

```kotlin
val transaction = Transaction(
  country = "IE",
  currency = "EUR",
  total = Amount("54.99"),
  lineItems = arrayOf(
    LineItem("Men's Shirt", Amount("50.00")),
    LineItem("Socks", Amount("04.99")),
  )
)
```

#### Browser

### Mount a Google Pay component

Now that you have created a transaction, you can create and mount the Google Pay component to display the Google Pay button to your users. The Google Pay component takes the transaction you created as a first argument and an options object with a `process` function that will be called with the encrypted payment method when the user completes the payment.

```javascript
const google = evervault.ui.googlePay(transaction, {
  process: async (paymentMethod) => {
    console.log(paymentMethod.card?.number);
    // ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$
  },
});

google.on("cancel", () => {
  console.log("Google Pay canceled");
});

google.on("success", () => {
  console.log("Google Pay success");
});

// Mount the Google Pay component to a container element
google.mount("#google-pay");
```

#### Android

### Render the Pay Button

Now that you have created a transaction and checked that Google Pay is supported, you can create and display the Google Pay button to your users by using the `EvervaultPaymentButton` composable.

```kotlin
EvervaultPaymentButton(
  modifier = Modifier
    .fillMaxWidth(),
  transaction,
  model,
)
```

### Process the payment

#### Browser

The `process` function is an asynchronous function that is called when the user authorizes the payment. Typically you will want to forward the encrypted payment method to your backend in order to process the payment. You can use [Relay](/relay) to forward the encrypted payment method to any third party payment processor.

```javascript
const google = evervault.ui.googlePay(transaction, {
  process: async (paymentMethod) => {
    await fetch("your-api.com/payments", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(paymentMethod),
    });
  },
});
```

Google Pay can return either a `networkToken` or a `card` object. Typically this depends on whether the transaction was initiated and authenticated via biometrics on a mobile device, or via a web browser on a desktop device.

Optional `card.paymentMethodType` is one of `credit`, `debit`, `prepaid`, or `store` when Google Pay supplies [`cardFundingSource`](https://developers.google.com/pay/api/web/reference/object#CardInfo) for the selected card. Values are normalized to lowercase. If the funding source is unknown or not returned, the field is omitted (there is no `"unknown"` sentinel). Like Apple Pay, this wallet-provided value can be more reliable than BIN-derived `funding` for dual-network cards.

`card.brand`, `funding`, `segment`, `country`, `currency`, and `issuer` are also optional. Each is included only when Evervault's BIN lookup can supply it, and is omitted (not sent as `null`) when unavailable.

Network tokens offer inherent security due to their device-bound nature. However, responses containing only card details carry a higher risk and require additional authentication steps. We recommend leveraging our [3D Secure](/cards/3d-secure) API to perform this necessary authentication for card-based responses.

#### Android

When the user completes the payment, cancels, or otherwise exits the Google Pay sheet, a callback is delivered to `onActivityResult()`. In the event of a successful payment, the Google Pay Payment token needs to be decrypted in order to be passed on to your PSP for processing. Call the `handlePaymentDataIntent()` method on the `viewModel` to handle this.

```kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  viewModel.handlePaymentDataIntent(requestCode, resultCode, data)
}
```

After `handlePaymentDataIntent()` is called, the `EvervaultPaymentViewModel` handles decryption of the Google Pay token and encrypts any sensitive PCI data for you. It emits `PaymentState.PaymentCompleted(response)` with the encrypted payload, or `PaymentState.Error` if an error occurred.

If the payment is handled successfully, the Evervault encrypted payment method is available in `PaymentState.PaymentCompleted(response)`. The `response` is a JSON object containing the payment method details encrypted with the Evervault public key. You can send this encrypted payment method to your server and use Evervault [Relay](/relay) to decrypt the payment details when you send them to your PSP.

Google Pay can return a `NetworkTokenResponse` or a `CardResponse` object, typically depending on whether the supported method was `PAN_ONLY` or `CRYPTOGRAM_3DS` and whether or not the network supports that method.

A `NetworkTokenResponse` object contains the following fields:

```json
{
  "token": {
    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
    "expiry": {
      "month": 12,
      "year": 31
    },
    "tokenServiceProvider": "Google"
  },
  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",
  "eci": "5",
  "card": {
    "brand": "visa",
    "lastFour": "1234",
    "displayName": "visa 1234",
    "funding": "debit",
    "segment": "consumer",
    "country": "ie",
    "currency": "eur",
    "issuer": "Revolut Bank Uab"
  },
  "messageId": "AB2Ejtf45mS02sSec_rbBgPtTCBvH1p-4Y-Ga_8_Pi9ZDgCiReH...",
  "messageExpiration": "1766011111111"
}
```

A `CardResponse` object contains the following fields:

```json
{
  "card": {
    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
    "expiry": {
      "month": 12,
      "year": 31
    },
    "lastFour": "1234",
    "displayName": "visa 1234",
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "ie",
    "currency": "eur",
    "issuer": "Revolut Bank Uab"
  },
  "messageId": "AB2Ejtf45mS02sSec_rbBgPtTCBvH1p-4Y-Ga_8_Pi9ZDgCiReH...",
  "messageExpiration": "1766011111111"
}
```

If available, both objects also contain a `billingAddress`, which sits at the root and contains the following fields:

```json
{
  "name": "John Smith",
  "postalCode": "94043",
  "countryCode": "US",
  "phoneNumber": "561-555-7689",
  "address1": "1600 Amphitheatre Parkway",
  "address2": "",
  "address3": "",
  "locality": "Mountain View",
  "administrativeArea": "CA",
  "sortingCode": ""
}
```

Google Pay responses containing a `networkToken` offer inherent security due to their device-bound nature. However, responses containing only `card` details carry a higher risk and require additional authentication steps. We recommend leveraging our [3DS API](/cards/3d-secure) to perform this necessary authentication for card-based responses.

### Complete example

Below is a full example of Evervault Google Pay in action:

```kotlin
class MainActivity : AppCompatActivity() {

  private val model: EvervaultPayViewModel by viewModels {
    EvervaultPayViewModelFactory(
      application,
      Config(
        appId = "YOUR_EVERVAUL_APP_ID",
        merchantId = "YOUR_EVERVAULT_MERCHANT_ID",
      )
    )
  }

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val transaction = Transaction(
      country = "GB",
      currency = "GBP",
      total = Amount("54.99"), // The total of the below line items
      lineItems = arrayOf(
        LineItem("Men's Tech Shell Full Zip", Amount("50.00")),
        LineItem("Something small", Amount("04.99")),
      )
    )

    setContent {
      LaunchedEffect(Unit) {
        model.start()
      }

      // Initialise your payment UI state
      val payState: PaymentState by
        model.paymentState.collectAsState()

      // Handle state updates
      when (val state = payState) {
        is PaymentState.Unavailable -> {
          // Google Pay is unavailable
          Text("Google Pay is unavailable.")
        }
        is PaymentState.Available -> {
          // Google Pay is available so render the Button
          EvervaultPaymentButton(
            modifier = Modifier
              .fillMaxWidth(),
            transaction,
            model,
          )
        }
        is PaymentState.PaymentCompleted -> {
          // Type is either `NetworkTokenResponse` or `CardResponse`
          when (val token = state.response) {
            is NetworkTokenResponse -> {
              Text("Network Token Cryptogram: ${token.cryptogram}")
            }
            is CardResponse -> {
              Text("Encrypted Card Number: ${token.card.number}")
            }
          }
        }
        is PaymentState.Error -> {
          // An error occurred in the Google Pay payment sheeet
          Text("Error: ${state.message}")
        }
        is PaymentState.NotStarted -> {
          // `viewModel.start()` has not been called yet
          CircularProgressIndicator()
        }
      }
    }
  }

  override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // Allow Evervault to handle the result of the payment request
    model.handlePaymentDataIntent(requestCode, resultCode, data)
  }
}
```

#### Browser

## Error handling

### Errors while processing the payment

The process function also accepts a second argument which is an object of helper methods. This object includes a `fail` function that can be called with an error message to display an error to the user in the event of an error during payment processing.

```javascript
const google = evervault.ui.googlePay(transaction, {
  process: async (paymentMethod, { fail }) => {
    try {
      // ...
    } catch (error) {
      fail({
        message: "Cannot pay with payment credentials",
      });
    }
  },
});
```

### Errors while rendering the component

In the rare event that the Google Pay component fails to render, you can handle the error by listening to the `error` event.

```javascript
const google = evervault.ui.googlePay(transaction, { ... })

google.on("error", (error) => {
  console.error("Google Pay error", error);
});
```

## Use Google Pay with your PSP

You can use Evervault's Google Pay integration with any PSP. This means you:

- Don't use your PSP's Google Pay integration.
- Preferably use network tokens with your PSP's APIs.

When Google Pay returns a network token, use it for all payments, retries, etc. with your PSP. There's no additional configuration (e.g., certificates) with your PSP or Google needed. Most PSPs have network token APIs and parameters for passing network token data. Like other 3rd party API calls, use [Relay](/relay) to decrypt network token data and send it to your PSP.

## Customization

#### Browser

Google Pay allows you to customize the appearance of the payment button with various predefined styles. These can be passed as additional options when initializing the Google Pay component. You can see all of the available options in the [JS SDK documentation](/sdks/javascript#google-pay).

```javascript
const google = evervault.ui.googlePay(transaction, {
  color: "white",
  type: "checkout",
  locale: "fr",
  borderRadius: 5,
  size: {
    width: "200px",
    height: "40px",
  },
  process: async (paymentMethod) => {
    // ...
  },
});
```

#### Android

Google Pay allows you to customize the appearance of the payment button with various predefined styles. These can be passed as additional options when initializing the `EvervaultPaymentButton`. Below is an example:

```kotlin
EvervaultPaymentButton(
  modifier = Modifier
    .fillMaxWidth(),
  transaction,
  model,
  type = ButtonType.Donate,
  theme = ButtonTheme.Light,
)
```

The default theme is `Dark` and the default type is `Pay`.

## Configuration

#### Browser

Google Pay allows you to specify the authorization methods and card networks that are supported by your merchant. This can be done by passing the `allowedAuthMethods` and `allowedCardNetworks` options when initializing the Google Pay component. You can see the available options in the [JS SDK](/sdks/javascript#google-pay).

```javascript
const google = evervault.ui.googlePay(transaction, {
  allowedAuthMethods: ["PAN_ONLY"],
  allowedCardNetworks: ["VISA", "MASTERCARD"],
  process: async (paymentMethod) => {
    // ...
  },
});
```

### Checkout button and card restrictions

You can control the sheet's checkout button, attach a transaction ID for fraud correlation, mark the total as an estimate, restrict prepaid or credit cards, and identify your integration to Google. You can see the available options in the [JS SDK](/sdks/javascript#uigooglepay).

```javascript
const google = evervault.ui.googlePay(transaction, {
  // Show "Pay" instead of "Continue". Requires totalPriceStatus "FINAL" (the default).
  checkoutOption: "COMPLETE_IMMEDIATE_PURCHASE",
  transactionId: "order_8f3dc605aa5d",
  totalPriceStatus: "ESTIMATED",
  allowPrepaidCards: false,
  allowCreditCards: true,
  softwareInfo: { id: "your-integration-id", version: "1.0.0" },
  process: async (paymentMethod) => {
    // ...
  },
});
```

### Assurance details

Set `assuranceDetailsRequired: true` to ask Google Pay to perform cardholder ID&V (identification and verification) or possession checks on the selected payment method. When Google Pay returns a result, it's surfaced as `assuranceDetails` on the payload passed to `process`. The result is in cleartext and isn't processed by Evervault's backend. If Google Pay doesn't return a result, `assuranceDetails` is omitted.

```javascript
const google = evervault.ui.googlePay(transaction, {
  assuranceDetailsRequired: true,
  process: async (paymentMethod) => {
    console.log(paymentMethod.assuranceDetails);
    // { accountVerified: true, cardHolderAuthenticated: true }
  },
});
```

### Require an existing payment method

Set `existingPaymentMethodRequired: true` to only show the button when the customer has a saved payment method in their Google account. This check happens up front, not when the button is clicked. It only controls whether the button appears and won't prompt the customer to add a card.

```javascript
const google = evervault.ui.googlePay(transaction, {
  existingPaymentMethodRequired: true,
  process: async (paymentMethod) => {
    // ...
  },
});
```

### Prefetch payment data

Set `prefetchPaymentData: true` to prepare the payment sheet before the customer clicks the button. The sheet opens faster, but every render costs a network request, even if the customer never clicks. It has no effect on the `process` result.

```javascript
const google = evervault.ui.googlePay(transaction, {
  prefetchPaymentData: true,
  process: async (paymentMethod) => {
    // ...
  },
});
```

#### Android

The `Config` object initialises your `EvervaultPaymentViewModel` with everything it needs to handle the interactions with the Google Pay API. At a minimum you're required to provide your Evervault App ID and Evervault Merchant ID. There are other options to allow you to customise how the Google Pay payment sheet functions. Below is an example with all the possible options:

```kotlin
Config(
  appId = "app_1234567890",
  merchantId = "merchant_1234567890",
  supportedNetworks = listOf(
    CardNetwork.VISA,
    CardNetwork.MASTERCARD,
    // AMEX, DISCOVER, JCB also supported
  ),
  supportedMethods = listOf(
    CardAuthMethod.PAN_ONLY,
    CardAuthMethod.CRYPTOGRAM_3DS
  )
)
```

The Google Pay environment (test vs. production) isn't set on `Config`. The SDK selects it automatically based on whether your Evervault app is configured as sandbox or live.

For the `supportedNetworks` option, all of the networks listed above, including those in the comment are enabled. If you wish to only support a select few of the networks, please override the list as shown above.

For the `supportedMethods`, please refer to Google's documentation on `PAN_ONLY` vs `CRYPTOGRAM_3DS`. Depending on the values you use here, you may encounter errors when initialising the component, for example, `JCB` and `DISCOVER` don't support `CRYPTOGRAM_3DS` because they don't support DPANs.

## 3D Secure

Google Pay supports encrypted and non-encrypted payment methods. Encrypted payment methods are preferred as they provide enhanced security and reduced fraud. Non-encrypted payment methods are also supported, and when used can subsequently be submitted for authentication via our 3D Secure API. See our [3D Secure guide](/cards/3d-secure) for more information. You can directly pass the encrypted card number string from the returned payment method to our 3DS API to perform an authentication.

## Content Security Policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.

```text
script-src https://js.evervault.com;
connect-src https://keys.evervault.com https://api.evervault.com;
frame-src https://ui-components.evervault.com;
```

- [3D Secure](/cards/3d-secure): Learn how 3D Secure works and how it can be used to enhance your payment security.
- [Apple Pay](/cards/apple-pay): Learn how to integrate Apple Pay with Evervault.


---

# Insights and Verification

_Use Evervault's Insights and Verification APIs to retrieve rich metadata for card numbers._

![An illustration of a BIN being searched in a database]()

The Evervault API provides several endpoints that can be used to retrieve additional information for cards and BIN ranges. This can be used for tasks such as fraud detection and payment routing.

- Use the [Card Insights](#card-insights) endpoint to perform cardholder verification checks and enrichment.
- Use the [BIN Lookup](#bin-lookup) endpoint to retrieve metadata for a BIN range.
- Use the [PAR Lookup](#par-lookup) endpoint to retrieve the Payment Account Reference (PAR) for a card number or network token.

> To get access to Insights and Verification, [register your
>   interest](https://tally.so/r/dWJ0zD?utm_medium=docs&utm_source=evervault&utm_campaign=card_insights_and_verification_launch).

## Card Insights

The [Card Insights API](/api#createCardInsight) provides a powerful, real-time interface for card and cardholder verification checks and enrichment. It allows you to run:

- Address verification (AVS)
- Cardholder name verification (ANI)
- CVV validation
- Email and phone verification

You can also retrieve BIN information, the Payment Account Reference (PAR), and the push and pull transaction capabilities for disbursements and collections. Checks can run against either a card or a network token. By unifying these inputs, the API provides real-time assessments of card and cardholder authenticity alongside rich card metadata—enabling precise validation and smarter routing, handling, and fraud prevention.

### Creating a card insight

You can run Card Insights against either a card (PAN) or a network token. Provide exactly one of `card` or `networkToken` per request.

Card Insights is extensible - you choose the insights you need per request. Every response includes BIN data by default. You can add any of the following extensions:

1. **Address Verification (AVS)** – Run AVS to verify postal code and street-level elements (line1, line2, city, state, country) against issuer records.
2. **Name Verification** – Run ANI to verify the provided name (first, last, middle, suffix, and owner type) against issuer records.
3. **Transaction Capabilities** – Determine push and pull transaction eligibility, network, regulatory status, and expected funds-availability windows.
4. **CVV Validation** – Validate the CVV against issuer records. Not available for network tokens.
5. **Email Verification** – Verify the provided email address against issuer records.
6. **Phone Verification** – Verify the provided phone number against issuer records.
7. **Payment Account Reference (PAR)** – Retrieve the Payment Account Reference for the card.

This example requests all possible extensions and includes both required and optional fields. The example response includes all possible fields.

```javascript
const response = await fetch("https://api.evervault.com/insights/cards", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    card: {
      number: "4111111111111111",
      cvv: "123",
      expiry: {
        month: "12",
        year: "29",
      },
    },
    extensions: [
      "capabilities",
      "address",
      "cardholder",
      "cvv",
      "email",
      "phone",
      "paymentAccountReference",
    ],
    address: {
      postalCode: "10001",
      line1: "Main Street",
      line2: "Anytown",
      city: "New York",
      state: "NY",
      country: "us",
    },
    cardholder: {
      firstName: "John",
      lastName: "Doe",
      middleName: "Michael",
      suffix: "Jr",
      ownerType: "primary",
    },
    email: "john.doe@example.com",
    phone: "0016505551234",
  }),
});
```

Alternatively, provide a `networkToken` in place of `card`:

```javascript
body: JSON.stringify({
  networkToken: {
    number: "4111111111111111",
    cryptogram: "AgAAAAAABk4DdZzBRckAAAAA",
    expiry: {
      month: "12",
      year: "29",
    },
    // transactionIdentifier, brand, and funding are required for Amex and Discover
    transactionIdentifier: "1234567890",
    brand: "visa",
    funding: "credit",
  },
  extensions: ["capabilities", "address", "paymentAccountReference"],
  address: {
    postalCode: "10001",
    country: "us",
  },
});
```

### Extensions and required fields

| Extension | Required Fields |
| --- | --- |
| `capabilities` | `card.number` |
| `address` | `card.number`, `card.expiry`, `address.postalCode` |
| `cardholder` | `card.number`, `card.expiry`, `cardholder.firstName`, `cardholder.lastName` |
| `cvv` | `card.number`, `card.expiry`, `card.cvv` |
| `email` | `card.number`, `email` |
| `phone` | `card.number`, `phone` |
| `paymentAccountReference` | `card.number` |

> The `cvv` extension isn't available for network token lookups. For all other
>   extensions, replace the `card.*` requirements above with the equivalent
>   `networkToken.*` fields.

### Request validation rules

There are some general rules that need to be followed for all strings fields. Failure to follow these will result in an error.

- All string fields must only consist of ASCII characters.
- Consecutive periods (`.`) will result in an error.

The following characters are restricted for all string fields:

| Forbidden Character | Description |
| --- | --- |
| `\` | Backslash |
| `^` | Caret |
| `,` | Comma |
| `"` | Double Quotes |
| `()` | Parentheses |
| `\|` | Pipe |
| `;` | Semi-Colon |
| `~` | Tilde |

#### Card fields

- The `number` must be a valid card number (either in plaintext for as an Evervault encrypted string).
- The `cvv` must be a valid CVV for the given card brand.
- The `month` and `year` for the `expiry` must be 2 digit strings.

#### Transaction fields

- The `amount` must be a number.
- The `currency` must be a valid ISO-4217 three digit currency code.

#### Cardholder fields

- `firstName` and `lastName` are required when the `cardholder` extension is requested.
- `middleName` and `suffix` are optional and refine the name match.
- `ownerType` is optional and indicates whether the cardholder is the `primary` or `secondary` account owner.

For name fields there are additional character restrictions. These are outlined below. Failure to remove these will result in an error.

| Forbidden Name Field Character | Description |
| --- | --- |
| `&` | Ampersand |
| `$` | Dollar Sign |
| `=` | Equal Sign |
| `!` | Exclamation Mark |
| `/` | Forward Slash |
| `#` | Hash / Pound |
| `%` | Percent |
| `+` | Plus |
| `?` | Question mark |
| `_` | Underscore |

#### Email and phone fields

> Email and phone verification aren't widely supported by issuers, so coverage is limited.

- The `email` must be a valid email address. Required when the `email` extension is requested.
- The `phone` must be in IDD-prefixed E.164 format: E.164 international format with the `00` IDD prefix substituted for `+` (for example `0016505551234` for a US number). Required when the `phone` extension is requested.

#### Network token fields

- The `number` must be a valid network token number (either in plaintext or as an Evervault encrypted string).
- The `cryptogram` must be a valid cryptogram (either in plaintext or as an Evervault encrypted string).
- The `month` and `year` for the `expiry` must be 2 digit strings.
- `transactionIdentifier`, `brand`, and `funding` are required for Amex and Discover network tokens.

#### Address fields

- If no `country` is provided, then it defaults to `us`.
- If the country is `us` (United States) then the `postalCode` must be a 5 or 9 digit string. The hyphen must be excluded.
- If the country is `ca` (Canada) then the `postalCode` must follow the Canadian postal code format (ANA NAN) e.g. `A1A 1A1`. The space character must be included.
- The `state` must be a valid ISO-3166 subdivision code. e.g `ny` for New York.
- The `country` must be a valid ISO-3166 two character country code.

## BIN Lookup

The [BIN Lookup API](/api#createBinLookup) allows you to retrieve BIN data for a card number or BIN range. You can pass a plaintext card number, an encrypted card number, or the first 6-10 digits of a card number. If the number matches a range of BINs, the response returns metadata that is common to all the BINs in that range. The API key and app ID are required to authenticate the request, and the API key needs the `binLookup:create` permission.

```javascript
const response = await fetch("https://api.evervault.com/payments/bin-lookups", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    number: "4242424242424242",
  }),
});
```

The response includes the BIN metadata, such as the card brand, the funding type, the country, and other relevant details.

```json
{
  "id": "bin_lookup_1234567890",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "type": "card",
  "productName": "Visa Wizard",
  "fastFunds": {
    "domestic": true,
    "crossBorder": true
  },
  "matchPrecision": 8,
  "threeDS": {
    "supportedVersions": {
      "accessControlServer": ["2.2.0"],
      "directoryServer": ["2.2.0", "2.3.1"]
    },
    "acsInfoIndicators": [
      {
        "code": "acs-auth-available",
        "indicator": "01",
        "description": "Authentication Available at ACS"
      }
    ]
  },
  "createdAt": 169297262323
}
```

## PAR Lookup

The [PAR Lookup API](/api#createParLookup) returns the Payment Account Reference for a card number or network token. A PAR is a stable identifier the card network assigns to a card. Unlike a card number, it stays constant when a card is reissued, renewed, or replaced, and every network token derived from the card resolves to the same PAR.

This makes PAR useful for identifying when a network token and a physical card are the same underlying payment account. You can use the PAR to track a card across reissues, and linking its activity to a single cardholder for fraud detection or lifetime-value analysis.

> **Card and account identifiers**
>
> A PAR identifies a card and its tokens over time, not the underlying bank account or the cardholder. Distinct cards on the same account aren't guaranteed to share a PAR.

To look up a PAR, send a plaintext or Evervault-encrypted card number or network token to the PAR Lookup endpoint. The API key and app ID are required to authenticate the request, and the API key needs the `parLookup:create` permission.

```javascript
const response = await fetch("https://api.evervault.com/payments/par-lookups", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
  },
  body: JSON.stringify({
    number: "5204248250001003",
  }),
});
```

The response includes the resolved PAR, along with an identifier for the lookup.

```json
{
  "id": "par_lookup_1234567890",
  "paymentAccountReference": "5001BN2CUZCOY2H2IJILTJJZWTEPW"
}
```

> **Sandbox**
>
> In sandbox, the PAR Lookup API returns a consistent value for the `paymentAccountReference` regardless of the inputs to that API.

- [Card Collection](/cards/card-collection): Learn how to use Card Collection to collect cardholder data.
- [Network Tokens](/cards/network-tokens): Learn how to use Network Tokens to enhance your payment security.


---

# Intelligent Retries

_Learn about how to enable and use intelligent retries._

> **Beta**
>
> Intelligent Retries is in beta, limited to Mastercard, and is subject to
>   change. To get access to our beta product, [register your
>   interest](https://tally.so/r/b5Xkeg?utm_medium=docs&utm_source=evervault&utm_campaign=beta_launch_intelligent_retries).

​Intelligent Retries help recover lost revenue from declined transactions by sending you notifications informing you when a transaction has succeeded on that card. The card networks track activity, such as successful approvals on the same card at other merchants for similar amounts or greater, to identify optimal retry windows.

Declined transactions impact all businesses to some degree and are often caused by temporary issues, such as insufficient funds. They can negatively impact revenue, support costs, customer loyalty, and brand trust. To prevent these issues, most solutions retry the payment based on some kind of static schedule, without any signal that the retry will succeed. Intelligent Retries fills this gap. It uses card network intelligence to determine when a retry is more likely to succeed, which can:

- Increase approval rates
- Maximize revenue recovery
- Mitigate excessive retry fines
- Prevent service disruptions
## How it works

There are 3 easy steps to start recovering revenue:

1. **Configuration**: Intelligent Retries is configured per merchant. To enroll your merchant, use the [Intelligent Retries onboarding API]. Then, configure a webhook endpoint in the dashboard and subscribe to the `payments.intelligent-retries.signal` event.

2. **Network Monitoring**: After enrollment, Mastercard detects and monitors activity related to declined transactions on that MID to identify the optimal moment for a retry.

3. **Intelligent Retry signals**: ​When the network identifies a transaction has succeeded on the same card, Evervault sends an event to your webhook endpoint so you can retry the payment.

### Intelligent Retries Onboarding API

> **Notice**
>
> Intelligent retries is currently restricted to US registered merchants only. Onboarding a non-US registered MID may fail.

You need to onboard your Merchant ID (MID) for Mastercard using the [Intelligent Retries Onboarding API](). Mastercard monitor this MID for declined transactions as outlined in the next section.

If you don't know your Merchant ID, you can supply a network transaction ID from one of your transactions. Evervault works to locate the MID associated with the transaction and onboard it with Mastercard for Intelligent Retries.

Locating a transaction ID is typically straight forward. Refer to the [Locating a transaction ID](/cards/intelligent-retries#locating-a-transaction-id) section.

From the time of onboarding, it can take up to 3 weeks before the MID is tracked by Mastercard and you start receiving notifications.

```bash
curl 'https://api.evervault.com/payments/intelligent-retries/onboarding` \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "networkTransactionId": "MCC123456789012345",
  "merchant": "merchant_123456789098",
}'
```

### Mastercard monitoring

Mastercard scans its own network for failed transactions associated with your enrolled MID. If a monitored MID receives a 51 or 61 decline code, Mastercard monitors the payment instrument involved in the declined transaction.

> Mastercard monitoring is triggered exclusively for the following response codes:
>   - Decline Code 51: Insufficient Funds
>   - Decline Code 61: Exceeds Withdrawal Amount Limit

Mastercard monitors linked payment credentials across its global network. They track activity such as successful approvals on the same card at other merchants for similar amounts or greater, to identify optimal retry windows.

#### Duplicate decline prevention

When a repeat decline occurs for the same PAN, MID, and amount, the system doesn't initiate a new monitoring session. It also avoids new sessions if a decline occurs within an existing monitoring period. This avoids redundant tracking, minimizes system load, and reduces duplicate notifications.

#### Self-retry detection (auto-termination)

If a successful authorization is observed independently (e.g., the customer pays manually), the active monitoring session is canceled.

## The Intelligent Retry signal event

Here is an example of a retry signal webhook event:

```json
{
	"id": "webhook_event_0aa6ff0fee57",
	"type": "payments.intelligent-retries.signal",
	"data": {
		"network": "mastercard",
		"signal": "retry-now",
		"amount": 12345,
		"networkTransactionId": "W3T51Z",
		"timestamp": "2026-02-04T13:53:47.314Z",
		"currency": {
			"alphaCode": "usd",
			"numericCode": 840,
		},
		"metadata": {
			"notificationId": "M8OjZWZgRi0uZLa6PdB0CIavqctFyipx",
			"acquirerMerchantId": "12354689987",
			"cardBin": "5123456",
			"cardLastFour": "9000",
			"tokenBin": "5234567",
			"tokenLastFour": "1234",
			"maskedPan": "512345XXXXXX9000"
		}
	}
}
```

There are two sections to a retry signal webhook event:

1. Signal status and transaction information.

2. Card network specific transaction metadata.

### Signal status and transaction information

| Field | Description |
| --- | --- |
| `network` | The card network where the signal originated from. |
| `signal` | The status of the signal. These are outlined in more detail below. |
| `amount` | The amount of the declined transaction in minor currency units. |
| `networkTransactionId` | The card network-specific transaction ID. |
| `timestamp` | The time the initial transaction failed. |
| `currency` | An object containing the ISO 4217 alphabetic currency code, and the ISO 4217 numeric currency code. |

### Card network metadata

#### Mastercard metadata

| Field | Description |
| --- | --- |
| `notificationId` | Mastercard’s unique reference for this specific alert. |
| `acquirerMerchantId` | The merchant ID enrolled with Mastercard for Intelligent Retries. |
| `cardBin` | The first 6-8 digits of the card number used in the declined transaction. |
| `cardLastFour` | The last four digits of the card used in the declined transaction. |
| `tokenBin` | The first 6-8 digits of the network token number used in the declined transaction. |
| `tokenLastFour` | The last four digits of the network token number used in the declined transaction. |
| `maskedPan` | The masked PAN used in the declined transaction. |

> Either `cardBin` and `cardLastFour`, or `tokenBin` and `tokenLastFour` will be present depending on whether a PAN or network token was used in the declined transaction.

## Signal statuses

| Signal | Description | Availability |
| --- | --- | --- |
| `retry-now` | Issued when conditions suggest that funds are available and a previously declined transaction can be retried. | Available |
| `monitoring-started` | Indicates the network started monitoring activity for the declined transaction. No retry is advised. | Coming soon |
| `monitoring-expired` | Monitoring period (30 days) ended without a successful retry. No further alerts will be sent. | Coming soon |
| `monitoring-cancelled` | Monitoring has ended because a successful retry was independently observed. No further alerts will be sent. | Coming soon |

> Only `retry-now` is currently available and requires merchant action. Monitoring lifecycle statuses will be informational when available and may be used for reporting, logging, or transparency purposes.

## Matching signals to failed transactions

To retry the failed transaction after a webhook signal, you can match on the following set of identifiers from your PSP:

- Transaction timestamp
- Network Transaction ID
- Last 4
- BIN
- Masked PAN

## Locating a transaction ID

If you use a PSP they will typically provide this value to you when you inspect a transaction on their platform or via one of their APIs. We have outlined how to do this for some common PSPs

### Finding a transaction ID with Stripe

- In the Stripe dashboard, navigate to Transactions and locate a Mastercard transaction.
- Copy and search for the Payment and open it in the Workbench.
- Locate the Charge associated with the Payment.
- In the Workbench Inspector tab, you can find the `network_transaction_id` located under `payment_method_details`.

### Finding a transaction ID with Adyen

With Adyen you can use the [Transfers API](https://docs.adyen.com/api-explorer/transfers/4/get/transfers/(id)) to locate a payment transfer for Mastercard. In the response, locate the event containing a `transactionId` field. This is the network transaction ID.


---

# Pre-Chargeback Alerts

_Learn about how to enable and use pre-chargeback alerts._

Pre-chargeback alerts notify you when a cardholder raises a dispute with their issuer, giving you a window to resolve it before it escalates to a formal chargeback. This helps keep your chargeback ratio low and avoids potential issues with card networks like Visa and Mastercard.

> **Beta**
>
> Pre-Chargeback Alerts are in beta and are subject to change. To get access
>   to our beta product, [register your
>   interest](https://tally.so/r/J9oEpX?utm_medium=docs&utm_source=evervault&utm_campaign=beta_launch_pre-chargeback_alerts).

## Alert Types

There are two alert networks, each associated with different card schemes:

- **Verifi RDR (Rapid Dispute Resolution)** — primarily covers Visa transactions. When an alert arrives, Evervault automatically processes a refund on your behalf before a chargeback is filed. No manual action is required from you. You can optionally configure an [amount rule](#verifi-rdr-refund-rules) per merchant to control which Verifi alerts are refunded.
- **Ethoca Alerts** — covers Mastercard, and some American Express and Discover transactions. Unlike Verifi RDR, Ethoca Alerts require you to take an action — such as issuing a refund through your PSP — and then update the alert via the API.

You can enrol a merchant in one or both networks at the same time.

## How it works

Pre-chargeback alerts are configured per merchant through the [Merchants API](/api#createMerchant). You enable them by including a `preChargebackAlerts` object when creating or updating a merchant. When Evervault receives an alert from one of the networks, it creates an alert record that you can retrieve and respond to via the API. You can also subscribe to [webhooks](#webhooks) to receive alert and enrolment status notifications in real time.

## API key grants

Make sure to authenticate with an API key that has the grant for the operation you're calling. An API key with `preChargebackAlert:*` can call all of them, including the rule operations. Enrolling a merchant goes through the [Merchants API](/api#createMerchant) and needs `preChargebackAlert:create` alongside the merchant grant — `merchant:create` to enable alerts on a new merchant, `merchant:update` on an existing one.

Paths below are relative to `/payments/pre-chargeback-alerts`.

| Endpoint | Grant |
| --- | --- |
| `GET /alerts`<br />`GET /alerts/{alert_id}` | `preChargebackAlert:read` |
| `PATCH /alerts/{alert_id}` | `preChargebackAlert:respond` |
| `POST /simulate-alert` | `preChargebackAlert:simulate` |
| `POST /merchants/{merchant_id}/rules` | `preChargebackAlert:ruleCreate` |
| `GET /merchants/{merchant_id}/rules`<br />`GET /merchants/{merchant_id}/rules/{rule_id}` | `preChargebackAlert:ruleRead` |
| `PATCH /merchants/{merchant_id}/rules/{rule_id}` | `preChargebackAlert:ruleUpdate` |
| `DELETE /merchants/{merchant_id}/rules/{rule_id}` | `preChargebackAlert:ruleDelete` |

## Enable alerts for a merchant

You enable pre-chargeback alerts by including a `preChargebackAlerts` object when creating or updating a merchant. At least one of `ethocaAlert` or `verifiRdr` must be provided.

### For a new merchant

Include `preChargebackAlerts` in the body of `POST /payments/merchants`:

```bash
curl -X POST 'https://api.evervault.com/payments/merchants' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "name": "Example Store",
    "website": "https://example.com",
    "categoryCode": "5411",
    "business": {
      "legalName": "Example Store Ltd",
      "address": {
        "line1": "123 Main Street",
        "city": "Dublin",
        "postalCode": "D01 AB12",
        "country": "IE"
      }
    },
    "preChargebackAlerts": {
      "ethocaAlert": {
        "descriptors": [
          { "descriptor": "EXAMPLE STORE", "matchType": "STARTS_WITH" }
        ]
      },
      "verifiRdr": {
        "bin": "424242",
        "caid": "123456789012345"
      }
    }
  }'
```

#### Ethoca

Each descriptor entry matches the statement descriptor that appears on the cardholder's statement. The `matchType` can be `STARTS_WITH` or `EXACT_MATCH`. Each `descriptor` must be 1–100 printable ASCII characters, and you can supply at most 50 descriptors per enrolment. At least one descriptor is required when enrolling in Ethoca Alerts. An empty `descriptors` array is rejected with a `400` error. Descriptors determine which transactions trigger alerts, and omitting `ethocaAlert` entirely enrols the merchant in Verifi RDR only (if configured).

Ethoca can only match disputed transactions by descriptor, so make sure your descriptors are specific. Vague descriptors produce excess matches that may not belong to the merchant. If another merchant uses the same descriptor and one of their transactions is disputed, the alert is delivered to you and billed. If that happens, contact us to request a refund. Collisions should be rare when descriptors are specific.

For example, a short brand name such as `APPLE` is likely to overlap with other merchants. To make this more distinctive, you might add a domain (`APPLE.COM`) or a more complete trading name (`APPLE SERVICES`).

#### Verifi RDR

To match transactions, you must provide a `bin` and a `caid` (card acceptor ID), or a list of `arns` (acquirer reference numbers). You have to provide `bin` and `caid` together. The `bin` must be 6 digits, and the `caid` has to be exactly 15 alphanumeric characters. Each `arn` must be exactly 23 digits, and you can up to 50 ARNs.

### For an existing merchant

Use `PATCH /payments/merchants/{merchant_id}` and include a `preChargebackAlerts` object with at least one of `ethocaAlert` or `verifiRdr`. The `enabled` field is optional and defaults to `true`.

```bash
curl -X PATCH 'https://api.evervault.com/payments/merchants/{merchant_id}' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "preChargebackAlerts": {
      "ethocaAlert": {
        "descriptors": [
          { "descriptor": "EXAMPLE STORE", "matchType": "EXACT_MATCH" }
        ]
      }
    }
  }'
```

The merchant's `preChargebackAlerts` field in the response shows the enrolment status:

```json
{
  "id": "{merchant_id}",
  "name": "Example Store",
  ...
  "preChargebackAlerts": {
    "enrolments": [
      {
        "type": "ETHOCA_ALERT",
        "status": "PENDING",
        "ethocaAlert": {
          "descriptors": [
            { "descriptor": "EXAMPLE STORE", "matchType": "EXACT_MATCH", "status": "PENDING" }
          ]
        }
      }
    ]
  }
}
```

> It can take 2–10 days to start receiving alerts after enrolment. This is a
>   limitation of the Verifi RDR and Ethoca Alert networks. You can monitor
>   enrolment status by polling the merchant's `enrolments[].status` field, or by
>   subscribing to the
>   [`payments.pre-chargeback-enrolment-status.updated`](#enrolment-configuration-updated)
>   webhook event. For Ethoca, descriptors are validated asynchronously — if a
>   descriptor is too generic or is already in use across Ethoca's network, the
>   enrolment moves to `ACTION_REQUIRED` and our support team will reach out to
>   agree on an alternative. This typically takes 1–2 business days.

### Enrolment statuses

The `enrolments[].status` field on a merchant can be one of:

| Status | Description |
| --- | --- |
| `PENDING` | Enrolment has been submitted and is awaiting activation from the alert network. This typically takes 2–10 days. |
| `ACTIVE` | Enrolment is active and the merchant can receive alerts. |
| `ACTION_REQUIRED` | Enrolment needs attention — usually an Ethoca descriptor that is too generic or already in use. Our support team will reach out to agree on an alternative. |
| `CANCELLED` | Enrolment has been cancelled and the merchant will no longer receive alerts for this network. |

## Retrieve alerts

### List alerts

`GET /payments/pre-chargeback-alerts/alerts` returns a paginated list of alerts for your app.

Supported query parameters:

- `status` — filter by `ACTION_REQUIRED`, `RESOLVED`, or `INVALID`.
- `merchantId` — filter by Evervault merchant ID.
- `alertReceivedAtGte` — return alerts received on or after this ISO 8601 timestamp (inclusive).
- `alertReceivedAtLte` — return alerts received on or before this ISO 8601 timestamp (inclusive). Must be greater than or equal to `alertReceivedAtGte` when both are provided.
- `sort` — sort order: `-alertReceivedAt` (newest first, default), `alertReceivedAt` (oldest first), `-actionRequiredDeadline`, or `actionRequiredDeadline`. Alerts without an `actionRequiredDeadline` sort last when ascending (`actionRequiredDeadline`) and first when descending (`-actionRequiredDeadline`), as if their deadline were infinitely far in the future.
- `limit` — number of results per page, between 1 and 1000.
- `offset` — pagination offset.

Unknown query parameters are rejected with a `400`.

```bash
curl 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts?status=ACTION_REQUIRED&merchantId={merchant_id}' \
  -u '<app_id>:<api_key>'
```

The response is a paginated object with an `items` array and a `count`:

```json
{
  "items": [ ... ],
  "count": 1
}
```

### Get a single alert

```bash
curl 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts/{chargeback_alert_id}' \
  -u '<app_id>:<api_key>'
```

## Respond to an alert

### Verifi RDR

Verifi RDR alerts are resolved automatically. They arrive with a status of `RESOLVED` or `INVALID` and don't require any action from you. The `transactionRefundOutcome` field reflects the outcome.

If the merchant has [refund rules](#verifi-rdr-refund-rules) configured, Evervault evaluates the disputed amount against those rules before processing the refund. Alerts that do not match are not refunded and are not charged. Merchants without any rules continue to have all Verifi alerts refunded by default.

### Ethoca Alerts

> Refunding the customer alone is **not enough** to prevent a chargeback for
>   Ethoca alerts. You must also call the PATCH endpoint so that Ethoca is
>   notified and can stop the chargeback from proceeding. An unactioned alert
>   provides no protection — the chargeback will proceed regardless of whether you
>   issued a refund.

For Ethoca alerts in `ACTION_REQUIRED` status, take action with your PSP first — for example, issuing a refund. The `transactionStatementDescriptor` and `transactionAcquirerReferenceNumber` fields are useful to share with your PSP to identify the transaction.

Once you have taken action, update the alert via `PATCH /payments/pre-chargeback-alerts/alerts/{alert_id}`. Both fields are optional: `action` notifies Ethoca of the action you took on your PSP and is what prevents the chargeback from proceeding — omitting it means Ethoca is not notified. `note` is purely informational and is stored for your own records only; it is not sent to Ethoca. `note` may be up to 1000 characters and must not contain control characters.

Valid `action` values:

- `REFUND` — you have refunded the customer.
- `CANCEL` — you have cancelled or dismissed the alert.
- `REFUND_AND_CANCEL` — you have both refunded the customer and cancelled the subscription or order.
- `ACCEPT_DISPUTE` — you are accepting the chargeback (equivalent to dismissing the alert without taking action).

```bash
curl -X PATCH 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts/{chargeback_alert_id}' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "action": "REFUND",
    "note": "Refund issued via PSP before deadline"
  }'
```

Once you take action, the alert moves to `RESOLVED` status. Alerts that are already `RESOLVED` can't be updated again. Pay close attention to `actionRequiredDeadline` — if you don't act before this ISO 8601 timestamp, the chargeback proceeds regardless.

## Verifi RDR refund rules

Refund rules let you control which **Verifi RDR** alerts Evervault automatically refunds. Rules only affect Verifi RDR alert processing — they don't change how Ethoca alerts are resolved, even if the merchant is enrolled in both networks.

By default, when a merchant has no rules configured, **all** incoming Verifi alerts are refunded. Once you create one or more rules, Evervault evaluates the disputed transaction amount against those rules. If the amount matches, the alert is refunded as usual. If it does not match, the alert is **not** refunded — and because Verifi alerts are only charged when a refund is processed, non-matching alerts aren't billed either.

### The rule object

```json
{
  "id": "{rule_id}",
  "type": "AMOUNT",
  "outcome": "REFUND",
  "parameters": {
    "operator": "LESS_THAN_OR_EQUAL",
    "currencyCode": "USD",
    "amountInCents": 5000
  },
  "createdAt": "2025-02-11T10:30:00Z"
}
```

- `type` — currently `AMOUNT` (the only supported rule type).
- `outcome` — the action taken when the rule matches. Currently always `REFUND`.
- `parameters.operator` — one of `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `EQUAL`, or `NOT_EQUAL`.
- `parameters.currencyCode` — must be `USD`. Only USD transaction amounts are supported for rule evaluation. If you want to set a threshold in another currency, convert it to USD yourself and pass the equivalent amount in cents with `currencyCode` set to `USD`.
- `parameters.amountInCents` — the threshold amount in cents against which the disputed amount is compared. Must be a positive integer.
- `createdAt` — ISO 8601 timestamp (UTC), consistent with the alert object's `createdAt`.

### Create a rule

`POST /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules`

The merchant must already be enrolled in Verifi RDR — rules only govern Verifi auto-refunds, so creating a rule for a merchant enrolled only in Ethoca is rejected with a `400`. Both `type` and all `parameters` fields are required. Returns `201` with the created rule.

```bash
curl -X POST 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "type": "AMOUNT",
    "parameters": {
      "operator": "LESS_THAN_OR_EQUAL",
      "currencyCode": "USD",
      "amountInCents": 5000
    }
  }'
```

This example refunds Verifi alerts where the disputed amount is $50.00 USD or less. Alerts above that threshold are not refunded.

### Update a rule

`PATCH /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}`

A rule's `type` can't be changed — only its `parameters`. `parameters` is replaced, not merged, so send the complete object (`operator`, `currencyCode`, `amountInCents`); a partial or empty object is rejected with `400`. Omitting `parameters` entirely is a no-op — the rule is returned unchanged. Returns `200` with the updated rule, or `404` if the rule doesn't exist or doesn't belong to that merchant.

```bash
curl -X PATCH 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "parameters": {
      "operator": "LESS_THAN_OR_EQUAL",
      "currencyCode": "USD",
      "amountInCents": 10000
    }
  }'
```

### List rules

`GET /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules`

Returns a JSON array of rules for the merchant.

A merchant has [at most one rule](#verifi-rdr-refund-rules), so this array contains zero or one item.

Unlike the [alerts list](#list-alerts), the response is a bare array, not wrapped in an `{ items, count }` object.

```bash
curl 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules' \
  -u '<app_id>:<api_key>'
```

### Get a rule

`GET /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}`

Returns `404` if the rule does not exist or does not belong to that merchant.

```bash
curl 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
  -u '<app_id>:<api_key>'
```

### Delete a rule

`DELETE /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}`

Deleting a rule restores the default behaviour: all Verifi alerts for that merchant are refunded. Returns `204 No Content` on success. Returns `404` if the rule does not exist or has already been deleted — delete is not idempotent, so retrying a successful delete won't return `204`.

```bash
curl -X DELETE 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
  -u '<app_id>:<api_key>'
```

## Webhooks

Rather than polling the API, you can subscribe to webhook events to be notified in real time. Pre-chargeback alerts supports two event types:

- [`payments.pre-chargeback-alert.received`](#alert-received) — fired when Evervault receives a new alert for your app.
- [`payments.pre-chargeback-enrolment-status.updated`](#enrolment-configuration-updated) — fired when an enrolment's status changes (for example, `PENDING` → `ACTIVE`).

See the [Webhooks](/developers/webhooks) documentation for full setup instructions, including how to secure and register your endpoint. Register your endpoint in the [Dashboard](https://app.evervault.com) under **Settings > Webhooks** and subscribe to the events you need.

> Webhook events may be delivered more than once in rare cases. Use the `id`
>   field on the event object to deduplicate. Duplicate alert webhook events are
>   only charged once.

### Alert received

Event type: `payments.pre-chargeback-alert.received`

Fired whenever Evervault receives a new alert for your app. Each delivery is a POST request with a JSON body shaped as a standard [webhook event object](/developers/webhooks#webhook-event-object):

```json
{
  "id": "{event_id}",
  "type": "payments.pre-chargeback-alert.received",
  "data": {
    ...alert object...
  },
  "createdAt": "2025-02-11T10:30:00Z"
}
```

The `data` field contains the full [alert object](#the-alert-object). Here is an example handler that processes both pre-chargeback alert webhook events:

```javascript
app.post("/evervault", (req, res) => {
  const event = req.body;

  switch (event.type) {
    case "payments.pre-chargeback-alert.received": {
      const alert = event.data;

      if (
        alert.alertType === "ETHOCA_ALERT" &&
        alert.status === "ACTION_REQUIRED"
      ) {
        // Resolve with your PSP, then PATCH the alert via the Evervault API
      }
      break;
    }
    case "payments.pre-chargeback-enrolment-status.updated": {
      const configuration = event.data;

      if (configuration.status === "ACTIVE") {
        // Enrolment is live — the merchant can now receive alerts
      } else if (configuration.status === "ACTION_REQUIRED") {
        // Enrolment needs attention (usually an Ethoca descriptor issue)
      }
      break;
    }
  }

  res.status(200).send({ success: true });
});
```

### Enrolment configuration updated

Event type: `payments.pre-chargeback-enrolment-status.updated`

Fired when an enrolment's status changes after the initial create or update call — for example when a network activates the enrolment or flags a descriptor for review. This is the recommended way to track [enrolment status](#enrolment-statuses) transitions without polling the Merchants API.

Each delivery uses the same [webhook event object](/developers/webhooks#webhook-event-object) shape:

```json
{
  "id": "{event_id}",
  "type": "payments.pre-chargeback-enrolment-status.updated",
  "data": {
    ...configuration object...
  },
  "createdAt": "2025-02-11T10:30:00Z"
}
```

The `data` field contains a [configuration object](#the-configuration-object) describing the status transition.

## The alert object

When Evervault receives an alert from one of the networks, it creates an alert record. Here is a full example:

```json
{
  "id": "{chargeback_alert_id}",
  "merchantId": "{merchant_id}",
  "alertType": "ETHOCA_ALERT",
  "alertNetworkId": "1234567890",
  "status": "ACTION_REQUIRED",
  "chargebackReasonCode": "10.4",
  "transactionAmountInCents": 4999,
  "transactionCurrencyCode": "USD",
  "transactionAuthorizedAt": "2025-02-10T10:30:00Z",
  "actionRequiredDeadline": "2025-02-17T10:30:00Z",
  "transactionAuthorizationCode": "ABC123",
  "transactionAcquirerReferenceNumber": "74027012345678901234567",
  "transactionStatementDescriptor": "EXAMPLE STORE",
  "transactionCardBin": "424242",
  "card": {
    "bin": "424242",
    "lastFour": "4242",
    "brand": "VISA",
    "issuer": "Example Bank"
  },
  "transactionRefundOutcome": null,
  "transactionNetworkId": null,
  "subscriptionCancelOutcome": null,
  "note": "Customer requested immediate review",
  "integrationId": null,
  "integrationTransactionId": null,
  "createdAt": "2025-02-11T10:30:00Z"
}
```

- `alertType` — either `ETHOCA_ALERT` or `VERIFI_RDR`.
- `status` — `ACTION_REQUIRED` (Ethoca only), `RESOLVED`, or `INVALID`.
- `transactionAuthorizedAt`, `actionRequiredDeadline`, and `createdAt` — ISO 8601 timestamps in UTC (for example, `"2025-02-11T10:30:00Z"`). For Ethoca alerts, you must act before `actionRequiredDeadline` or the chargeback proceeds regardless of whether you refunded the customer.
- `transactionAcquirerReferenceNumber` — the ARN, which is useful when communicating with your PSP to identify the transaction.
- `transactionStatementDescriptor` — the descriptor that appeared on the cardholder's statement.
- `transactionCardBin` — first 6–11 digits of the card number. Also included in `card.bin`.
- `card` — card details for the disputed transaction, when available. Contains `bin` (BIN/IIN), `lastFour` (last four digits), `brand` (card scheme, for example `VISA` or `MASTERCARD`), and `issuer` (issuing bank name).
- `transactionRefundOutcome` — populated when a refund outcome is known. For Verifi RDR, this is set automatically.

## The configuration object

When an enrolment's status changes, the `payments.pre-chargeback-enrolment-status.updated` event includes a configuration object in `data`. Here is a full example:

```json
{
  "id": "{chargeback_alerts_enrolment_id}",
  "merchantId": "{merchant_id}",
  "type": "ETHOCA_ALERT",
  "oldStatus": "PENDING",
  "status": "ACTIVE",
  "updatedAt": "2025-02-11T10:30:00Z"
}
```

- `id` — Evervault enrolment UUID (for example, `chargeback_alerts_enrolment_...`).
- `merchantId` — Evervault merchant ID the enrolment belongs to.
- `type` — enrolment network: `ETHOCA_ALERT` or `VERIFI_RDR`.
- `oldStatus` — status before this update. `null` on the first event for a new enrolment.
- `status` — current enrolment status after the update. See [enrolment statuses](#enrolment-statuses) for possible values.
- `updatedAt` — ISO 8601 timestamp (UTC) when the enrolment was last updated.

Provider-specific configuration (Ethoca descriptors, Verifi BIN/CAID, and so on) is not included in the webhook payload — retrieve the merchant via the [Merchants API](/api#getMerchant) if you need the full enrolment details.

## Testing (sandbox)

In sandbox, you can simulate an incoming alert without waiting for a real dispute. This is useful for testing your webhook handler and alert-processing logic.

```bash
curl -X POST 'https://api.evervault.com/payments/pre-chargeback-alerts/simulate-alert' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "merchantId": "{merchant_id}",
    "status": "ACTION_REQUIRED",
    "cardScheme": "MASTERCARD",
    "amountInCents": 4999,
    "currencyCode": "USD"
  }'
```

All fields other than `merchantId` are optional. The `merchantId` must belong to a merchant that has already been enrolled in pre-chargeback alerts. When supplied:

- `amountInCents` must be a positive integer.
- `currencyCode` must be a valid ISO 4217 code.
- `status` must be one of `ACTION_REQUIRED`, `RESOLVED`, or `INVALID`.
- `cardScheme` must be one of `VISA`, `MASTERCARD`, `MAESTRO`, `AMEX`, `DISCOVER`, `JCB`, `DINERS_CLUB`, `UNIONPAY`, `RUPAY`, `INTERAC`, `MIR`, or `OTHER`.
- `transactionRefundOutcome` must be `REFUNDED` or `NOT_REFUNDED`, and may only be supplied when `status` is `RESOLVED`.
- `transactionAcquirerReferenceNumber` must be exactly 23 characters.
- `transactionAuthorizationCode` must be exactly 6 characters.

The endpoint returns a simulated alert object with a `201` status.

> Simulate is only available for sandbox apps.

## Disable alerts

To disable pre-chargeback alerts for a merchant, call `PATCH /payments/merchants/{merchant_id}` with `preChargebackAlerts.enabled` set to `false`:

```bash
curl -X PATCH 'https://api.evervault.com/payments/merchants/{merchant_id}' \
  -H 'Content-Type: application/json' \
  -u '<app_id>:<api_key>' \
  -d '{
    "preChargebackAlerts": {
      "enabled": false
    }
  }'
```

> If the merchant is already actively receiving alerts, the unenrolment process
>   is manual and takes a few working days to complete. The merchant will continue
>   to receive alerts during this window.

## Errors

Pre-chargeback alerts endpoints return standard Evervault API error responses. Common cases:

| HTTP status | When |
| --- | --- |
| `400` | The request is invalid — for example, an invalid field in an update or simulate request (such as an unrecognised `action`, `status`, `cardScheme`, or `transactionRefundOutcome`); invalid, empty, or partial rule `parameters`; creating a rule for a merchant that has no Verifi RDR enrolment; a rule already exists for the merchant; or malformed query parameters on the alerts list. |
| `403` | The API key doesn't have the [grant](#api-key-grants) required for the operation. |
| `404` | The requested resource was not found — for example, an alert or rule ID that does not exist, a rule that does not belong to the merchant, a merchant that does not exist or is not yours, or pre-chargeback alerts that have not been configured for the app. |
| `422` | The alert network rejected the request — for example, attempting to action an alert that is already resolved. |

## Reason codes

Each alert includes a `chargebackReasonCode` field that identifies why the dispute was raised. The codes differ by card network.

| Code | Description |
| --- | --- |
| **Visa** | |
| 10.1 — EMV Liability Shift Counterfeit Fraud | A counterfeit copy of the cardholder's chip card was used to make fraudulent purchases. |
| 10.2 — EMV Liability Shift Non-Counterfeit Fraud | The cardholder's chip card required PIN verification, but the merchant processed it at a terminal without a chip reader. |
| 10.3 — Other Fraud: Card-Present Environment | The cardholder disputed a transaction that was key-entered by staff, or processed at an unattended terminal without the cardholder's involvement. |
| 10.4 — Other Fraud: Card-Absent Environment | The cardholder claimed that a card-not-present transaction was unauthorized. |
| 10.5 — Visa Fraud Monitoring Program | The merchant is enrolled in Visa's fraud monitoring program, which permits the issuer to raise disputes. |
| 11.1 — Card Recovery Bulletin | The transaction exceeded the merchant's floor limit, and no authorization was requested from the card network before completing the sale. |
| 11.2 — Declined Authorization | The terminal received a decline or card-pickup response from the authorizing network, but the sale was completed regardless. |
| 11.3 — No Authorization | The payment was processed without attempting to obtain an authorization approval. |
| 12.1 — Late Presentment | The merchant submitted the transaction after the presentment window expired, by which point the account was no longer in good standing. |
| 12.2 — Incorrect Transaction Code | A debit was submitted when a credit was required, or a credit was submitted in place of a reversal. |
| 12.3 — Incorrect Currency | The currency at the terminal didn't match the currency transmitted to Visa during processing. |
| 12.4 — Incorrect Account Number | The transaction was applied to the wrong card account number. |
| 12.5 — Incorrect Amount | The amount debited from the cardholder differed from the amount they agreed to pay. |
| 12.6 — Duplicate Processing / Paid By Other Means | The same transaction was submitted more than once in a batch settlement, or the customer paid using a separate payment method and was charged again. |
| 12.7 — Invalid Data | The authorization request contained an error in a required field such as the transaction date, merchant category code, or country code. |
| 13.1 — Merchandise/Services Not Received | The cardholder didn't receive the goods or services within the timeframe that was defined at the point of sale. |
| 13.2 — Cancelled Recurring Transaction | A recurring charge was billed after the cardholder already requested cancellation of the subscription or agreement. |
| 13.3 — Not As Described or Defective Merchandise/Services | The item or service delivered was materially different from what was advertised at purchase, or arrived damaged or non-functional. |
| 13.4 — Counterfeit Merchandise | The goods received were not genuine, or the cardholder falsely asserted that authentic items were counterfeit. |
| 13.5 — Misrepresentation | The merchant's product or service descriptions were misleading, inaccurate, or materially incomplete. |
| 13.6 — Credit Not Processed | The merchant failed to apply an agreed credit, or the credit was issued too late to appear on the relevant billing statement. |
| 13.7 — Cancelled Merchandise/Services | Goods were returned or a service was cancelled, but the cardholder's account wasn't credited. |
| 13.8 — Original Credit Transaction Not Accepted | The cardholder declined to accept the original credit, or local regulations prevented the issuing bank from processing it. |
| 13.9 — Non-Receipt of Cash or Load Transaction Value | The cardholder didn't receive the full cash amount from an ATM withdrawal, or received only a partial disbursement. |
| **Mastercard** | |
| 4807 — Warning Bulletin File | The card appeared on a warning bulletin at the time of the transaction, indicating it shouldn't have been accepted. |
| 4808 — Authorization-Related Chargeback | The required authorization wasn't obtained before processing, or the transaction was completed after receiving a decline response. |
| 4812 — Account Number Not on File | The card account number submitted didn't match any record held by the issuer. |
| 4831 — Transaction Amount Differs | The amount charged to the cardholder didn't match what appeared on the transaction receipt. |
| 4834 — Duplicate Processing | The same transaction was submitted and settled multiple times. |
| 4837 — No Cardholder Authorization | The cardholder stated they didn't authorize the transaction and received no benefit from it. |
| 4840 — Fraudulent Processing of Transactions | A transaction was processed multiple times under a single authorization, or a series of fraudulent charges were made with a single approval. |
| 4842 — Late Presentment | The transaction wasn't submitted to the network within the required timeframe. |
| 4846 — Correct Transaction Currency Code Not Provided | The cardholder was billed in a different currency than the one used at the time of purchase. |
| 4850 — Installment Billing Dispute | A dispute was made over the terms or execution of an installment billing arrangement. |
| 4853 — Cardholder Dispute: Defective/Not as Described | The goods or services received were defective, damaged, or materially different from how they were described. |
| 4854 — Cardholder Dispute: Not Elsewhere Classified | The dispute doesn't fit any other defined category and wasn't resolved through direct negotiation. |
| 4855 — Goods or Services Not Provided | The merchant didn't deliver the goods or services the cardholder purchased. |
| 4859 — Services Not Rendered | The cardholder paid for a service that wasn't performed. |
| 4860 — Credit Not Processed | The merchant agreed to issue a credit but didn't process it within the expected timeframe. |
| 4863 — Cardholder Does Not Recognize: Potential Fraud | The cardholder can't identify the charge on their statement and suspects it may be fraudulent. |
| 4870 — Chip Liability Shift | A genuine chip card was used at a non-chip-capable terminal and a fraudulent transaction resulted. |
| 4871 — Chip/PIN Liability Shift | A chip-and-PIN card was processed at a terminal that didn't support chip-and-PIN authentication and fraud occurred. |
| 4999 — Domestic Chargeback Dispute | A domestic transaction was disputed under local card network operating regulations. |
| **American Express** | |
| A01 — Charge Exceeds Authorization Amount | The final amount billed exceeded the amount that was originally authorised. |
| A02 — No Valid Authorization | The transaction was processed without obtaining a valid authorization code. |
| A08 — Authorization Approval Expired | The authorization obtained prior to settlement had already lapsed when the charge was submitted. |
| C02 — Credit Not Processed | A credit was either not applied or was only partially posted to the cardholder's account. |
| C04 — Goods/Services Returned or Refused | The cardholder returned or refused the goods or services, but no refund was issued. |
| C05 — Goods/Services Cancelled | An order was cancelled in line with the merchant's stated policy but no refund was provided. |
| C08 — Goods/Services Not Received | The cardholder didn't receive the ordered goods or services within the expected timeframe. |
| C14 — Paid By Other Means | The cardholder paid for the transaction using a different payment method and was charged twice. |
| C18 — No-Show or CARDeposit Cancelled | A reservation was cancelled within the policy period but a no-show or deposit fee was still charged. |
| C28 — Cancelled Recurring Billing | A recurring charge was processed after the cardholder already cancelled the subscription or agreement. |
| C31 — Goods/Services Not As Described | The item received didn't match what was shown or described at the time of purchase. |
| C32 — Goods/Services Damaged or Defective | The goods arrived in a damaged condition or were defective upon delivery. |
| F10 — Missing Imprint | No card imprint was captured at the point of sale despite being required for the transaction type. |
| F14 — Missing Signature | The sales receipt lacks the cardholder's signature, which was required for the transaction. |
| F24 — No Cardmember Authorization | The cardholder denied authorizing or benefiting from the transaction. |
| F29 — Card Not Present | The cardholder disputed the transaction because the card wasn't physically present at the time of purchase. |
| F30 — EMV Counterfeit | A counterfeit chip card was used to complete a fraudulent transaction. |
| F31 — EMV Lost/Stolen/Non-Received | The card used in the transaction was reported lost, stolen, or was never received by the cardholder. |
| M01 — Chargeback Authorization | The cardholder authorized the merchant to raise a chargeback on their behalf. |
| M10 — Vehicle Rental: Capital Damages | The cardholder disputed capital damage charges applied by a vehicle rental company. |
| M49 — Vehicle Rental: Theft or Loss of Use | The cardholder disputed fees for theft or loss-of-use levied by a vehicle rental company. |
| P01 — Unassigned Card Number | The card number used didn't correspond to any account the issuer holds on record. |
| P03 — Credit Processed as Charge | A credit or refund was submitted in error as a charge to the cardholder. |
| P04 — Charge Processed as Credit | A purchase transaction was incorrectly posted to the account as a credit. |
| P05 — Incorrect Charge Amount | The amount charged differed from the amount at the time of the transaction. |
| P07 — Late Submission | The charge was submitted for settlement after the permitted submission window had closed. |
| P08 — Duplicate Charge | The same transaction was submitted and posted more than once. |
| P22 — Non-Matching Account Number | The account number used during authorization differed from the one recorded on the settled charge. |
| P23 — Currency Discrepancy | The currency of the settled transaction didn't match what was specified during authorization. |
| R03 — Insufficient Reply | The merchant's response to a previous dispute inquiry didn't contain enough information to resolve the issue. |
| R13 — No Reply | The merchant didn't respond to a dispute inquiry within the required timeframe. |
| **Discover** | |
| AA — Does Not Recognize | The cardholder can't identify the transaction on their statement. |
| AP — Recurring Payments | A recurring billing charge was processed after the cardholder cancelled the underlying subscription or agreement. |
| AW — Altered Amount | The transaction amount was changed after the cardholder's initial approval. |
| PM — Paid By Other Means | The purchase was settled using a different payment method, resulting in a duplicate charge on the Discover card. |
| RG — Non-Receipt of Goods or Services | The cardholder didn't receive the goods or services they purchased. |
| UA01 — Fraud: Card Present Transaction | The cardholder denied making a purchase that was processed as a card-present transaction. |
| UA02 — Fraud: Card Not Present Transaction | The cardholder stated they didn't authorize an online or telephone transaction. |
| UA05 — Fraud: Chip Counterfeit Transaction | A counterfeit chip card was used fraudulently at a chip-enabled terminal. |
| UA06 — Fraud: Chip and PIN Transaction | A chip-and-PIN transaction was disputed as fraudulent by the cardholder. |
| UA38 — Fraud: Fictitious Account | The account number used doesn't correspond to a genuine, active Discover card account. |


---

# Real-time Account Updater

_Check for card updates on demand with a single encrypted request, or subscribe for updates using webhooks._

Real-time Account Updater (RTAU) ensures that you always have the latest card number and expiration date for customers' cards. It helps maintain seamless billing without needing the customer to manually update their card details. This results in higher authorization rates and reduced friction for customers.

> **Coming soon**
>
> Real-time Account Updater is coming soon. To get access to our beta product,
>   [register your
>   interest](https://tally.so/r/xXArgy?utm_medium=docs&utm_source=evervault&utm_campaign=beta_launch_rtau).

## The benefits of Real-time Account Updater

Using RTAU to manage card details offers several advantages over customers manually updating their information.

- **Improved authorization rate**: Since RTAU ensures you always have the most current card details, transactions are less likely to be declined due to outdated information. This leads to a higher authorization rate and a smoother customer experience.
- **Seamless customer experience**: Customers no longer need to manually update their card details for recurring payments or card-on-file transactions. RTAU automates this process, reducing friction and enhancing the overall customer experience. This is particularly beneficial for subscription-based services, where up to date payment information is crucial.
- **Reduced operational overhead**: Automating the card update process means you don't have to contact customers for new card information. This reduces the administrative burden and allows you to focus on more critical business operations.
- **Improved customer retention**: By ensuring seamless recurring payments, your customers complete payments at a higher rate and stay subscribed for longer.

## How Real-time Account Updater works

The process begins when an issuer updates a customer's card (usually due to reasons like expiration, replacement, or re-issuance). The card issuer sends the updated details to the card network, and the card network forwards these updates to you through Evervault's Real-time Account Updater Service. After you receive the updates, your system can automatically replace outdated card details with the new ones. This ensures continuous service for the customer without interruption. Subsequent updates or replacements for the same card are sent as they become available.

![A diagram showing the Card Account Updater process]()

Evervault pushes updated card information to configured webhooks immediately after we receive the new details. You can also use the API to retrieve the latest state of a card. This means you can check card details before or after a transaction, which is useful in situations where a failed transaction is likely to cause significant revenue disruption (e.g., high value transactions).

## Get started with Real-time Account Updater

You integrate RTAU using our APIs without having to interact directly with card networks. To get updates for a card, you can:

- Check the card manually using the API, and receive the result synchronously.
- Subscribe the card, then configure a webhook endpoint to receive updates automatically.

If a new card number is available, it's returned as an Evervault encrypted string. If you need to do additional processing of the encrypted card data, see [Processing encrypted card data](/cards/card-collection#processing-encrypted-card-data) for further details.

## Check a card for updates

Submit a card number and expiry to the [checks](/api#createAccountUpdaterCheck) endpoint. The `card.number` can be a plaintext card number or an Evervault encrypted card number. Make sure to authenticate with an API key that has the `card:checks` grant.

```bash
curl 'https://api.evervault.com/payments/cards/checks' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "card": {
    "number": "ev:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
    "expiry": {
      "month": "12",
      "year": "28"
    }
  }
}'
```

> **Plaintext card numbers**
>
> An Evervault encrypted card number is used in this example. Evervault
>   recommends passing encrypted card numbers to prevent having plaintext
>   card numbers in your infrastructure.

### Handling card updates

The check is synchronous, so the result comes back in the response. If a new card number is available, `update.card.number` is always an Evervault encrypted string, and only ever returned on a `new-account-number` result. The plaintext card number is never returned.

```json
{
  "id": "auc_8da9a7fbde01",
  "result": "new-account-number",
  "update": {
    "card": {
      "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
      "expiry": {
        "month": "04",
        "year": "30"
      }
    }
  }
}
```

The `result` field describes the outcome of the check. The `update` object is only populated on `new-expiry-date` and `new-account-number` results. For every other result, it's `null`.

| Result | Description |
| --- | --- |
| `no-change` | The card matches the issuer and there's nothing to update. |
| `new-expiry-date` | A new expiry date is available, returned in `update.card.expiry`. |
| `new-account-number` | A new account number is available, returned as an encrypted string in `update.card.number`, along with an expiry in `update.card.expiry`. The expiry may be the same or different. |
| `account-closed` | The account is closed and shouldn't be used for future payments. No new credentials are returned. |
| `contact-cardholder` | Updates are withheld for risk or privacy reasons. No new credentials are returned. |
| `cardholder-opt-out` | The cardholder has opted out of account updates. No new credentials are returned. |
| `merchant-opt-out` | The issuer has opted out of sharing updates with the merchant. No new credentials are returned. |
| `no-match` | The card isn't known to the network. No new credentials are returned. |

## Subscribe a card to real-time updates

Submit a card number and expiry to the [subscriptions](/api#createAccountUpdaterSubscription) endpoint. The `card.number` can be a plaintext card number or an Evervault encrypted card number. Make sure to authenticate with an API key that has the `card:subscriptions` grant.

```bash
curl 'https://api.evervault.com/payments/cards/subscriptions' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "card": {
    "number": "ev:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
    "expiry": {
      "month": "12",
      "year": "28"
    }
  }
}'
```

### Handling the webhook

When the card networks push an update, Evervault sends a `real-time.card.updated` event. Register a [webhook endpoint](/api#webhook-endpoints) subscribed to that event to receive it.

```json
{
  "id": "webhook_event_0aa6ff0fee57",
  "type": "real-time.card.updated",
  "data": {
    "subscription": "aus_8da9a7fbde01",
    "result": "new-account-number",
    "update": {
      "card": {
        "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
        "expiry": {
          "month": "04",
          "year": "30"
        }
      }
    }
  }
}
```

The result field describes the outcome. The update object is only populated on `new-expiry-date` and `new-account-number` results; for every other result it's null.

| Result | Description |
| --- | --- |
| `new-account-number` | A new account number is available, returned as an encrypted string in `update.card.number` along with an expiry in `update.card.expiry`. The expiry may be the same or different. |
| `new-expiry-date` | A new expiry date is available, returned in `update.card.expiry`. |
| `account-closed` | The account is closed and shouldn't be used for future payments. No new credentials are returned. |

{/*
recommendedAction is temporarily hidden. To restore, do three things.
Uncomment this section.
Re-add the recommended-actions link in the "Simulate an asynchronous update" section below.
Re-add `"recommendedAction": "update-card-details"` as the last field of `data` in the two `real-time.card.updated` JSON examples above.

### Recommended actions for asynchronous updates

Each update carries a `recommendedAction` that tells your listener what to do. A push only happens on an update from a card network, so the webhook uses a subset of the recommended actions that are applicable.

<Table headings={["Recommended action", "When", "What to do"]}>
  <TableRow>
    <TableCell>`update-card-details`</TableCell>
    <TableCell>`new-account-number`, `new-expiry-date`</TableCell>
    <TableCell>Update the stored card details before the next payment.</TableCell>
  </TableRow>
  <TableRow>
    <TableCell>`use-another-payment-method`</TableCell>
    <TableCell>`account-closed`</TableCell>
    <TableCell>The account is closed and shouldn't be used for future payments. Request new card details and use another payment method.</TableCell>
  </TableRow>
</Table>
*/}

### Unsubscribe a card from real-time updates

Unsubscribe the card using the subscription `id` to stop receiving webhook updates for it. Evervault never stores the card number, so provide the same encrypted or plaintext card number and expiry you subscribed with. Make sure to authenticate with an API key that has the `card:subscriptions` grant.

```bash
curl -X POST 'https://api.evervault.com/payments/cards/subscriptions/aus_8da9a7fbde01/unsubscribe' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "card": {
    "number": "ev:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
    "expiry": {
      "month": "12",
      "year": "28"
    }
  }
}'
```

### Rate limits

There are rate limits on checking cards, subscribing them, and unsubscribing them. Requests that exceed the limit return a `429` response and aren't sent to the upstream card provider. For the full policy, see [API rate limits](/more/faq#does-the-evervault-api-have-rate-limits).

### Supported card networks

Evervault supports real-time updates for Visa and Mastercard cards. American Express isn't supported, as Amex cards can't be registered for real-time updates at this time. To fetch updates for American Express cards, please see [Card Account Updater](/cards/card-account-updater).

## Testing

You can use Evervault's [Sandbox apps](/developers/sandbox) to test the full process without affecting live data. The [simulate updates](#simulate-updates-in-sandbox) section explains how to test the process for checking cards and receiving update events. When you're ready to transition to Live Mode, contact our support team at [support@evervault.com](mailto:support@evervault.com).

### Simulate updates in Sandbox mode

Sandbox apps don't receive real updates from card networks, so Evervault provides simulated endpoints for testing. Use them to test your integration before switching to Live Mode. The manual check flow and the asynchronous flow each have their own endpoint, so you can test them independently.

> **Sandbox only**
>
> Simulated endpoints are only available to [Sandbox apps](/developers/sandbox). Calling them with a Live app returns a `403` response.

### Simulate card updates after a manual check

Submit the test card `4242424242424242` along with the `type` of result you want returned to the [checks simulate](/api#simulateAccountUpdaterCheck) endpoint. Make sure to authenticate with an API key that has the `card:checks` grant. The `type` attribute accepts any of the [check results](#handling-card-updates).

```bash
curl 'https://api.evervault.com/payments/cards/checks/simulate' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "card": {
    "number": "4242424242424242",
    "expiry": {
      "month": "12",
      "year": "28"
    }
  },
  "type": "new-account-number"
}'
```

> **Test card only**
>
> Checks can only be simulated for the test card `4242424242424242`. Calling the endpoint with any other card in sandbox apps returns a `400` response.

The response is identical in shape to a live check. For `new-expiry-date` and `new-account-number`, the `update` object is populated, and `new-account-number` returns the test card `4111111111111111` as an Evervault encrypted string. Every other result returns a `null` update.

```json
{
  "id": "auc_8da9a7fbde01",
  "result": "new-account-number",
  "update": {
    "card": {
      "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
      "expiry": {
        "month": "04",
        "year": "30"
      }
    }
  }
}
```

### Simulate an asynchronous update

For the asynchronous flow, [subscribe a card](#subscribe-a-card-to-real-time-updates) in a sandbox app first, using the test card `4242424242424242`. Make sure to authenticate with an API key that has the `card:subscriptions` grant. Then, submit a simulated subscription update to the [subscription simulate](/api#simulateAccountUpdaterSubscription) endpoint, and Evervault delivers a `real-time.card.updated` event to your registered webhook.

```bash
curl 'https://api.evervault.com/payments/cards/subscriptions/aus_8da9a7fbde01/simulate' \
-H 'Content-Type: application/json' \
-u '<app_id>:<api_key>' \
-d '{
  "type": "new-expiry-date"
}'
```

> **Test card only**
>
> Updates can only be simulated for a subscription to `4242424242424242`. Calling the endpoint for a subscription to any other card in sandbox apps returns a `400` response.

The card networks only push a subset of results asynchronously, so the `simulate` endpoint accepts only the update types that can arrive over a webhook.

| Type | Description |
| --- | --- |
| `new-account-number` | Simulates a new account number. Returns the new card number in `update.card.number` along with an expiry in `update.card.expiry`. The replacement card is always the test card `4111111111111111` as an Evervault encrypted string, and the simulated expiry date will always be 1 year in the future from the current month. |
| `new-expiry-date` | Simulates a new expiry date, returned in `update.card.expiry`. The simulated expiry date will always be 3 years in the future from the current month. |
| `account-closed` | Simulates a closed account. No new credentials are returned. |

Evervault delivers the simulated update to your registered webhook as a `real-time.card.updated` event, identical in shape to a production webhook. For the `new-expiry-date` request above, the payload looks like this.

```json
{
  "id": "webhook_event_0aa6ff0fee57",
  "type": "real-time.card.updated",
  "data": {
    "subscription": "aus_8da9a7fbde01",
    "result": "new-expiry-date",
    "update": {
      "card": {
        "expiry": {
          "month": "07",
          "year": "29"
        }
      }
    }
  }
}
```

Handle the simulated event exactly as you would a production update{/*, following the [asynchronous recommended actions](#recommended-actions-for-asynchronous-updates)*/}.

- [Network Tokens](/cards/network-tokens): Learn how to tokenize cards for secure, network-provisioned payments.
- [Insights](/cards/insights): Learn how to gain additional insights into the cardholder and the card itself.


---

# Page Protection

_Monitor third-party scripts and security headers to detect unauthorized changes and meet PCI DSS v4 requirements._

Page Protection works by intercepting requests to all third-party scripts on your page (including Evervault's). We monitor the source code for every script load and trigger an alert if any changes are detected. We also monitor for new scripts being added to a page as well as changes to security headers.

Evervault Page Protection helps protect companies from sophisticated card data breaches, while directly addressing new requirements in PCI DSS Version 4:

- [Prevent Unauthorized Scripts (6.4.3)](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf#page=157)
- [Verify Script Integrity (6.4.3)](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf#page=157)
- [Maintain a Script Inventory (6.4.3)](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf#page=157)
- [Header Tamper and Change Detection (11.6.1)](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf#page=292)

With monitoring and alerting, you'll detect potentially malicious JavaScript changes before they impact your customers — without the noise.

## Getting started

To get started with page protection, you need to register the page you want to monitor. Inside of the Evervault Dashboard, navigate to the **Page Protection** tab and click on **Add Page**. Specify the URL where your page is hosted, and an optional name to help identify the page. After creating the page, you will be guided through the process of installing the monitoring script on your page.

![A screenshot of the Add Page modal in the Evervault dashboard.]()

## Monitoring

Once you have successfully deployed the monitoring script, any third party script or security header changes made on your page are tracked by Evervault. These changes appear inside of the Evervault Dashboard as alerts allowing you to review, approve, and provide a reason for each change that's been detected. You can see all resolved issues in the **Resolved** tab, including the reviewer and reason for the change:

![A screenshot of the Page Protection tab in the Evervault dashboard showing open issues.]()

> Reasons are only required when new scripts are added to the page. However,
>   it's a good rule of thumb to add a reason for the change for auditing purposes
>   if you can identify it.

### Alerting

To receive alerts for changes to your page, enable Page Protection events by navigating to **App → Settings → Webhooks → Create Endpoint**. Slack and standard webhooks are supported. You can subscribe to the following events:

| Event | Description |
| --- | --- |
| `page-protection.scripts.added` | Fires when a new script has been detected on the page. |
| `page-protection.scripts.updated` | Fires whenever a change was detected for an existing script. |
| `page-protection.headers.updated` | Fires whenever a change was detected for security headers. |

## Auditing

All scripts and headers detected are stored for auditing purposes. From each inventory tab, you can export a CSV of all scripts and headers detected.

### Script inventory

Under the **Scripts** view, you can see an inventory of all scripts detected on the page. Click on a script to see its details, including the latest source code, reason for approval, and the history of changes and reviews:

![A screenshot of the Page Protection tab in the Evervault dashboard showing the Scripts view.]()

### Headers

Under the **Headers** view, you can see an inventory of all security headers detected on the page. You can copy the latest headers to your clipboard, or navigate the history of changes:

![A screenshot of the Page Protection tab in the Evervault dashboard showing the Headers view.]()

## Frequently Asked Questions

### Which headers does Evervault monitor?

We only monitor security headers that are used to protect against attacks like XSS and clickjacking:

```text
Content-Security-Policy
Content-Security-Policy-Report-Only
Cross-Origin-Embedder-Policy
Cross-Origin-Opener-Policy
Cross-Origin-Resource-Policy
Permissions-Policy
Referrer-Policy
Report-To
Reporting-Endpoints
Strict-Transport-Security
X-Content-Type-Options
X-Frame-Options
X-Permitted-Cross-Domain-Policies
X-XSS-Protection
```

### Does Page Protection track self-hosted scripts?

Any scripts that are hosted on your own domain are not tracked by Page Protection. This includes any third-party code that is installed via a package manager like npm and bundled with your application.

Since these scripts are part of your static application bundle, they can be analyzed before deployment. We recommend using code analysis tools during your build process to monitor for potential security threats.

OWASP maintains a list of [source code analysis tools](https://owasp.org/www-community/Source_Code_Analysis_Tools).

### Can I enable Page Protection on localhost?

Yes, you can enable Page Protection on localhost. You will need to add the following attribute to your monitoring script tag:

```html
<script src="https://monitoring..." data-local-mode></script>
```

You can also enable debug logs with the following attribute:

```html
<script src="https://monitoring..." data-log-level="DEBUG"></script>
```

### Can I disable proxying for specific scripts?

By default, all scripts are proxied through the monitoring endpoint. This ensures that the scripts running on the page match the versions being analyzed.

However, some scripts may not function correctly when proxied. In such cases, you can use the `data-proxy-bypass` attribute on the monitoring script. This attribute accepts a comma-separated list of script sources that bypass proxying while still being monitored.

```html
<script
  src="https://monitoring..."
  data-proxy-bypass="js.stripe.com,applepay.cdn-apple.com"
></script>
```

### Can I enable Page Protection on specific pages?

Yes, how you enable it depends on how your site is built:

1. **For server-side rendered sites**

Include the monitoring script on **every page** you want to track.

2. **For client-side rendered sites**

You can control monitoring dynamically:

```js
window.EvervaultMonitoring.enable();
window.EvervaultMonitoring.disable();
```

To set whether monitoring is enabled by default on page load, use the `data-default-enabled` attribute in the script tag:

```html
<script src="https://monitoring..." data-default-enabled="false"></script>
```

By default, `data-default-enabled` is set to true, so monitoring starts automatically unless explicitly disabled.

### What should I do if I don't recognize a change?

If you don't recognize a change we've detected, don't resolve the issue just yet. Follow these steps:

- If a new script is added, confirm with your engineering team that the script was meant to be added. If not, another script may have loaded it.
- If a script has been updated, check with the third-party script provider to find out what changes they included. You should also confirm with your engineering team that the change is safe, or if the script should be removed.
- If your security headers have been updated, confirm with your engineering team that the update was expected. If not, your team may need to update their security configuration.

Once you've confirmed the change, include the reason in your review and resolve the issue.


---

# ASV Scans

_Learn about ASV scans and how to run them with Evervault._

[Approved Scanning Vendor](<https://docs-prv.pcisecuritystandards.org/Programs%20and%20Certification/Approved%20Scanning%20Vendor%20(ASV)/ASV-Program-Guide-v4.0r2.pdf>) (ASV) scans identify security weaknesses and other flaws in public-facing systems. You need to submit a passing ASV scan [every three months or 90 days](https://www.pcisecuritystandards.org/faq/articles/Frequently_Asked_Question/for-vulnerability-scans-what-is-meant-by-quarterly-or-at-least-once-every-three-months/) depending on your compliance obligations under the [PCI Data Security Standard](https://www.pcisecuritystandards.org/standards/pci-dss/) (PCI DSS). Evervault recommends completing your scan well ahead of the deadline. Many customers submit monthly to enhance security and allow for early identification and resolution of any issues. You can run scans from the Evervault Dashboard, browse previous scans, and download scan results to share with external auditors.

## Getting started

Open the **ASV Scans** tab in the [Dashboard](https://app.evervault.com/), and then:

1. Click **Get started**.
2. Fill out your company name, estimated IP count, and other details.
3. Submit and wait for Evervault to contact you.

## Add a target

Targets contain the IPv4 addresses (or range of addresses) and DNS names to scan. You can include multiple IP addresses and DNS names in a single target. To create a target:

1. Click **+ New target** on the **ASV Scans** page.
2. Name the target.
3. Add the IP addresses and DNS names to scan.
4. Click **Create target**.

You can create as many targets as you need, and you can edit target names, descriptions, and hosts. Subdomains aren't scanned automatically and need to be added separately. For example, if you needed to scan `example.com` and `app.example.com`, you need to add them both, not just `example.com`.

### Which hosts should be scanned?

Generally, any systems (such as firewalls, routers, and servers) that store, process, or transmit cardholder data (CHD), or any system that could impact the security of CHD, needs to be scanned. When using Evervault, that means scanning hosts that call the iframe that collects card information.

## Run a scan

You can run scans by clicking **+ New scan**. You might need to add `38.123.140.0/25` to an allowlist if your domains aren't publicly accessible. Scan times can take up to 2+ hours depending on the number of targets, hosts, and the external systems themselves. You can rerun scans after they finish, as well as skip queued and in-progress scans.

> **Locked targets**
>
> Make sure targets are correctly configured before you scan them. After scanning, you can't edit the name, description, or hosts.

### How often should scans be run?

While a passing ASV scan is only required every 90 days, Evervault recommends running scans monthly to enhance security and allow for early identification and resolution of any issues.

## Evaluating and using results

Scan results are displayed in the Evervault Dashboard. Vulnerabilities are highlighted, and you can click any issue to view more information, fix recommendations, and request exceptions. Exceptions are typically reviewed within 24 hours. When working through remediations, you can rerun scans as needed at no extra cost.

You can download scan results as a PDF or JSON. You can also download Attestation and Executive Summary reports. If you're working with a Qualified Security Assessor (QSA), these reports should include the information required for compliance with PCI DSS 4.0 requirement 11.3.2.1.

### What happens if a scan fails?

If your scan fails, you need to remediate the high and medium severity issues that were identified. You can rerun scans as needed at no extra cost.

## ASV scan webhooks

Similar to other Evervault events, you can configure [webhooks](/developers/webhooks) for ASV scans. Scan times vary so you might want to set up Slack notifications or a webhook to notify your team when they finish. You can listen for when reports are created as well.


---

# PCI Compliance

_How Evervault helps reduce PCI DSS scope and cost while enabling secure collection and use of cardholder data._

The Payment Card Industry Data Security Standard (PCI DSS), is a global security standard which applies to any organization which stores, processes, or transmits cardholder data.

PCI DSS is a particularly thorough security standard which requires significant overhead to manage and demonstrate the security of card data, often costing companies $100k+ per year. That’s why organizations who handle cardholder data use Evervault to de-risk and de-scope their environments.

## Becoming PCI compliant

Evervault provides a hand held approach to help organizations de-risk their environments and minimize the effort required to become PCI DSS compliant. Once you begin the process of becoming PCI compliant, Evervault provides you with a PCI Policy Pack, which is a downloadable collection of documents and checklists to walk you through the process of becoming PCI compliant. The process can be broken down into the following core steps.

### Understanding your requirements

The first step to becoming PCI compliant is understanding which requirements apply to your business. You do this by understanding how card data flows through your organization and mapping out the systems supporting those flows. This becomes the basis for PCI Scope (Cardholder Data Environment - CDE). There are four levels of PCI compliance, each with different requirements depending on various factors such as the number of transactions processed annually.

**Level 1**

##### Applies to

    - Service Providers processing over 300,000 transactions annually
    - Merchants processing over 6 million transactions annually

    ##### Requirements

    - Annual Report on Compliance (RoC) by a Qualified Security Assessor (QSA)
    - Quarterly network scans by an Approved Scanning Vendor (ASV)
    - Internal and External Penetration testing at the Application and Network layers
    - Completion of the Attestation of Compliance (AoC) form
  **Level 2**

##### Applies to

    - Service Providers processing less than 300,000 transactions annually
    - Merchants processing between 1 million and 6 million transactions annually

    ##### Requirements

    - Annual Self-Assessment Questionnaire (SAQ)
    - Quarterly network scans by an Approved Scanning Vendor (ASV)
    - Completion of the Attestation of Compliance (AoC) form
  **Level 3**

##### Applies to

    - Merchants processing between 20,000 and 1 million transactions annually
    - **Service Providers can not be categorized as Level 3**

    ##### Requirements

    - Annual Self-Assessment Questionnaire (SAQ)
    - Quarterly network scans by an Approved Scanning Vendor (ASV)
    - Completion of the Attestation of Compliance (AoC) form
  **Level 4**

##### Applies to

    - Merchants processing less than 20,000 transactions annually
    - **Service Providers can not be categorized as Level 4**

    ##### Requirements

    - Annual Self-Assessment Questionnaire (SAQ)
    - Quarterly network scans by an Approved Scanning Vendor (ASV)
    - Completion of the Attestation of Compliance (AoC) form

### Reducing your scope

The Cardholder Data Environment (CDE) comprises people, processes, and technologies that store, process, or transmit cardholder data or sensitive authentication data. PCI DSS requirements apply to all system components included in or connected to the CDE. In the simplified diagram below—which describes a system handling plaintext credit card data—all components are in scope for the 300+ PCI DSS Requirements, because they directly store, process, or transmit card data (or connect to systems which store card data). For developers impacted by these requirements, it becomes critical that you secure the data, infrastructure, and code in your CDE.

![A diagram of a system scope for PCI DSS compliance]()

Minimizing scope is key to reducing the burden of PCI DSS compliance. By never handling plaintext card data, the number of controls that must be satisfied is significantly cut back, in many cases reduced by more than 90%. As a result, the attack surface for a card breach is minimized, and the effort to initially achieve and maintain compliance is simplified.

#### Reducing scope with Card Collection

Evervault allows you to safely collect and display cardholder data in the browser, without ever handling it in plaintext. Our UI Components are served within an iFrame retrieved directly from Evervault’s PCI-compliant infrastructure. All operations on card data, such as validity checks, occur within the Evervault environment.

Adopting this approach for collecting or displaying cardholder data can reduce your PCI DSS compliance scope to the simplest form (SAQ A Control Set for Merchants), once integrated correctly.

- [Card Collection](/cards/card-collection): Learn how to securely encrypt and collect cardholder data in the browser.
- [Card Reveal](/cards/reveal): Learn how to safely display encrypted cardholder data in the browser.

#### PCI restricted apps

If your app needs to comply with PCI, it will be designated as a PCI restricted app. This automatically applies additional security measures and features to your app, minimizing your PCI scope as much as possible.

- The Evervault Decrypt API is unavailable for PCI restricted Apps.
- Functions in PCI Restricted Apps undergo regular vulnerability scans.
- Allowlists can be set up to manage the sources and destinations of traffic within your PCI Function.
- PCI Functions have [fixed IP addresses](/more/faq#whitelisting-evervault-ips), ensuring third party traffic originates solely from Evervault’s secure infrastructure.
- Function response payloads are checked for any potential exfiltration of sensitive PCI data.
- Multi-Factor Authentication (MFA) is enabled by default on the Evervault Dashboard.

#### Additional security measures

Although using Evervault massively reduces your PCI scope, there are some additional security measures you need in place to ensure you are fully compliant. These include:

- Payment page web server patching and vulnerability scanning
- Secure Authentication and MFA
- Script and Code Dependency Inventory Management
- Third-Party Risk Management
- Incident Response Management

### Attestation of compliance

Once you have implemented the necessary controls and reduced your scope, you will need to complete the Attestation of Compliance (AoC) form. This is a document that can be shared with others as an attestation of your compliance with the PCI DSS. Depending on your level of compliance, this may need to be completed by a Qualified Security Assessor (QSA) or can be self-assessed.

## Ongoing compliance

PCI DSS compliance is an ongoing process. You will need to regularly review and update your security controls, conduct regular vulnerability scans, and complete the Attestation of Compliance (AoC) form annually.

### Automating compliance

Some of these ongoing processes can be automated with third-party or in-house tooling to reduce the burden on your team of remaining compliant.

#### Examples

- Using pre-built secure Terraform templates
- Automated patching
- Automated vulnerability scanning
- Automated exception remediation
- Integrated governance management systems like [Vanta](https://www.vanta.com/)


---

# HIPAA

_Learn the basics of HIPAA’s Privacy and Security Rules and how Evervault enables secure handling of e‑PHI._

The Health Insurance Portability and Accountability Act 1996 (**HIPAA**) is a US Federal Law, which required the creation of national standards to protect sensitive patient health information from being disclosed without the patient’s consent or knowledge. The HIPAA Privacy Rule implements the requirements of HIPAA, and the HIPAA Security Rule protects a subset of information covered by the Privacy Rule — Electronic Protected Health Information (e-PHI).

## Privacy rule

Organizations covered by the Privacy Rule typically include:

- Healthcare Providers
- Health Plan Providers
- Healthcare Clearing Houses
- Business Associates (Service Providers to the above)

A major goal of the Privacy Rule is to make sure that individuals’ health information is properly protected while allowing the flow of health information needed to provide and promote high-quality healthcare, and to protect the public’s health and well-being. The Privacy Rule permits important uses of information while protecting the privacy of people who seek care and healing.

## Security rule

While the HIPAA Privacy Rule safeguards PHI, the Security Rule protects a subset of information covered by the Privacy Rule. This subset is all individually identifiable health information a covered entity creates, receives, maintains, or transmits in electronic form. This information is called Electronic Protected Health Information, or e-PHI. The Security Rule does not apply to PHI transmitted orally or in writing.

To comply with the HIPAA Security Rule, all covered entities must:

1. Ensure the confidentiality, integrity, and availability of all e-PHI
2. Detect and safeguard against anticipated threats to the security of the information
3. Protect against anticipated impermissible uses or disclosures that are not allowed by the rule
4. Certify compliance by their workforce

Encryption plays a critical role in addressing points 1, 2, and 3, and organizations would be wise to implement both encryption in transit and at rest to protect personally identifiable sensitive personal health information.

Evervault is formally designated as a covered entity, and is externally assessed for compliance to HIPAA as part of our SOC 2 Type 2 Assessment (documentation available on request). Using Evervault allows organizations to securely store, process, and share sensitive health data using robust encryption schemes.


---

# GDPR

_Understand GDPR principles, categories of personal data, and how Evervault helps protect sensitive information._

The General Data Protection Regulation (GDPR) (EU) 2016/679 is a regulation on data protection and privacy for all individuals within the European Union. It came into force across the European Union on May 25th 2018.

The GDPR regulation is widely regarded as one of the toughest Privacy regulations in the world, particularly given its fines for non-compliance (4% of global revenues or €20m, whichever is higher) and its implications across nearly all aspects of business, inside and outside Europe. Any organization is in scope for GDPR if they handle the personal data of an EU citizen.

The GDPR splits in-scope parties into two main groups: Data Processors and Data Controllers, each with corresponding responsibilities.

- **Data Controller**: The person or entity which determines the purposes and means of the processing of personal data.
- **Data Processor**: A third party that processes personal data on behalf of a data controller.

There are 7 primary principles relating to data handling which are defined by GDPR. Although we will focus on number 6, which is one of the most challenging to implement, the other elements also require a robust company-wide program in order to comply.

1. Lawfulness, fairness, and transparency
2. Purpose limitation
3. Data minimization
4. Accuracy
5. Storage limitation
6. Integrity and confidentiality (security)
7. Accountability

## Integrity and confidentiality (security)

This Principle requires that data processing maintains appropriate security, integrity, and confidentiality. To expand on this, let's explain what data comes under GDPR scope.

GDPR defines two categories of personal data based on their perceived risk and sensitivity:

- Personal Data
  - Name
  - Address
  - Date of birth
  - Financial information
  - Email address
  - IP address
- Special Category Data
  - Racial or Ethnic Origin
  - Political Opinions
  - Religious or Philosophical Beliefs
  - Trade Union Membership
  - Genetic Data and Biometric Data
  - Health Data
  - Sex Life and Sexual Orientation Data

Special Category Data should always be secured with strong cryptography. GDPR considers robust encryption as an Appropriate Technical and organizational Measure.

Evervault Encryption can be used for Special Category information, while allowing processing of that in secure environments (using Evervault [Functions](/functions) or [Enclaves](/enclaves)). This allows Special Category Data to be processed in public clouds, while still preventing Cloud Service Providers or malicious individuals gaining access to the sensitive information.


---

# API Keys

_Learn how to create, scope, rotate, and revoke Evervault API keys to securely authenticate API and SDK requests._

Evervault provides a secure and easy-to-use authentication mechanism for APIs using API keys. These keys authenticate API requests by passing them in HTTP headers or as a parameter to the Evervault SDKs.

API keys can be created and managed on a per-app basis in the Evervault Dashboard, and can be scoped to control access to specific resources and services, ensuring that your API keys only have access to the resources they need.

## Create an API key

To create an API key, follow these steps:

1. Sign in to the [Evervault dashboard](https://app.evervault.com).
2. Go to the **app settings -> API Keys**.
3. Click **Create Key**.
4. Select the actions and resources you want the API key to have access to.
5. Click **Save**.
6. Store the API key securely in your application.

> The plaintext value of an API key is only shown once when it's created.
>   It's essential to store and manage them securely to ensure the integrity of
>   your Evervault account.

## Manage existing API keys

API keys can be updated and revoked in the Evervault dashboard. This allows you to ensure that your API keys are secure and that they only have access to the resources they need. To update an API key, follow these steps:

1. Sign in to the [Evervault dashboard](https://app.evervault.com).
2. Go to the **app settings -> API Keys**.
3. Click on the dropdown menu next to the API key you want to update.
4. Select the actions and resources you want the API key to have access to.
5. Click **Save**.

## Revoke an API key

API keys can be revoked in the Evervault dashboard. This allows you to ensure that your API keys are secure and that you only have the keys you need. To revoke an API key, follow these steps:

1. Sign in to the [Evervault dashboard](https://app.evervault.com).
2. Go to the **app settings -> API Keys**.
3. Click on the dropdown menu next to the API key you want to revoke and click **Delete**.
4. Enter the name of the API key to confirm the deletion.

## Rotate an API key

To maintain the security of your Evervault account, it's important to regularly rotate your API keys. To rotate a key, you can create a new API key with the same permissions as the old key. Once the new key is in use, you can remove the old key from your account. This ensures that any potential security vulnerabilities associated with the old key are eliminated, while still allowing your application to function properly with a new key.

## Keeping your API keys secure

API keys should be kept safe to prevent unauthorized access to sensitive resources and services, and to maintain the security and integrity of your Evervault account.

Here are some tips on how to keep your API keys safe:

- Don't share your API keys: API keys are sensitive and shouldn't be shared with anyone. Keep them secure and only provide access to those who need it.
- Store API keys securely: store your API keys in a secure location, such as a password manager, and never store them in plain text or in public repositories.
- Rotate API keys regularly: regularly rotate your API keys, especially if they have been compromised or if access is no longer required.
- Restrict API key access: limit access to your API keys by scoping them to specific resources and services. This ensures that they only have access to the resources they need.
- Don't embed API keys directly in code: embedding API keys directly in code, such as in configuration files, can make them more vulnerable to exposure. Instead, use environment variables or a configuration file that's not included in version control to store and manage your API keys.


---

# Logs

_Filter and search Evervault logs in the dashboard using Evervault Query Language (EQL) syntax and operator-based expressions._

Any time you send a request to an Evervault resource, a log of the request and response will be created inside of your app. You can use the Logs view in the [Evervault Dashboard](https://app.evervault.com) to view and filter these log events.

## EQL

Logs can be queried using the Evervault Query Language (EQL), which allows you to filter logs based on their attributes.

```text
// e.g., EQL query to find all logs with a relay category and response
// status code of 400 or higher
category="relay" AND response.status>=400
```

## Operators

The following operators are supported in EQL queries, but not every operator is available for every field. See the [searchable fields](#searchable-fields) section below for details.

| Operator | Meaning | Example |
| --- | --- | --- |
| `=` | Exact match | `request.method="POST"` |
| `!=` | Not equal | `function.status!="success"` |
| `>` | Greater than | `response.status>399` |
| `<` | Less than | `response.status<500` |
| `>=` | Greater than or equal to | `response.status>=400` |
| `<=` | Less than or equal to | `response.status<=299` |
| `:` | Contains | `url.path:"/checkout"` |

## Compound queries

You can combine filters with `AND` when all conditions must match, `OR` when any condition can match, and parentheses to group conditions.

```text
// AND: all conditions must match
category="relay" AND response.status>=400

// OR: any condition can match
request.method="POST" OR request.method="PUT"

// Grouped: control evaluation order
(category="function" AND function.status="failure") OR response.status>=500
```

## Searchable fields

| Field | Operators |
| --- | --- |
| `log.id`<br />The unique identifier of the log. | `=`, `!=` |
| `resource.id`<br />The ID of the Evervault resource. | `=`, `!=` |
| `category`<br />The event category. | `=`, `!=` |
| `request.method`<br />The request method used in the HTTP request. | `=`, `!=` |
| `response.content_type`<br />The content type of the response. | `=`, `!=` |
| `request.headers`<br />The headers sent in the HTTP request. | `=`, `:`, `!=` |
| `request.body`<br />The body of the HTTP request. | `=`, `:`, `!=` |
| `response.status`<br />The status code of the HTTP response. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `response.headers`<br />The headers sent in the HTTP response. | `=`, `:`, `!=` |
| `response.body`<br />The body of the HTTP response. | `=`, `:`, `!=` |
| `request.content_type`<br />The content type of the request. | `=`, `!=` |
| `url.full`<br />The full URL requested. | `=`, `:`, `!=` |
| `url.domain`<br />The domain part of the URL. | `=`, `!=` |
| `url.path`<br />The path part of the URL. | `=`, `:`, `!=` |
| `url.query`<br />The query string part of the URL. | `=`, `!=` |
| `url.port`<br />The port part of the URL. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `function.id`<br />The unique identifier of the function. | `=`, `!=` |
| `function.run_id`<br />The unique identifier of the function run. | `=`, `!=` |
| `function.name`<br />The name of the function. | `=`, `!=` |
| `function.log`<br />The log output of the function. | `=`, `:`, `!=` |
| `function.status`<br />The status of the function. | `=`, `!=` |
| `function.initialisation.duration`<br />The duration of the function initialisation. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `function.duration`<br />The duration of the function. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `crypto.fields.encryptCount`<br />The number of fields encrypted. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `crypto.fields.decryptCount`<br />The number of fields decrypted. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `crypto.files.encryptCount`<br />The number of files encrypted. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `crypto.files.decryptCount`<br />The number of files decrypted. | `=`, `!=`, `>`, `<`, `>=`, `<=` |
| `network_token.id`<br />The unique identifier of the network token. | `=`, `!=` |
| `3ds.id`<br />The unique identifier of the 3D Secure session. | `=`, `!=` |
| `3ds.status`<br />The status of a 3D Secure session. | `=`, `!=` |
| `3ds.authentication_flow`<br />The authentication flow used in the 3D Secure session. | `=`, `!=` |
| `3ds.card.last_four`<br />The last four digits of a card number. | `=`, `!=` |
| `3ds.card.funding`<br />The card funding type. | `=`, `!=` |
| `3ds.card.issuer`<br />The issuer of the card. | `=`, `!=` |
| `3ds.card.country`<br />The country the card is issued in. | `=`, `!=` |
| `3ds.card.currency`<br />The currency of the card. | `=`, `!=` |
| `3ds.card.segment`<br />The card segment. | `=`, `!=` |
| `3ds.payment_type`<br />The type of payment. | `=`, `!=` |
| `3ds.card.brand`<br />The brand of the card. | `=`, `!=` |
| `3ds.initiator`<br />The initiator of the 3D Secure session. | `=`, `!=` |
| `3ds.version`<br />The version of the 3D Secure protocol used. | `=`, `!=` |


---

# Observability

## Datadog integration

![Datadog logo]()

Your Evervault resources can be connected to Datadog via the Datadog integration. Datadog compatible log and metrics sync from the selected resources in real time. You can enable the Datadog integration for your team inside of the team settings in the [Evervault dashboard](https://app.evervault.com).

Enabling the Datadog integration presents you with a drawer to enter your API key and the Datadog site to forward your logs to. You can enable and disable the Datadog integration at a per resource level. API keys can be generated in the Datadog dashboard under the **Organization Settings** heading.

Evervault will submit a log to verify the integration. This log can be ignored.

### Logs and metrics

To start syncing logs and metrics from your Evervault resources to Datadog, you need to connect your Datadog account to your Evervault account.

1. Create a [Datadog API key](https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens).
2. Go to the [Evervault Dashboard](https://app.evervault.com) and navigate to your teams settings.
3. Select **Integrations** and enable the Datadog integration.
4. Follow the instructions to connect your Datadog account to your Evervault account.

Logging data will start streaming to Datadog from your selected Relays, Enclaves, and Functions. [Statsd](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) metrics will also be published from Enclaves to Datadog.

### Enclave metrics

The following list of stats will be sent to Datadog if the integration is enabled for an Enclave:

```
evervault.enclaves.cpu.one
evervault.enclaves.cpu.cores
evervault.enclaves.encrypt.count
evervault.enclaves.decrypt.count
evervault.enclaves.memory.avail
evervault.enclaves.memory.total
```

The stats can be queried with `host:<enclave_name>-*` or `enclave_uuid:<enclave_uuid>`.


---

# Data policies

_Define fine‑grained rules for when and where encrypted data may be decrypted using Evervault data roles and policies._

![A visual representing a data policy granting access to a piece of encrypted data]()

Data policies are rules that govern the conditions under which specific pieces of encrypted data can be decrypted. These policies are fine-grained and can be created to explicitly permit or forbid decryption, depending on the context of the decryption. These policies are embedded in the encrypted data at the time of encryption, ensuring that the data itself understands where and when it can be decrypted.

Here are some examples of what data policies can be used for:

- Permit decryption of OAuth tokens using Relay to a specific destination
- Permit decryption of data by a given Evervault Function
- Permit decryption of data by an IP address
- Permit decryption for a specific amount of time
- Permit decryption for a specific revision of an Enclave using PCRs

## Data roles

Data roles are an abstraction for a category of data. They can be attached to a piece of data at encryption time, allowing for granular control over how that data can be decrypted in the future. Each data role has a corresponding set of decryption policies that specify how data tagged with that role can be decrypted. These policies are evaluated at decryption time and determine whether or not a particular piece of data can be decrypted given the current context.

Data roles can be managed in the Evervault Dashboard through the **Data Policies** section. Roles must be created in the dashboard before they can be associated with individual data elements.

![Data policies embedded inside of a data role which is then attached to a piece of encrypted data.]()

### Assign policies to a role

Data policies are attached to specific roles and can be managed via the Evervault Dashboard. In contrast to data roles, which become fixed once embedded in encrypted data, policies remain changeable. This flexibility accommodates the evolution of data usage scenarios over time, allowing for adaptations that may differ from initial use cases.

### Attaching a role to a piece of data

A data role is attached to data during the encryption process. The data role is embedded into the encrypted data along with important metadata. Attaching a data role to data can be done in a few different ways based on how you’re using Evervault to encrypt your data.

#### Attaching roles using Relay

A data role can be assigned to values encrypted using Relay. A data role can be specified when adding a field to encrypt to your Relay configuration.

[Learn more about how to encrypt data with Relay](/relay)

#### Attaching roles using the Encrypt API

A data role can be provided when encrypting a value using the Encrypt API. The data role slug can be provided using the `X-Evervault-Data-Role` header.

```bash
curl https://api.evervault.com/encrypt -u <app_id>:<api_key>
	-H 'X-Evervault-Data-Role: <data_role_slug>'
	-H 'Content-Type: application/json'
	-d '"Hello World!"'
```

[Learn more in the API reference](/api#encrypt).

#### Attaching roles in an Enclave

A data role can be provided when encrypting a value using the Encrypt endpoint within your Enclave. The data role slug can be provided using the `X-Evervault-Data-Role` header.

```bash
curl http://127.0.0.1:9999/encrypt
	-H 'X-Evervault-Data-Role: <data_role_slug>'
	-H 'Content-Type: application/json'
	-d '"Hello World!"'
```

[Learn more about encrypting data in an Enclave](/enclaves#encrypt).

#### Attaching roles using the SDK

A data role can be provided when encrypting a value using one of Evervault’s SDKs. The data role slug can be passed as an argument to the `encrypt` function.

```javascript
const evervault = new Evervault("<APP_ID>", "<API_KEY>");
evervault.encrypt("Hello World!", "<data_role_slug>");
```

[Learn more in the SDK references](/sdks).

## Policies evaluation

When decrypting data linked to a specific role, the associated policies for that role are retrieved. These policies are assessed in the following manner:

1. The policies are individually examined, and decryption is immediately rejected if any policy contains a rule that explicitly prohibits it.
2. In the absence of any explicit denial, the presence of at least one policy that explicitly authorizes decryption will result in decryption being permitted. Without such explicit permission, decryption is not allowed.


---

# Webhooks

_Subscribe to Evervault webhook events to receive real‑time notifications for actions like 3DS results, token updates, and deployments._

Webhook events are notifications triggered by specific operations to which you can subscribe, allowing you to be alerted when those operations occur. These events might include scenarios such as a network token being updated, a successful 3DS session, or the completion of a function deployment. Each event is categorized by a type that defines the nature of the event, along with associated data relevant to that event.

## Webhook Event object

When an event is triggered, Evervault creates a new Event object, which is sent to your Webhook Endpoint as a JSON payload. This payload includes the following fields:

- `id`: A unique identifier for the event.
- `type`: The type of event that occurred.
- `data`: Event specific data.
- `createdAt`: The timestamp when the event was created.

You can see a full list of webhook events in the [API Reference](/api#webhook-events).

## Getting started

To start receiving webhook events, you need to set up an API endpoint within your infrastructure that can handle POST HTTP requests and process JSON objects. This endpoint must return a 2XX HTTP status code upon successfully completing the event processing.

```javascript
const express = require("express");
const app = express();

app.use(express.json());

// Webhooks endpoint
app.post("/evervault", (req, res) => {
  const webhookEvent = req.body;

  switch (webhookEvent.type) {
    case "payments.network-token.updated":
      // Process the Network Token update
      break;
    // Handle other event types
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  // Respond with HTTP status 200
  res.status(200).send({ success: true });
});

// Start the server
app.listen(3000, () => console.log("Running on port 3000"));
```

### Secure your webhook endpoint

All webhook event requests are signed using a secret key, allowing you to verify that the event was sent by Evervault. Each request includes a JSON Web Token (JWT) in the `X-Evervault-Signature` header, which you can use to authenticate the request. To do this, compare the signature provided in the header with a signature you generate locally using the payload and endpoint URL.

The signature is created by generating a SHA-256 hash of the body of the request. This hash, along with the endpoint URL, is then signed using the ES256 algorithm (ECDSA with a P-256 curve) and a private key. To verify this signature, use the corresponding public key, which you can retrieve from Evervault’s JSON Web Key Set (JWKS) endpoint.

Below is an example of how to verify an Evervault webhook signature using JavaScript. For optimal performance, it’s recommended to cache the JWKS instead of fetching it with each request.

```javascript
const { createRemoteJWKSet, jwtVerify } = require("jose");
const crypto = require("crypto");

// Function to verify Evervault webhook
async function verifyWebhook(req) {
  try {
    // Convert the request body to a JSON string
    const jsonStr = JSON.stringify(req.body);

    // Retrieve the JWT signature from the request headers
    const jwt = req.headers["X-Evervault-Signature"];

    // Reconstruct the SHA-256 hash of the request body
    const reconstructedBodySha256 = crypto
      .createHash("sha256")
      .update(jsonStr)
      .digest("base64");

    // Reconstruct the full endpoint URL
    const reconstructedEndpointUrl = `${req.protocol}://${req.get("host")}${
      req.originalUrl
    }`;

    // Fetch the JWKS (JSON Web Key Set) for webhook verification
    const JWKS = createRemoteJWKSet(
      new URL("https://api.evervault.com/jwks/webhooks.json")
    );

    // Verify the JWT using the JWKS
    const { payload } = await jwtVerify(jwt, JWKS);
    const { bodySha256, endpointUrl } = payload;

    // Validate the reconstructed body hash and endpoint URL against the JWT payload
    if (
      reconstructedBodySha256 !== bodySha256 ||
      reconstructedEndpointUrl !== endpointUrl
    ) {
      throw new Error("Body or endpoint URL could not be verified");
    } else {
      console.log("Webhook verified!");
    }
  } catch (error) {
    console.error("Webhook verification failed.", error);
    throw error;
  }
}

// Example usage of the verifyWebhook function
await verifyWebhook(req);
```

### Register your webhook endpoint

After deploying your new endpoint, you can register it as a webhook endpoint with Evervault through either the [Dashboard](https://app.evervault.com) (**Settings > Webhooks**) or the [Evervault API](/api). You’ll need to subscribe this endpoint to the specific events you wish to receive. Once subscribed, Evervault will send those events to the registered endpoint whenever they occur for your app.

## Webhook event delivery

Webhook events are delivered to a webhook endpoint via a POST request over HTTPS. The request includes a `Content-Type` header set to `application/json`. A webhook event is deemed successfully delivered when the Webhook Endpoint responds with a 2XX HTTP status code.

Single delivery is not guaranteed, and in rare cases, a eebhook event may be delivered more than once. To handle potential duplicates, you can use the `id` field in the event payload to identify and filter out duplicate events.

You can register a webhook endpoint either through the [Evervault dashboard](https://app.evervault.com) or via the [Evervault API](/api). An Evervault app can have multiple webhook endpoints registered, with each endpoint subscribed to a specific set of events.

### Retries

If the webhook endpoint does not respond with a 2XX status code, Evervault will automatically retry sending the event using an exponential backoff strategy, gradually increasing the delay between each retry. This process continues until the event is successfully delivered or until 5 days (120 hours) have passed. If the event cannot be delivered within this timeframe, it will be permanently discarded.

### Monitoring

You can monitor Webhook Event deliveries through the [Evervault Dashboard](https://app.evervault.com), under the Logs tab. The logs include detailed information about each event, such as timestamps and status codes, enabling you to quickly diagnose and address delivery issues.


---

# Sandbox

_Use Sandbox Apps to test and simulate Evervault features safely with isolated environments that mirror production behavior._

Evervault's Sandboxes provide isolated environments for testing and validating configurations without affecting production. Unlike regular apps, they grant access to all [Platform](https://evervault.com/pricing) features, enabling advanced testing. Sandboxes include specialized tools like [simulating card updates](/cards/card-account-updater#testing), [Apple Pay sandbox testing](/cards/apple-pay#testing-sandbox), and triggering webhook events to refine integrations before going live. This ensures development and production stay separate, protecting production data while fully utilizing Evervault's features for comprehensive testing.

Encrypt and decrypt actions are tied to app keys. Any data you encrypt with a sandbox app can only be decrypted with that same app key. This helps preserve the separation between sandbox and production apps (data can't accidentally be encrypted or decrypted across them).

## Sandbox vs. Production

| Sandbox | Production |
| --- | --- |
| Designed for testing, experimentation, and validation in a safe environment. Ideal for testing new features and integrations and evaluating Platform features (e.g., 3D Secure, Card Account Updater, etc.). | Used for live business operations, handling real user data, and ensuring the reliability and performance of your services. |
| Data and metrics are isolated from production, ensuring that test results do not affect live data or operations. | Handles real-world data with no cross-contamination from test environments, ensuring accurate analytics and reporting. |
| Full range of Evervault features, including Platform features, are available for thorough testing and evaluation. | Evervault products and any Platform features that have been enabled on your account. |
| Minimizes risk by isolating errors, bugs, and issues within the sandbox environment, preventing them from affecting production. | Focuses on minimizing downtime and ensuring that changes are thoroughly tested before deployment to maintain high reliability. |

## Creating a sandbox app

You can create a sandbox app from within the [Evervault Dashboard](https://app.evervault.com/apps) by checking the **Sandbox mode** checkbox when creating a new app. You can open the app create modal by opening the app switcher dropdown and selecting **+ New App**.

![A screenshot of the app creation modal with the sandbox mode checkbox checked.]()

## Best practices when using sandbox apps

Sandboxes retain the full suite of functionalities available in a production environment. This feature-rich setup allows you to replicate your production environment precisely, enabling thorough testing and validation. However, to maximize the benefits of using sandboxes, consider the following best practices:

1. Separate testing and production data: always use a sandbox to test changes, ensuring that your production configuration and data remain untouched. This separation prevents any accidental data corruption or configuration issues in your live environment.
2. Test with confidence: use the sandbox environment to test any changes or updates thoroughly. By doing so, you can confidently apply these changes to your production environment, knowing they've been vetted in an isolated environment.
3. Mirror production configurations: when creating a sandbox, mirror your production environment as closely as possible. This practice ensures that the testing outcomes are reliable and applicable to your live environment.
4. Naming conventions: Use consistent naming conventions to clearly differentiate between your sandbox and production environments. This practice aids in avoiding confusion when switching between apps.
5. Replicate and deploy: after testing and validating your configurations in your sandbox, replicate the settings to your app. This approach minimizes downtime and ensures a smooth transition from testing to production.

By following the outlined practices and leveraging sandboxes effectively, you can ensure a smooth, risk-free development process while maintaining the integrity of your production environment. As Evervault continues to evolve, sandboxes remain a cornerstone for testing and evaluating new features, giving you the confidence to innovate without hesitation.


---

# Evervault Encryption

_An overview of the Evervault Encryption Engine (E3), key management, and ciphertext format used across all products._

Evervault Encryption is the encryption scheme used across all of Evervault's products. All key management and cryptographic operations take place within the Evervault Encryption Engine (E3) which runs exclusively in an [AWS Nitro Enclave](https://aws.amazon.com/ec2/nitro/nitro-enclaves/).

By default, any data that you encrypt with any Evervault product can all be decrypted and used by all of our other products. For example, you could collect credit card data from your customers using [Card Collection](/cards/card-collection) and then perform credit card verification using [Functions](/functions) — without any additional configuration.

Evervault takes on the responsibility for managing your encryption keys so you don't need to worry about storing them safely. We also manage key rotation and provisioning on your behalf with no additional configuration.

If your infrastructure is compromised, simply rotate your API token in the Evervault Dashboard and we'll take care of the rest. Your API token doesn't contain any sensitive key material and is only used to authenticate with the Evervault Encryption Engine.

## Evervault Encryption Engine (E3)

At the core of Evervault is the Evervault Encryption Engine (E3). All cryptographic operations for our hosted products (Functions, Enclaves, Relay, and UI Components) take place in E3.

E3 is built on AWS Nitro Enclaves. Nitro Enclaves are Secure Enclaves backed by isolated, hardened, and highly constrained virtual machines.

Using enclaves means that Evervault cannot access your data. Enclaves have no persistent storage, no interactive access, and no external networking. Root users and admin users on the parent EC2 instance cannot access or SSH into the enclave. The only way to communicate with the enclave is through the secure local channel from the parent EC2 instance attached to the enclave.

Enclaves have attestation for verifying that only authorized code is running in the enclave, and to verify the enclave's identity. Key material is only passed to E3 if it passes all attestation checks. Similarly, all other products will only interact with a fully-attested deployment of E3.

## Evervault Encryption Scheme

### Encryption keys

The current Evervault Encryption Scheme (EES) comprises two sets of keys: the App Master Key, and a public/private asymmetric key pair.

#### App Master Key (AMK)

When an Evervault App is created, an App Master Key (AMK) is provisioned for that App.

Each AMK is generated for use with AES-256 symmetric encryption (with a 256-bit key length).

We use Shamir's Secret Sharing to split the AMK into three shares with a quorum of three. Of these three shares, two are stored in separate databases on Evervault's infrastructure — encrypted using a key that is only accessible by E3's AWS Nitro Enclave. Once these shares have been generated, the original AMK is discarded.

Your API token is generated by taking the third share and offsetting it by XORing each byte of the share with randomly generated "offset bytes", which are stored by Evervault.

Evervault stores the API token encrypted in its database using AWS KMS to allow you to retrieve it using the Dashboard. Each access request is tracked and there is a full audit log of each API token decrypt operation.

#### App Asymmetric Keypair

Two Elliptic Curve Diffie-Hellman keypairs are generated for each App: one on the `secp256r1` curve (NIST P-256) and one on the `secp256k1` curve (Koblitz). Two keys are used in order to allow for complete interoperability with different encryption libraries, many of which will only support a subset of all standardized elliptic curves.

The private key is encrypted with the App's AMK (using AES-256), and the plaintext private key is discarded.

The AMK-encrypted private key is stored in the Evervault database. Evervault never sees the private key in plaintext. The only point where the private key is accessible is within the E3 AWS Nitro Enclave.

The public asymmetric key is stored in the Evervault database and is publicly available for any clients who wish to encrypt data to be processed by your App.

### Encryption

Your App's ECDH public key is loaded by the Evervault SDK or by E3, which generates a new, ephemeral ECDH keypair per encryption. The SDK or E3 then derives a 32-byte (256 bit) shared secret using the App ECDH public key and the ephemeral ECDH private key.

The data is then encrypted using `AES-256-GCM` with a 12-byte initialization vector (IV) and 16-byte auth tag. A string is generated containing the ephemeral ECDH public key, AES-encrypted data, and the key IV.

The plaintext AES key and the ephemeral ECDH private key are discarded.

The encrypted data returned by the Evervault SDK or E3 can then be stored anywhere on your infrastructure. Evervault does not store the data in any form—neither in plaintext, nor encrypted.

Evervault-encrypted data is encoded using the following structure:

```text
ev:Base64(Version):[datatype:]Base64(KeyIV):Base64(ECDHPublicKey):Base64(AESEncryptedData):$
```

| Parameter | Description |
| --- | --- |
| ev | Used so that you can easily identify Evervault-encrypted strings. |
| Version | Evervault encryption version, e.g., RFVC or Tk9D. |
| datatype | Allows you to easily identify the type of data that was encrypted. |
| KevIV | Randomly-generated Base64-encoded Initialization Vector used for AES |
| ECDHPublicKey | Base64-encoded representation of the ephemeral ECDH session public key that was used to derive the shared secret AES key for the particular string. |
| AESEncryptedData | The original data that has been encrypted by AES-256-GCM using the randomly generated key. |

Our data structure is designed so that you don't need to change your database configuration or models. You can store Evervault-encrypted data in your database as you would the plaintext data.


---

# SAML

_Configure SAML SSO for Evervault teams on custom plans, including prerequisites and IdP attribute mapping._

Teams on a custom plan can configure SAML authentication for their team.

By default, users who sign in through their organization's SAML connection are granted **Viewer** membership. To elevate their permissions, a team admin must adjust their role via the **Team Settings** page in the Evervault Dashboard.

> SAML is only available for teams on custom plans. Please [contact
>   support](mailto:support@evervault.com) to enable SAML for your team.

## Prerequisites

The user configuring SAML from the Evervault Dashboard must be a team admin. You will also need admin access to your IdP to complete the setup from the provider.

> By default, the email domain of the admin configuring SAML is allowlisted as a
>   discovery realm. To add further domains please contact Evervault support.

## Setup

1. Navigate to **Team Settings -> Security** in the Evervault Dashboard.
2. Click the **Configure** button next to **Single sign-on (SAML)** to begin configuring your SAML connection.

### Okta

1. Use the SAML connection details from the Evervault Dashboard to create the connection within Okta.

![A screenshot of the Evervault SAML Config]()

2. Evervault requires that your IdP maps the account's email into the app attribute `email`. To configure this in Okta, navigate to `Sign On` -> `SAML Attributes` -> `Profile attribute statements`. Set the `email` attribute to the value `user.email`.

![A screenshot of the Okta SAML attribute mapping]()

3. Return to the Evervault Dashboard's **Security** page. Input the Okta-generated sign-in URL and x509 certificate. The certificate may be in .PEM or .CER format. If you enable sign-out, you must also provide the Okta-generated sign-out URL.

### Google

1. Input your SAML sign-in URL and upload your IdP's x509 cert in .PEM or .CER format. Optionally you can enable sign-out and provide a sign-out URL.
2. Press the **Create SAML Connection** button. After the Connection has been created successfully, you will see a "Configured" badge next to SAML settings.
3. Press the **Setting** button to view your Connection's metadata.
4. Evervault only requires a single SAML attribute mapping. To configure this, set the mapping of **Primary email** to the app attribute `email`. Below is an example of what this looks like when using Google as an IdP.

![A screenshot of the Google SAML attribute mapping]()

## IdP-initiated sign-in

IdP-initiated sign-in is disabled by default, and users must start the SAML flow from the Evervault Dashboard. If you need to support an IdP-initiated flow, [contact our support team](mailto:support@evervault.com).


---

# Migrating off Evervault

_If you leave Evervault, we provide a free, attestable decryption service to safely export your encrypted data._

If there ever comes a time you wish to stop using Evervault, we will provide a free service for you to decrypt all of your data.

You will be provided with a CSV template to insert encrypted data into, which can then be uploaded to the decryption service. This migration service is built on [Enclaves](/enclaves), so you can cryptographically attest that Evervault is unable to access or tamper with the data in any way.

## Decryption process

- An [Enclave](/enclaves) specifically designed for exporting data securely will be added to your account.
- The Decryption Enclave exposes two authenticated endpoints:
  - `/upload`: accepts a CSV of encrypted data, along with a key for re-encryption.
  - `/download`: returns a download of the decrypted data, which has been re-encrypted with the provided key (or a progress percentage on the decryption if it hasn’t finished).
- On startup, the Decryption Enclave is given a special API key which allows it to request the team’s private-key from E3.
- Once you have uploaded your data, the Decryption Enclave will use the private key to decrypt the data in the CSV, then re-encrypt the CSV with the provided key.
- You can then poll the /download endpoint until it succeeds, returning the decrypted data, which has been encrypted with the key provided.


---

# Integrations

_Connect Evervault with Datadog and Vanta to stream logs, metrics, and user data for monitoring and compliance._

## Datadog

![Datadog logo]()

Your Evervault resources can be connected to Datadog through your team settings in the Dashboard. Datadog compatible log and metrics sync from the selected instances in real time. Learn more about setting up the Datadog integration in our [observability guide](/developers/observability#datadog-integration).

## Vanta

![Vanta logo]()

The Evervault Vanta integration syncs your Evervault team's users into Vanta. You can then use this information to provide evidencing to auditors. To start syncing users, enable the integration from the **Team Settings** page:

1. Go to the [Evervault Dashboard](https://app.evervault.com) and navigate to your **Teams Settings** page.
2. Click **Integrations** and enable Vanta.
3. Follow the instructions to connect your Vanta account to your Evervault account.


---

# FAQ

_Questions frequently asked by our customers_

These are some questions we are frequently asked by our customers.

## Encryption

Below you'll find questions related to encrypting data.

### What encryption scheme does Evervault use?

You can learn more about the Evervault Encryption Scheme (EES) [here](/developers/evervault-encryption).

### Do I need to manage encryption keys?

No. Simply include our [SDKs](/sdks) and Relay your data or deploy your functions to an [Evervault Function](/functions). We handle everything else.

### Why is Evervault better than encryption at rest and in transit?

Encryption in transit (using TLS) protects against man-in-the-middle attacks between the client and your server.

Encryption at rest (at the disk-level, file-system-level, and database-level) protects against someone taking the physical drive from your machine and overriding your file-system, and prevents a non-authenticated admin accessing your database.

However, neither encryption in transit or at rest protect against a malicious agent on your server because data still gets decrypted to be processed.

With Evervault, data never exists on your infrastructure in plaintext — so it can never be lost or leaked.

### Why is Evervault better than open-source encryption libraries?

There are two core reasons why Evervault is better than encryption libraries:

#### 1. No plaintext data on your infrastructure

With encryption libraries like Web Crypto and Tink, you still need to decrypt sensitive data to process and get value from it. With Evervault, sensitive data is never decrypted (i.e. never exists in plaintext) on your infrastructure—so you cannot lose or leak it.

#### 2. No need to manage encryption keys

With encryption libraries, you still need to manage encryption keys. Using Evervault means that you do not need to manage encryption keys. We take full responsibility for key management. The way we configure key management means that Evervault cannot decrypt your data—because your app’s API key is necessary for decryption.

## Storage

Below you'll find questions related to storing encrypted data.

### Where do I store data I encrypted with Evervault?

You store the data in your database as normal. There’s no need to change your data structure or format.

## Compliance

### Where can I find Evervault's compliance reports?

You can request access to our PCI DSS AoC and other assurance documents from our [Trust Center](https://trust.evervault.com).

## Roles

Below you'll find questions related to roles in your account.

### What are available roles within my account?

In your Pro account you will see a dropdown of available roles within your team. The available roles are “Admin”, “Developer”, and “Viewer.”

Each role varies in the permissions they have for reading, creating, deleting, and updating resources within an Evervault team account.

If you are an admin of a team you can make any other member an admin or adjust their role. You can also control resource and service access by using [Scoped API Keys](/developers/api-keys)

#### Admin

| Action | Read | Create | Update | Delete |
| --- | --- | --- | --- | --- |
| API Keys | ✅ | ✅ | ✅ | ✅ |
| Apps | ✅ | ✅ | ✅ | ✅ |
| Billing | ✅ | ❌ | ✅ | ❌ |
| Cards | ✅ | ✅ | ✅ | ✅ |
| Data roles | ✅ | ✅ | ✅ | ❌ |
| Enclaves | ✅ | ✅ | ✅ | ✅ |
| Functions | ✅ | ✅ | ✅ | ✅ |
| Invites | ✅ | ✅ | ✅ | ✅ |
| Merchants | ✅ | ✅ | ✅ | ✅ |
| Network tokens | ✅ | ✅ | ✅ | ✅ |
| Notifications | ✅ | ✅ | ✅ | ✅ |
| Relay | ✅ | ✅ | ✅ | ✅ |
| SAML connections | ✅ | ✅ | ✅ | ✅ |
| View team members | ✅ | ✅ | ✅ | ✅ |
| Teams | ✅ | ✅ | ✅ | ✅ |
| Third-party integrations | ✅ | ✅ | ✅ | ✅ |

#### Developer

| Action | Read | Create | Update | Delete |
| --- | --- | --- | --- | --- |
| API Keys | ✅ | ✅ | ✅ | ✅ |
| Apps | ✅ | ✅ | ✅ | ✅ |
| Billing | ❌ | ❌ | ❌ | ❌ |
| Cards | ✅ | ✅ | ✅ | ❌ |
| Data roles | ✅ | ✅ | ✅ | ❌ |
| Enclaves | ✅ | ✅ | ✅ | ✅ |
| Functions | ✅ | ✅ | ✅ | ✅ |
| Invites | ✅ | ❌ | ❌ | ❌ |
| Merchants | ✅ | ✅ | ✅ | ❌ |
| Network tokens | ✅ | ✅ | ✅ | ❌ |
| Notifications | ✅ | ✅ | ✅ | ✅ |
| Relay | ✅ | ✅ | ✅ | ✅ |
| SAML connections | ✅ | ❌ | ❌ | ❌ |
| View team members | ✅ | ❌ | ❌ | ❌ |
| Teams | ✅ | ✅ | ❌ | ❌ |
| Third-party integrations | ✅ | ❌ | ❌ | ❌ |

#### Viewer

| Action | Read | Create | Update | Delete |
| --- | --- | --- | --- | --- |
| API Keys | ❌ | ❌ | ❌ | ❌ |
| Apps | ✅ | ❌ | ❌ | ❌ |
| Billing | ❌ | ❌ | ❌ | ❌ |
| Cards | ✅ | ❌ | ❌ | ❌ |
| Data roles | ✅ | ❌ | ❌ | ❌ |
| Enclaves | ✅ | ❌ | ❌ | ❌ |
| Functions | ✅ | ❌ | ❌ | ❌ |
| Invites | ✅ | ❌ | ❌ | ❌ |
| Merchants | ✅ | ❌ | ❌ | ❌ |
| Network tokens | ✅ | ❌ | ❌ | ❌ |
| Notifications | ✅ | ❌ | ❌ | ❌ |
| Relay | ✅ | ❌ | ❌ | ❌ |
| SAML connections | ✅ | ❌ | ❌ | ❌ |
| View team members | ✅ | ❌ | ❌ | ❌ |
| Teams | ✅ | ❌ | ❌ | ❌ |
| Third-party integrations | ✅ | ❌ | ❌ | ❌ |

## Other

### Where are my Evervault API keys?

Your API keys can be found in [Settings](https://app.evervault.com). You can learn more on our dedicated [docs page](/developers/api-keys).

### Does the Evervault API have rate limits?

The Evervault API applies rate limits on incoming requests to safeguard stability and service reliability. Limits are enforced across these endpoints:

- [Encrypt](/api#encrypt)
- [Decrypt](/api#decrypt)
- [Functions](/api#createFunctionRun)
- [Fingerprint](/api#fingerprint)
- [BIN Lookup](/api#createBinLookup)
- [Real-time Account Updater Checks](/api#createAccountUpdaterCheck)
- [Real-time Account Updater Subscriptions](/api#createAccountUpdaterSubscription)

Requests exceeding the rate limit return a `429` status code. Rate limited requests aren't queued by Evervault, so you need to implement your own retry logic if required.

#### Rate limits by environment

Rate limits are set at 100 RPM for [Sandbox apps](/developers/sandbox) and 6000 RPM in production. If you need higher rate limits, contact [support@evervault.com](mailto:support@evervault.com).

#### How rate limiting works

Evervault uses a sliding window rate limiting model. This means requests are limited based on a rolling one minute window, rather than resetting at fixed intervals. Rate limit information is exposed in response headers on every request:

| Header | Example | Description |
| --- | --- | --- |
| `x-evervault-ratelimit` | `limit=6000, remaining=6000, reset=60` | The maximum number of requests allowed per window (`limit`), the number of requests left in the current window (`remaining`), the time (in seconds) until the window fully resets (`reset`). |
| `x-evervault-ratelimit-policy` | `6000;w=60;comment="sliding window"` | Describes the rate limit policy: maximum requests (6000), window length in seconds (w=60), and the method used. |

### I can decrypt data in Sandbox mode but not Production. What's wrong?

Encrypt and decrypt actions are tied to app keys. This means if you encrypt data using a sandbox app, you can't decrypt that data with your production app key. Data can only be encrypted and decrypted using the same app key.

## Whitelisting Evervault IPs

Evervault provides a set of static IP addresses which can be used to ensure requests are originating from our infrastructure.

In the case of Relay, the request IP will always be one of the below list. Requests from Functions do not use these IPs by default, but can be configured to do so. If you're interested contact us at [support@evervault.com](mailto:support@evervault.com) to get access.

If you need to modify an allowlist to accommodate these IPs, the following static IP addresses should be whitelisted to allow requests from Evervault:

```
34.199.158.122
52.48.156.228
54.161.131.154
54.216.126.127
168.100.164.1
168.100.164.2
168.100.164.3
168.100.164.4
168.100.164.5
168.100.164.6
168.100.164.7
168.100.164.8
168.100.164.9
168.100.165.1
168.100.165.2
168.100.165.3
168.100.165.4
168.100.165.5
168.100.165.6
168.100.165.7
168.100.165.8
168.100.165.9
```

### Is Evervault compliant?

Evervault are a PCI DSS Level 1 Service Provider and SOC 2 Type II compliant. We can enter into BAAs under HIPAA.
[Request our reports](mailto:compliance@evervault.com)

### Evervault's setup guide

As when using any cloud based application there are always areas where both the consumer and service provider will have to manage information security responsibilities. Evervault follows the traditional SaaS model for security responsibilities. Evervault are responsible for the systems used to deliver the proposed services, and the customer is responsible for the data you chose to put through our systems & how you interact with our systems.

Securing your credentials to access our platform is a critical step in protecting your environment. We have made several options available to enhance the security of access to the platform. It is up to you to ensure these are configured. In addition to standard good security hygiene, at a minimum Evervault suggest the following security good practice when using Evervault Securely:

#### Management plane access

- Implement an approval process for access and monitor account activity
- Allocate access on a least privilege basis
- Allocated credentials to individual users, do not share accounts
- Quickly Amend / Remove User Access when no longer required
- Frequently Review Access
- Store and Share Credentials and API keys Securely
- Rotate API Keys when administrator leaves
- Select robust hard to guess passwords
- Enable Multi-factor authentication
- Disable Accounts immediately if you suspect compromise and alert [support@evervault.com](mailto:support@evervault.com) for further support.
- Store your API key in a secure secrets manager application
- Configure logging and alerting to record any access to / unexpected activity involving the API key

#### Data plane (app.evervault.com)

- Constantly review the fields that you have chosen to encrypt to ensure they are adequate
- Constantly review the chosen destination end points for your encrypted and decrypted data flows
- Implement a change and approval process to authorise changes to destinations and fields
- Adhere to Evervault patch advisories if SDKs are in use


---

# Android

_Encrypt data client-side, collect card details & perform 3D Secure authentication._

The [Evervault](https://evervault.com/) Android SDK is a library for encrypting data and collecting credit cards data on Android Devices. It's simple to integrate, easy to use and it supports a wide range of data types.

## Features

- Core encryption capabilities for various data types.
- A secure and customizable PaymentCard Compose view.
- Built-in data type recognition and appropriate encryption handling.

## Supported Platforms

- Android (API Version 26-33)

## Quickstart

### Install SDK

Our Android SDK distributed via [maven](https://central.sonatype.com/search?q=com.evervault.sdk), and can be installed using your preferred build tool.

If you are installing `evervault-inputs` from version `2.0.0` and onwards you will also need to add the JitPack repository to your build file:

```kotlin
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
  }
}
```

#### Gradle DSL

```kotlin
implementation("com.evervault.sdk:evervault-core:1.2")
implementation("com.evervault.sdk:evervault-inputs:2.0.0")
implementation("com.evervault.sdk:evervault-enclaves:2.0.0")
```

#### Maven

```xml
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-core</artifactId>
  <version>1.2</version>
  </dependency>
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-inputs</artifactId>
  <version>2.0.0</version>
  </dependency>
<dependency>
  <groupId>com.evervault.sdk</groupId>
  <artifactId>evervault-enclaves</artifactId>
  <version>2.0.0</version>
  </dependency>
```

#### Initialize SDK

Before using the Evervault Android SDK, you need to configure it with your Evervault Team ID and App ID. This step is essential for establishing a connection with the Evervault encryption service.

```kotlin
Evervault.shared.configure("<TEAM_ID>", "<APP_ID>")
```

Make sure to replace `<TEAM_ID>` and `<APP_ID>` with your actual Evervault Team ID and App ID which can be found in the [Evervault Dashboard](https://app.evervault.com)

### Encrypting Data

Once the SDK is configured, you can use the `encrypt` method to encrypt sensitive data. The `encrypt` method accepts Java's primitive data types and an optional [role](/developers/data-policies)

Here's an example of encrypting a social security number:

```kotlin
val encryptedPassword = Evervault.shared.encrypt("123-12-1234")
```

A role defines an encryption policy to be applied to the return ciphertext. The `encrypt` function takes as an optional parameter `role` which is the `id` of the role created in your [Evervault App](https://app.evervault.com)

```kotlin
val encryptedPassword = Evervault.shared.encrypt("123-12-1234", 'role-id')
```

The `encrypt` method returns an `Any` type, so you will need to safely cast the result based on the data type you provided. For Boolean, Numerics, and Strings, the encrypted data is returned as a String. For Arrays, Lists and Maps, the encrypted data maintains the same structure but is encrypted (except that Arrays become Lists). For ByteArray, the encrypted data is returned as encrypted ByteArray, which can be useful for encrypting files.

### Decrypting 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](/sdks) or through our [REST API](/api).
The payload must be the same payload that was used to create the token and expires 10 minutes after creation.
The payload must be a map and the response is `Any` which can, and should be, cast to `Map<String, Any>`

```kotlin
val encrypted = Evervault.shared.encrypt("Super Secret Password")

val decrypted = Evervault.shared.decrypt(token, mapOf("data" to encrypted)) as Map<String, Any>
println(decrypted["data"]) // Output: "Super Secret Password"
```

## Inputs

The Evervault Android SDK also provides a Compose view called `PaymentCard`. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data. The `PaymentCard` view can be customized to fit your application's design.

Here's an example of using the `PaymentCard` composable:

```kotlin
UserParentLayout {
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    // ...
    PaymentCard(onDataChange = onDataChange) {
        // User custom payment card layout using the [PaymentCardInputScope] components with a combination of user own components and modifiers
    }
}
```

The encrypted credit card number and CVC are captured in the `PaymentCardData`, as well as the expiry month and year and validation fields.

### Styling

The `PaymentCard` and its components can be customized to fit your application's design. The view excepts a number of parameters that enable you to customize the modifier, text and placeholder styles. The `content` parameter accepts a `@Composable PaymentCardInputScope.()` function, which can be used to customize the view's layout. The `PaymentCardInputScope` components can be customized with a modifier (`Modifier`), label (`String` or `@Composable`), placeholder (`String` or `@Composable`), text style (`TextStyle`), and input field colors (`TextFieldColors`).

Two build-in layouts are provided:

#### Inline

- `InlinePaymentCard` (the default layout) - This layout displays the card number, expiry and CVC fields inline.

![Screenshot of the Android PaymentCard with Inline styling]()

```kotlin
@Composable
fun InlinePaymentCard(
    modifier: Modifier = Modifier,
    textStyle: TextStyle = TextStyle.Default,
    placeholderTexts: PlaceholderTexts = PlaceholderDefaults.texts(),
    placeholderTextStyle: TextStyle = textStyle.copy(color = MaterialTheme.colorScheme.secondary),
    onDataChange: (PaymentCardData) -> Unit = {}
)
```

#### Rows

`RowsPaymentCard` - Displays the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.

![Screenshot of the Android PaymentCard with Rows styling]()

```kotlin
@Composable
fun RowsPaymentCard(
    modifier: Modifier = Modifier,
    textStyle: TextStyle = TextStyle.Default,
    placeholderTexts: PlaceholderTexts = PlaceholderDefaults.texts(),
    placeholderTextStyle: TextStyle = textStyle.copy(color = MaterialTheme.colorScheme.secondary),
    onDataChange: (PaymentCardData) -> Unit = {}
)
```

You can also customize these layout through theming and modifiers:

```kotlin
UserCustomTheme {
    // ...
    val modifier: Modifier = Modifier
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    // ...
    InlinePaymentCard(modifier = modifier, onDataChange = onDataChange)
}
```

#### Custom Layout

If these two layouts do not fit your application's design, you can create your own layout by passing a `@Composable` function to the `content` parameter. The `@Composable` function will receive a `PaymentCardInputScope` (together with the `PaymentCard` `Modifier`) object, which contains the `CardImage`, `CardNumberField`, `ExpiryField` and `CVCField` fields. You can use these fields to create your own layout:

```kotlin
UserParentLayout {
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    // ...
    PaymentCard(onDataChange = onDataChange) { modifier ->
        Column(
            modifier = modifier
                .border(BorderStroke(1.dp, Color.LightGray), RoundedCornerShape(8.dp))
                .padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            CardImage()

            CardNumberField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.CreditCardText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.CreditCardText,
                        color = Color(0x75757575),
                        fontSize = 12.sp
                    )
                },
                textStyle = MaterialTheme.typography.titleLarge,
                textFieldColors = customTextFieldColors()
            )

            ExpiryField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.ExpirationDateText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.ExpirationDateText,
                        color = Color(0x9E9E9E9E),
                        fontSize = 10.sp
                    )
                },
                textStyle = MaterialTheme.typography.titleMedium,
                textFieldColors = customTextFieldColors()
            )

            CVCField(
                modifier = Modifier.fillMaxWidth(),
                label = {
                    Text(
                        text = LabelTextsDefaults.CvcText,
                        color = Color.Blue
                    )
                },
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.CvcText,
                        color = Color(0xBDBDBDBD),
                        fontSize = 8.sp
                    )
                },
                textStyle = MaterialTheme.typography.bodyMedium,
                textFieldColors = customTextFieldColors()
            )
        }
    }
}

@Composable
private fun customTextFieldColors(): TextFieldColors = TextFieldDefaults.colors(
    focusedIndicatorColor = Color.Transparent,
    unfocusedIndicatorColor = Color.Transparent,
    disabledIndicatorColor = Color.Transparent,
    focusedContainerColor = Color.Transparent,
    unfocusedContainerColor = Color.Transparent,
    disabledContainerColor = Color.Transparent,
)
```

#### Optional Rendering

Fields can be optionally displayed by passing in a list of CardFields. For example if you with to only render the Card Number field use the following code.

```kotlin
import com.evervault.sdk.input.model.CardFields

UserCustomTheme {
    // ...
    val onDataChange: (PaymentCardData) -> Unit = {} // Handle card data
    PaymentCard(onDataChange = onDataChange, enabledFields = listOf(CardFields.CARD_NUMBER)) { modifier ->
        Column(
            modifier = modifier
                .border(BorderStroke(1.dp, Color.LightGray), RoundedCornerShape(8.dp))
                .padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            CardImage()

            CardNumberField(
                modifier = Modifier.fillMaxWidth(),
                label = null,
                placeholder = {
                    Text(
                        text = PlaceholderTextsDefaults.CreditCardText,
                        color = Color(0x75757575),
                        fontSize = 12.sp
                    )
                },
                textStyle = MaterialTheme.typography.titleLarge,
                textFieldColors = customTextFieldColors()
            )
        }
    }
}
```

## Enclaves

The Evervault Enclaves SDK provides an accessible solution for developers to deploy Docker containers within a Secure Enclave. It enables you to interact with your Enclaves endpoints via standard HTTPS requests directly from your Android applications. A key feature that enables this is the attestation verification performed before completing the TLS handshake. For a deeper understanding of this process, you can explore our [TLS Attestation documentation](/enclaves#attestation-in-tls).

The attestation verification is executed using a custom Trust Manager on a `OkHttpClient.Builder`. This Trust Manager needs initialization with an `AttestationData` object:

```kotlin
data class AttestationData(
    val enclaveName: String,
    val pcrs: List<PCRs>
) {
    constructor(enclaveName: String, vararg pcrs: PCRs)
}

data class PCRs(
    val pcr0: String? = null,
    val pcr1: String? = null,
    val pcr2: String? = null,
    val pcr8: String? = null
)
```

It is crucial to ensure that the supplied PCRs align with the PCRs of the respective Enclave.

Then you configure the HTTP Client with the attestations:

```kotlin

val client = OkHttpClient.Builder()
    .trustManager(AttestationData(
        enclaveName = enclaveName,
        // Replace with legitimate PCR strings when not in debug mode
        PCRs(
            pcr0 = "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            pcr1 = "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            pcr2 = "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            pcr8 = "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
        )
    ))
    .build()
```

Only use this client for requests to your Enclave. For all other requests, use a separate client.

### Enclave PCR Manager

If the PCRs of your Enclave change, the attestation connection will fail from all clients that are not updated with the new PCRs. The `EnclaveTrustManager` is a service that can optionally be used to cache a list of PCRs that are returned from an API under your control. The `EnclaveTrustManager` can be used by passing a `PcrCallback` and the `enclaveName` as a parameter to `AttestationData` that is used to build the `OkHttpClient`. The `EnclaveTrustManager` will cache the response PCRs from the `PcrCallback` and refresh them at a default interval of 5 minutes. This refresh can be configured by passing the `callbackInterval` parameter.

This example below show how to call an endpoint that returns a list of PCRs as the callback function.

```kotlin
val pcrRequest = Request.Builder()
    .url(BuildConfig.PCR_CALLBACK_URL)
    .build()

val pcrCallback: PcrCallback = {
    val pcrResponse = pcrClient.newCall(pcrRequest).execute()
    val type = object : TypeToken<List<PCRs>>() {}.type
    val responseMap: List<PCRs> = Gson().fromJson(pcrResponse.body!!.string(), type)
    responseMap
}

val client = OkHttpClient.Builder()
    .enclavesTrustManager(
        AttestationData(
            enclaveName = enclaveName,
            pcrCallback
        ),
        appUuid
    )
    .build()
```

The endpoint returning the PCRs must return the PCRs in the format

```json
[
  {
    "pcr0": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "pcr1": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "pcr2": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "pcr8": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
  }
]
```

#### Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active versions of your Enclave which you can use to keep your clients in sync with your Enclave across deployments.

```kotlin
// Data type to deserialize the Evervault API's response
data class PCRContainer(
    val data: List<PCRs>
)

fun invokeEnclaveWithEvervaultPCRProvider(enclaveName: String, appId: String, url: String) {
  val pcrClient = OkHttpClient.Builder().build()
  val pcrRequest = Request.Builder()
      .url("https://api.evervault.com/enclaves/$enclaveName/attestation")
      .header("x-evervault-app-id", appId)
      .build()

  try {
    val pcrCallback: PcrCallback = {
      val pcrResponse = pcrClient.newCall(pcrRequest).execute()
      val type = object : TypeToken<PCRContainer>() {}.type
      val responseMap: PCRContainer = Gson().fromJson(pcrResponse.body!!.string(), type)
      responseMap.data
    }

    val jsonPayload = JSONObject()
    jsonPayload.put("a", 1)
    jsonPayload.put("b", 2)

    val request = Request.Builder()
      .url(url)
      .header("content-type", "application/json")
      .post(requestBody)
      .build()

    val enclaveClient = OkHttpClient.Builder()
      .enclavesTrustManager(
          AttestationData(
              enclaveName = enclaveName,
              pcrCallback
          ),
          appUuid
      )
      .build()

    val response = client.newCall(request).execute()
  } catch (e: Exception) {
      when(e) {
          is IOException, is PCRCallbackError -> {
              e.printStackTrace()
              return "Error: ${e.message}"
          }
          else -> throw e
      }
  }
}
```

#### Considerations

- It's crucial to note that the PCR values associated with an Enclave change with each new deployment. Consequently, older versions of your app with hardcoded PCRs may stop functioning. To alleviate this, you can accommodate previous deployments by providing multiple `PCRs` objects or use the `EnclaveTrustManager`:

```kotlin
AttestationData(
    enclaveName = enclaveName,
    listOf(
        PCRs(
            pcr0 = "fd4b",
            pcr1 = "bc3f",
            pcr2 = "2c10",
            pcr8 = "dfb3"
        ),
        PCRs(
            pcr0 = "c779",
            pcr1 = "bc3f",
            pcr2 = "4cbf",
            pcr8 = "dfb3"
        )
    )
)
```

Using the `EnclaveTrustManager` by passing a `PcrCallback` to the `AttestationData` allows you do update your PCRs remotely via an endpoint you control. When an Enclave is deployed and the PCRs change the list of PCRs returned from the endpoint should expand to hold the new PCRs e.g

```json
[
  {
    "pcr0": "fd4b", // Old PCRs
    "pcr1": "bc3f",
    "pcr2": "2c10",
    "pcr8": "dfb3"
  },
  {
    "pcr0": "c779", // New PCRs
    "pcr1": "bc3f",
    "pcr2": "4cbf",
    "pcr8": "dfb3"
  }
]
```

The `EnclaveTrustManager` will cache the new PCRs and old PCRs. Over time you can then remove the old PCRs from your endpoints response leaving just the new PCRs.

```json
[
  {
    "pcr0": "c779", // New PCRs
    "pcr1": "bc3f",
    "pcr2": "4cbf",
    "pcr8": "dfb3"
  }
]
```

This allows for the updating of an Enclave without having to re-publish your client with new PCRs.

- Please be aware that the Android SDK is compatible only with Enclaves that have the API Key Authentication set to `false` in your enclave.toml file:

```
api_key_auth = false
```

- Only use the `OkHttpClient` configured with the `AttestationData` for requests to your Enclave. For all other requests, use a separate client. If you have multiple Enclaves, you will need to configure a separate `OkHttpClient` for each Enclave.

- When calling an endpoint of your Enclave, use make sure you do not have any underscore `_` in the request url. Replace any underscore, such as the one in your App ID, with hyphens `-`.

These considerations are essential to remember for a seamless integration and operation of the Evervault Enclaves SDK in your Android applications.

## Google Pay

The Evervault SDK provides a Google Pay component that allows your customers to make payments in your app using credit and debit cards saved to their Google Account. Read the [Google Pay](/cards/google-pay?client=android) guide for more information.

## Proguard Rules

If you are using code shrinking with ProGuard you will need to specify exclusion rules for evervault-core dependencies. To do this add the following lines to your `proguard-rules.pro`

```
## Keep the BouncyCastle provider classes
-keep class org.bouncycastle.jce.provider.** { *; }

## Keep all classes from the org.bouncycastle package
-keep class org.bouncycastle.** { *; }

## Keep all classes that implement javax.crypto interfaces
-keep class * extends javax.crypto.** { *; }
```

## Sample App

The Evervault Android SDK Package includes a sample app, located in the `sampleapplication` directory. The sample app demonstrates various use cases of the SDK, including string encryption, file (image) encryption, the usage of the `PaymentCard` view with customized styling and how to contruct an attested Enclave client.

## License

The sample app is released under the MIT License. See the [LICENSE](https://github.com/evervault/evervault-android/blob/main/LICENSE) file for more information.

Feel free to experiment with the sample app to understand the capabilities of the Evervault Android SDK and explore different integration options for your own projects.

## Contributing

Bug reports and pull requests are welcome on [GitHub](https://github.com/evervault/evervault-android).

## Feedback

Questions or feedback? [Let us know](mailto:support@evervault.com).


---

# CLI

_The Evervault Command Line Interface allows you to test and manage your Evervault integration from your terminal._

The Evervault CLI allows you to configure your Evervault integration from the terminal. This reference documents every command and flag available in the Evervault CLI.

## Installation

Run the following command to install the Evervault CLI. This command can also be used to upgrade from a previous major version of the Evervault CLI.

```bash
sh <(curl https://cli.evervault.com/v4/install -sL)
```

### Updating

To update the Evervault CLI to the latest version, run the following command:

```bash
ev update
```

> The update command will not update between major versions of the Evervault
>   CLI. To update to a new major version, you will need to run the installation
>   command again.

## Authentication

To authenticate the Evervault CLI configure the following environment variables:

**Environment Variables**

- `EV_API_KEY` `string` _(required)_ — An [API Key](/developers/api-keys) with the appropriate permissions, created from the [Evervault Dashboard](https://app.evervault.com).
- `EV_APP_UUID` `string` _(required)_ — Your App ID, which can be found in the [Evervault Dashboard](https://app.evervault.com) on the app Settings page.

## Global Flags

The following flags can be used on any command within the Evervault CLI.

**Flags**

- `--help` — Show help for the command.
- `--verbose` — Print verbose logs.
- `--json` — Output the response in JSON format.

## encrypt

Encrypt data using the Evervault API. Note, while Strings are valid JSON values they must be enclosed in double quotes.

```bash
ev encrypt --data "Hello, world!"
```

**Options**

- `--data` _(required)_ — The JSON value to be encrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

## decrypt

Decrypt data using the Evervault API.

```bash
ev decrypt --data "ev:Tk9D:GWgxSXezEFNw10..."
```

**Options**

- `--data` _(required)_ — The Encrypted JSON value to be decrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

## relay

The Evervault CLI can be used to manage your Relays in a continuous integration environment.

### relay create

Creates an Evervault Relay and generates a configuration file. You will be prompted to enter the relay destination URL.

```bash
ev relay create
```

**Flags**

- `--out` _(required)_ — Path to write relay.json to. Defaults to relay.json

### relay deploy

Deploy changes to your [Relay](/relay) based on the relay.json configuration file. This is useful for versioning your Relay configuration by checking your `relay.json` file into version control.

```bash
ev relay deploy
```

**Flags**

- `--file` — The file containing the Relay config you want to use. Defaults to relay.json.

### relay.json

The relay.json file is a JSON file that contains the configuration for your Relay. It is used to define the Relay's behavior and how it should interact with data.

```json
{
  // The ID of the Relay.
  "id": "relay_destination_de582ef10c16",
  // The ID of the App the Relay belongs to.
  "app": "app_ddfbbn7n841e",
  // The destination where the Relay will forward requests to.
  "destinationDomain": "example.com",
  // The Evervault domain for the Relay.
  "evervaultDomain": "example-com-app-relay.evervault.app",
  // Whether to encrypt empty strings.
  "encryptEmptyStrings": true,
  // The authentication method to use for the Relay. Set this to 'api-key' to enable API key authentication.
  "authentication": null,
  // The route configurations for how the Relay should handle requests.
  "routes": [
    {
      // The HTTP method to match.
      "method": "POST",
      // The path to match.
      "path": "/checkout",
      // The transformations to apple to the request payload.
      "request": [
        {
          // The action to perform on the request payload. "encrypt" or "decrypt".
          "action": "encrypt",
          // The JSON Path expressions to select the fields to encrypt.
          "selections": [
            {
              // The type of data to select. "json", "form" or "header"
              "type": "json",
              // The JSON Path expression to select the field to encrypt.
              "selector": "$.cardNumber"
            }
          ]
        }
      ],
      // The transformations to apple to the response payload.
      "response": [
        {
          "action": "decrypt",
          "selections": [
            {
              "type": "json",
              "selector": "$..*"
            }
          ]
        }
      ]
    }
  ]
}
```

## function

### function init

Initialize a sample "hello world" Function either in your current directory, or the directory provided.

```bash
ev function init
```

**Flags**

- `--dir` — The directory to initialize the function into. If not given, the Function will be created in a subdirectory of the current directory using the name of the Function.
- `--force` — Overwrite the existing directory at the location if it exists

### function create-toml

Creates a starter `function.toml` in the current directory.

```bash
ev function create-toml
```

### function deploy

Deploy a Function using the source code of your current working directory. Your current directory must contain a valid `function.toml` file.

```bash
ev function deploy
```

**Flags**

- `--background` — By default, the CLI will wait for the Function deployment to complete. If you only want to begin the deployment and then exit, you can pass in the --background flag. This is recommended in a CI/CD environment.
- `--name` — The name of the Function to deploy. If not given, the CLI will look for a function.toml in the current directory.

### function env

Manage the environment variables for a Function.

> Some environment variables are reserved for our use and therefore are
>   immutable.

```bash
ev function env (get|set|delete) [FLAGS] [OPTIONS]
```

**Flags**

- `--secret` — Mark the environment variable as a secret. This encrypts it and makes it irretrievable. All secrets are decrypted when your function is run.

**Options**

- `--name` — The name of the Function to interact with. If not given, then the CLI will look for a function.toml in the current directory.
- `--key` — The key of the environment variable to update.
- `--value` — The value of the environment variable to update.

### function delete

Deletes a Function.

```bash
ev function delete [FLAGS] [OPTIONS]
```

**Flags**

- `--force` — Force the deletion of the Function. This will prevent any confirmation dialogues.

**Options**

- `--name` — The name of the Function to delete. If not given, then the CLI will look for a function.toml in the current directory.

### function run

Run a named Function from the command line using a JSON Payload.

> This command **does not** automatically encrypt your data before sending it to
>   the Function.

```bash
ev function run [OPTIONS]
```

**Options**

- `--name` — The name of the Function you wish to invoke. If not provided the CLI will attempt to run the Function defined in a function.toml in the current working directory.
- `--data` — The JSON payload to send to the Function.
- `--async` — Whether to run the Function asynchronously. See the [Function Execution Time](/functions#executiontime) documentation for more information.

## enclave

The Evervault CLI is the primary interface for building and deploying Enclaves.

### enclave init

Create an Enclave and initialize an `enclave.toml` in the current directory. By default, this will generate a key pair to sign your Enclave image unless a key pair is explicitly provided using `--private-key`and`--signing-cert`.

```bash
ev enclave [FLAGS] init [OPTIONS] --name <ENCLAVE_NAME>
```

**Options**

- `--name` — Name of Enclave to deploy
- `--port` — The port that the in-Enclave service listens on. All incoming requests will be forwarded to this port. If unset, it will be taken as last exposed port in the Dockerfile.
- `--file` — Dockerfile to build the Enclave
- `--healthcheck` — The path that should be used for in-Enclave healthchecks. These healthchecks are performed every second and can be used to probe the running process.
- `--healthcheck-port` — The port to perform healthchecks against. If this is unset, then the healthchecks are assumed to be served over the same port as the incoming requests.
- `--debug` — Debug setting for the Enclave. When debug is enabled, you can access logs from within the Enclave.
- `--egress` — Flag to enable network egress from your Enclave, default egress port is 443
- `--egress-destinations` — Comma separated list of domains to allow egress to, default is all (*)
- `-h, --help` — Print help information
- `-o, --output` — Directory to write the enclave.toml to. Defaults to the current directory.
- `--private-key` — Path to the signing key to use for the Enclave.
- `--signing-cert` — Path to the signing cert to use for the Enclave
- `--disable-api-key-auth` — Turn off API key authentication in the Enclave.
- `--trusted-headers` — Trusted headers sent into the Enclave will be persisted without redaction in the Enclave's transaction logs.
- `--disable-tls-termination` — Turn off TLS Termination in the Enclave's data plane process. This will allow you to control TLS termination within your service to enable mTLS or a custom certificate.
- `--forward-proxy-protocol` — When supplied with --disable-tls-termination, the data plane will forward the client IP using the HAProxy Proxy Protocol v2.
- `--desired-replicas` — Define the number of instances to deploy your Enclave to. Defaults to 2.
- `--max-concurrent-connections` — Enable concurrent request processing by capping the number of connections the data plane handles at once. Must be greater than zero. If unset, the data plane accepts connections serially.
- `--max-concurrent-handshakes` — The maximum number of TLS handshakes the data plane maintains concurrently. Must be greater than zero and must not exceed --max-concurrent-connections.
- `--handshake-timeout` — The timeout for a single TLS handshake, in milliseconds. Stalled handshakes are dropped after the timeout elapses.

### enclave build

The build command mirrors the `docker build` command but produces an Enclave Image File (EIF) as output instead of a Docker image. The build command requires a `enclave.toml` to be available when creating an Enclave Image File. This can be generated using the `ev enclave [FLAGS] init` command.

```bash
ev enclave [FLAGS] build [OPTIONS] [CONTEXT_PATH]
```

**Arguments**

- `CONTEXT_PATH` — Path to use for Docker context, defaults to the current directory.

**Options**

- `-c, --config` — Path to the enclave.toml file. Defaults to ./enclave.toml
- `-f, --file` — Path to the Dockerfile to use for the Enclave. Defaults to ./Dockerfile
- `-o, --output` — Path to directory to save the processed Dockerfile and EIF.
- `--private-key` — Private key to be used when signing the EIF.
- `--signing-cert` — Certificate corresponding to the private key.
- `--build-arg` — Build time arguments to provide to Docker.
- `--build-secret` — Build time secrets to provide to Docker. These secrets are used during the Docker build process, similar to the Docker --secret flag.
- `--from-existing` — Build from enclave.Dockerfile for build reproducibility
- `--reproducible` — Build enclave with reproducible measures
- `--forward-proxy-protocol` — Enabled forwarding proxy protocol when TLS Termination is disabled
- `--no-cache` — Disables the use of cache during image builds

### enclave cert new

Create a new Enclave signing certificate and private key.

```bash
ev enclave [FLAGS] cert new [OPTIONS]
```

**Options**

- `-o, --output` — Path to the directory where the credentials will be saved. Defaults to the current directory.
- `--subj` — Defining the certificate's distinguished name e.g. `/CN=EV/C=IE/ST=LEI/L=DUB/O=Evervault/OU=Eng`. If not given a generic Enclave subject is given.

### enclave cert upload

Upload a signing certificate's metadata to the Evervault API. This cert can then be used in the `cert lock` command.

Note: Certificate metadata is automatically uploaded to the Evervault API when you deploy an Enclave. This command is only necessary if you want to lock deployments to a certificate before the certificate has been used for a deployment. If you have already deployed with the certifcate, the metadata will be available in the cert lock prompt.

```bash
ev enclave [FLAGS] cert upload [OPTIONS]
```

**Options**

- `-p, --cert_path` — Path to directory where the signing cert is. Defaults to the path specified in ./enclave.toml
- `-c --config` — Path to enclave.toml config file. Default: ./enclave.toml

### enclave cert lock

Interactive prompt to lock Enclave deployments to specific signing certificates. An Enclave deployment will fail if the signing certificate used is not in specified locked certs. If no certificates are locked to an Enclave, it can be deployed with any certificate. If you want to lock a newly created certifcate, you must first upload it's metadata using the `cert upload` command. This certificate will then be available in the cert lock prompt.

```bash
ev enclave [FLAGS] cert lock [OPTIONS]
```

**Options**

- `-c --config` — Path to enclave.toml config file. Default: ./enclave.toml

### enclave delete

Delete the Enclave defined in a given `enclave.toml`.

```bash
ev enclave [FLAGS] delete [OPTIONS]
```

**Options**

- `-c --config` — Path to the enclave.toml config file. Default: ./enclave.toml
- `--enclave-uuid` — Uuid of the Enclave to delete
- `--background` — Perform the Enclave deletion in the background
- `--force` — Prevent confirmation dialogue and proceed with deletion. Use with caution.

### enclave deploy

Deploy the Enclave defined in your `enclave.toml` file. By default, the deploy command will ignore any prebuilt EIFs and begin a fresh Enclave build. You can prevent this by providing a path to an existing EIF using the `--eif-path` option.

```bash
ev enclave [FLAGS] deploy [OPTIONS] [CONTEXT_PATH]
```

**Arguments**

- `CONTEXT_PATH` — Path to use for Docker context, defaults to the current directory.

**Options**

- `-c, --config` — Path to the enclave.toml config file. Default: ./enclave.toml
- `--eif-path` — Path to EIF for the Enclave. Will skip building if EIF is provided.
- `-f, --file` — Path to Dockerfile for Enclave. Will override any Dockerfile specified in the enclave.toml file
- `--private-key` — Private key used to sign the Enclave Image File.
- `--signing-cert` — Certificate used to sign the Enclave Image File.
- `--build-arg` — Build time arguments to provide to Docker
- `--build-secret` — Build time secrets to provide to Docker. These secrets are used during the Docker build process, similar to the Docker --secret flag.
- `--from-existing` — Build from enclave.Dockerfile for build reproducibility
- `--reproducible` — Build enclave with reproducible measures
- `--healthcheck` — The endpoint to use for healthchecks. See healthchecks for more information.
- `--no-cache` — Disables the use of cache during the image builds

### enclave restart

Restart the Enclave defined in your `enclave.toml` file. This will redeploy the Enclave with the same image as your current Deployment, but with the latest environment variables and secrets. This won't affect your Enclave's PCRs.

```bash
ev enclave [FLAGS] restart [OPTIONS]
```

**Options**

- `-c --config` — Path to the enclave.toml config file. Default: ./enclave.toml
- `--enclave-uuid` — Uuid of the Enclave to restart
- `--background` — Perform the Enclave restart in the background

### enclave describe

Get the PCRs of an existing EIF.

```bash
ev enclave [FLAGS] describe [OPTIONS] [EIF_PATH]
```

**Arguments**

- `EIF_PATH` — Path to the EIF to describe.

**Options**

- `-h, --help` — Print help information
- `--no-cache` — Disables the use of cache during the image builds

### enclave list enclaves

List your enclaves.

```bash
ev enclave [FLAGS] list enclaves [OPTIONS]
```

**Options**

- `-h, --help` — Print help information

### enclave list deployments

List the deployments for your Enclave.

```bash
ev enclave [FLAGS] list deployments [OPTIONS]
```

**Options**

- `-h, --help` — Print help information
- `--enclave-uuid` — Uuid of the Enclave to list deployments for

### enclave logs

View the logs for your Enclave. Only available for Enclaves in debug mode.

```bash
ev enclave [FLAGS] logs [OPTIONS]
```

**Options**

- `--enclave-uuid` — The uuid of the Enclave to get deployments for.
- `-c, --config` — The local Enclave config.
- `--end-time` — The end time in milliseconds since the unix epoch.
- `--start-time` — The start time in milliseconds since the unix epoch
- `-h, --help` — Print help information

### enclave env add

Add environment variable to be used in an Enclave.

```bash
ev enclave [FLAGS] env add [OPTIONS] --key <ENV_KEY> --value <SECRET_VALUE>
```

**Flags**

- `--key` _(required)_ — The key of the environment variable to add.
- `--value` _(required)_ — The value of the environment variable to add.

**Options**

- `-h, --help` — Print help information.
- `--secret` — Encrypt the environment variable.

### enclave env delete

Permanently delete a environment variable from the Enclave environment.

```bash
ev enclave [FLAGS] env delete [OPTIONS] --key <ENV_KEY>
```

**Flags**

- `--key` _(required)_ — The key of the environment variable to delete.

### enclave env get

Get the environment variables in json format.

```bash
ev enclave [FLAGS] env get
```


---

# Go

_Encrypt data server-side, invoke Functions, Enclaves and proxy requests through Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

```bash
go get github.com/evervault/evervault-go
```

### Initialize the SDK

Now, let's initialize the SDK using our App's ID and API key. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```go
import "github.com/evervault/evervault-go"

evClient, err := evervault.MakeClient("<APP_ID>", "<API_KEY>")
```

### Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

```go
encrypted := evClient.Encrypt("Hello, world!");
```

## Connecting to an Enclave

The returned client will be configured to connect to the Enclave and attest the connection on each request with the pcrs provided.

```go
enclaveURL = "my-enclave.<APP_UUID>.enclave.evervault.com"
expectedPCRs := evervault.PCRs{PCR8: "..."}

enclaveClient, err := evClient.EnclaveClient(
    enclaveURL,
    []evervault.PCRs{expectedPCRs}
)

if err != nil {
    log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
    log.Fatal(err)
}

req, _ := http.NewRequest(
    http.MethodPost,
    fmt.Sprintf("https://%s/", enclaveURL
    ),
    bytes.NewBuffer(payload)
)
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := enclaveClient.Do(req)
```

To keep your clients in sync with your Enclave across deployments, you can use the `EnclaveClientWithProvider`. This allows you to define a callback function which returns a list of PCRs. This can be used to load the latest set of PCRs for your Deployed Enclave from a trusted source without a redeploy of your client.

```go

import (
    "github.com/evervault/evervault-go",
    "github.com/evervault/evervault-go/attestation"
)

evClient, err := evervault.MakeClient("<APP_ID>", "<API_KEY>")
if err != nil {
    log.Fatal(err)
}

enclaveURL = "my-enclave.<APP_UUID>.enclave.evervault.com"
expectedPCRs := attestation.PCRs{PCR8: "..."}

func GetPCRsFromApi() ([]attestation.PCRs, error) {
  // Logic to load PCRs from an API/CDN etc.
  return pcrs, nil
}

enclaveClient, err := evClient.EnclaveClientWithProvider(enclaveURL, GetPCRsFromApi)
if err != nil {
    log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
    log.Fatal(err)
}

req, _ := http.NewRequest(
    http.MethodPost,
    fmt.Sprintf("https://%s/", enclaveURL),
    bytes.NewBuffer(payload)
)
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := enclaveClient.Do(req)
```

## Reference

The full reference is available on [Go pkg](https://pkg.go.dev/github.com/evervault/evervault-go).

### Encrypt

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). Evervault Strings can be used across all of our products. The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

```go
encrypted := evClient.Encrypt("Hello, world!");
```

**Parameters**

- `data` _(required)_ — The data to encrypt.

### Decrypt

Decrypt data previously encrypted with the `Encrypt` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```go
encrypted := evClient.Encrypt("Hello, world!");

dataToDecrypt := make(map[string]any);
dataToDecrypt["encryptedData"] = encrypted;

decrypted := evClient.Decrypt(dataToDecrypt);
```

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### CreateClientSideDecryptToken

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```go
token := evClient.CreateClientSideDecryptToken(encryptedData)
```

**Parameters**

- `payload` `string` _(required)_ — The payload containing encrypted data that the token will be used to decrypt.
- `expiry` `time.Time` — The time the token will expire. Defaults to 5 minutes in the future.

### RunFunction

Invoke an [Evervault Function](/functions) with a given payload.

```go
result := evClient.RunFunction(functionName, payload)
```

**Parameters**

- `functionName` `string` _(required)_ — The name of the function to invoke.
- `payload` `map[string]any` _(required)_ — The payload containing encrypted data that will be passed as an argument to the Function.


---

# iOS

_Encrypt data client-side, collect card details & perform 3D Secure authentication._

## Supported Platforms

- iOS 15+
- macOS 12+

## Quickstart

### Install SDK

The Evervault iOS SDK can be installed using the Swift Package Manager.

1. Open your Xcode project.
2. Navigate to **File** > **Swift Packages** > **Add Package Dependency**.
3. Enter the repository URL for the Evervault iOS SDK: `https://github.com/evervault/evervault-ios.git`.
4. Choose the latest available version or specify a version rule.
5. Click **Next** and follow the instructions to integrate the package into your project.

#### Initialize SDK

Now, let's initialize the SDK using our App and Team ID. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```swift
import EvervaultCore

Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

If you need multiple instances of the Evervault SDK you can use the initializer as follows:

```swift
import EvervaultCore

let evervault = Evervault.init(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

### Encrypting Data

Once the SDK is configured, you can use the `encrypt` method to encrypt your sensitive data. The `encrypt` method accepts various data types, including Boolean, Numerics, Strings, Arrays, Dictionaries, and Data.

Here's an example of encrypting a password:

```swift
let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")
```

Or using a dedicated instance:

```swift
let encryptedPassword = evervault.encrypt("Super Secret Password")
```

The `encrypt` method returns an `Any` type, so you will need to safely cast the result based on the data type you provided. For Boolean, Numerics, and Strings, the encrypted data is returned as a String. For Arrays and Dictionaries, the encrypted data maintains the same structure but is encrypted. For Data, the encrypted data is returned as encrypted Data, which can be useful for encrypting files.

### Decrypting Data

Decrypts data previously encrypted with the `encrypt()` function or through Relay.

The `decrypt()` method 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](/sdks) or through our [REST API](/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.

```swift
let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")
let decrypted: String = Evervault.shared.decrypt('<token generated by your backend application>', encryptedPassword)
```

### Inputs

The Evervault iOS SDK also includes the `EvervaultInputs` module, which provides a SwiftUI view called `PaymentCardInput`. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data. The `PaymentCardInput` view can be customized to fit your application's design.

To use `PaymentCardInput`, make sure you have imported the `EvervaultInputs` module in your file, and then simply add the view to your SwiftUI hierarchy:

```swift
import EvervaultInputs

struct ContentView: View {

    @State private var cardData = PaymentCardData()

    var body: some View {
        VStack {
            PaymentCardInput(cardData: $cardData)

            // Data captured:
            Text("Encrypted credit card number: \(cardData.card.number)")
        }
    }
}
```

Fields can be optionally displayed by passing in the enabledFields struct. For example if you with to only render the Card Number field use the following code.

```swift
import EvervaultInputs

struct ContentView: View {

    private var enabledFields = EnabledFields(isCardNumberEnabled: true, isExpiryEnabled: false, isCVCEnabled: false)

    @State private var cardData = PaymentCardData()

    var body: some View {
        VStack {
            PaymentCardInput(cardData: $cardData, fields: enabledFields)

            // Data captured:
            Text("Encrypted credit card number: \(cardData.card.number)")
        }
    }
}
```

The encrypted credit card number and CVC are captured in the `PaymentCardData` Binding, as well as the expiry month and year and validation fields.

#### Styling

Internally, the `PaymentCardInput` view uses SwiftUI `TextField`s. These can be customized using SwiftUI modifiers like any other `TextField`s in your application:

```swift
    PaymentCardInput(cardData: $cardData)
        .font(.footnote)
        .foregroundColor(.blue)
```

To provide more customization options, the `PaymentCardInput` can be styled using a `PaymentCardInputStyle`. There are two build-in styles:

- `InlinePaymentCardInputView` (the default style) - puts the credit card number, expiry and cvc fields all on a single row.

![Screenshot of the iOS PaymentCardInput with Inline styling]()

To explicitly use this style:

```swift
    PaymentCardInput(cardData: $cardData)
        .paymentCardInputStyle(.inline)
```

- `RowsPaymentCardInputStyle` - puts the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.

![Screenshot of the iOS PaymentCardInput with Rows styling]()

To use this style:

```swift
    PaymentCardInput(cardData: $cardData)
        .paymentCardInputStyle(.rows)
```

If these two styles do not match your use case, you can create your own style:

```swift
struct CustomPaymentCardInputStyle: PaymentCardInputStyle {

    func makeBody(configuration: Configuration) -> some View {
        VStack(alignment: .center) {
            configuration.cardImage

            Text("CC Number").font(.title3)
            configuration.cardNumberField

            Divider()

            Text("Expiry").font(.title3)
            configuration.expiryField

            Divider()

            Text("CVC").font(.title3)
            configuration.cvcField
        }
    }
}
```

```swift
    PaymentCardInput(cardData: $cardData)
        .paymentCardInputStyle(CustomPaymentCardInputStyle())
```

### Attest Enclaves

The Evervault iOS SDK includes the ability to attest connections to [Enclaves](/enclaves).

To [attest your Enclave](/enclaves#attestation-in-tls), you need to provide the expected PCRs to an Enclave session.

```swift
import EvervaultCore
import EvervaultEnclaves

//Note: Make sure app uuid is hyphenated (eg: app-123456).
let url = URL(string: "https://<ENCLAVE_NAME>.<APP_UUID>.enclave.evervault.com")
let enclaveSession = await Evervault.enclaveAttestationSession(
  enclaveAttestationData: EnclaveAttestationData(
    enclaveName: "<ENCLAVE_NAME>",
    appUuid: "<APP_UUID>",
    pcrs: PCRs(
      pcr0: "<PCR0>",
      pcr1: "<PCR1>",
      pcr2: "<PCR2>",
      pcr8: "<PCR8>",
    )
  )
)

do {
  let response = try await enclaveSession.data(from: url)
  // ...
} catch {
  // ...
}
```

### Apple Pay®

The Evervault iOS SDK provides support for Apple Pay on iOS, enabling secure handling of card data during mobile transaction flows. When a customer taps the Apple Pay button in your app, our SDK will give you the Apple Pay card token (DPAN) from the user's device.

Instead of using Apple's default encryption, the SDK extracts the customer's card details, including the card token and "cryptogram", and returns them in an Evervault-encrypted payload. This allows you to securely access sensitive values while ensuring they remain protected through Evervault's encryption infrastructure.

The encrypted payload can then be safely passed to any downstream system or payment processor for transaction authorization using our proxy, Evervault [Relay](/relay).

In [Sandbox apps](/developers/sandbox), the encrypted network token maps to a [brand-specific test card](/cards/apple-pay#testing-sandbox) based on the card the customer selects in their Apple Wallet.

#### Prerequisites

- You must have an individual or organisational Apple Developer account.

- All users of Apple Pay agree to adhere to the [Apple Pay Terms and Conditions](https://www.apple.com/legal/internet-services/apple-pay-wallet/us/).

#### Register for an Apple Merchant ID

Before you can use Apple Pay for iOS with Evervault you need to obtain an Apple Merchant ID by [registering for a new identifier](https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier) on the Apple Developer portal.
Fill out the description and identifier. We recommend you use the name of your app as the identifier e.g. `merchant.com.<YOUR_APPS_NAME>`

#### Create a new Apple Pay Payment Processing Certificate

Apple Pay needs to encrypt payment data such as card details. You will need a payment processing certificate for your app to allow Apple Pay to encrypt those details within your app.

In the Evervault dashboard, click the `Payments` tab at the top of the page. Then, on the left-hand side of the page click `Apple Pay` and at the bottom of the page under `Certificates`, click `Add certificate`. Follow the on screen instructions.

As part of this flow, Evervault will provide you with a certificate signing request that you must download.

Then, in a new tab, in the Apple Developer portal, under [Certificates](https://developer.apple.com/account/resources/certificates/add), create an `Apple Pay Payment Processing Certificate`, select the Merchant ID that you created in the previous step and click `Continue`. Under the `Apple Pay Payment Processing Certificate` section, click `Create Certificate` and upload the certificate signing request you downloaded from the Evervault dashboard.

Download the Apple certificate you just created and go back to the Evervault dashboard and in the certificate set up dialog, upload the certificate you just downloaded from Apple.

#### Setting up Xcode

Once you have created your merchant identifier and payment processing certificate, you need to add the Apple Pay capability to your app in Xcode.

Open your project settings, click the `Signing & Capabilities` tab, and add the Apple Pay capability. You might be prompted to sign in to your developer account. Select the merchant ID you created earlier, and now your app is ready to accept Apple Pay.

#### Create a Transaction

Next you will need to create a transaction to describe the payment you want to process. You will need to provide the country, currency, and line items for the transaction. The last item is the total for the transaction.

If the transaction isn't constructed correctly — for example, the `country` or `currency` fields aren't valid, or the transaction has no summary items — Evervault throws `EvervaultError.InvalidCountryError`, `EvervaultError.InvalidCurrencyError`, or `EvervaultError.EmptyTransactionError` respectively.

Please refer to [Apple's documentation](https://developer.apple.com/documentation/passkit/pkpaymentrequest/#Setting-currency-and-region-information) on requirements for country and currency and `amount` fields.

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

#### Pending line items

Line items default to a final amount. For estimates such as tax or shipping that aren't final, pass `type: .pending` to `SummaryItem`. The Apple Pay sheet shows an ellipsis (`…`) instead of an amount for that line. This maps to PassKit's [PKPaymentSummaryItemType](https://developer.apple.com/documentation/passkit/pkpaymentsummaryitemtype).

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Estimated Tax", amount: Amount("2.50"), type: .pending),
    SummaryItem(label: "Total", amount: Amount("32.50"))
  ]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

`OneOffPaymentTransaction` and `RecurringPaymentTransaction` also accept a `requestPayerDetails` parameter to request billing contact fields — such as the payer's name, email, phone, or postal address — using PassKit's own `PKContactField` values:

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  requestPayerDetails: [.name, .phoneticName, .phoneNumber, .emailAddress, .postalAddress]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

If you need to collect a shipping address, pass `shippingType`, `shippingMethods`, and `requiredShippingContactFields` to `OneOffPaymentTransaction`. `shippingMethods` are [`PKShippingMethod`](https://developer.apple.com/documentation/passkit/pkshippingmethod) instances the customer can choose between on the payment sheet:

```swift
import EvervaultPayment
import PassKit

let expressShipping = ShippingMethod(label: "Express Shipping", amount: NSDecimalNumber(string: "9.99"))
expressShipping.identifier = "express_1day"
expressShipping.detail = "Arrives in 1–2 business days."

let standardShipping = ShippingMethod(label: "Standard Shipping", amount: NSDecimalNumber(string: "2.99"))
standardShipping.identifier = "standard_3day"
standardShipping.detail = "Arrives in 3-5 business days."

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Standard Shipping", amount: Amount("2.99")),
    SummaryItem(label: "Total", amount: Amount("37.99"))
  ],
  shippingType: .shipping,
  shippingMethods: [expressShipping, standardShipping],
  requiredShippingContactFields: [.postalAddress, .name, .phoneNumber]
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

Use the `onShippingAddressChange` modifier on `EvervaultPaymentViewRepresentable` (see [Render the Apple Pay button](#render-the-apple-pay-button)) to update the summary items when the customer picks a different shipping address.

For subscriptions, use `RecurringPaymentTransaction`. You must provide a `managementURL` where customers can manage their subscription, and a `regularBilling` [PKRecurringPaymentSummaryItem](https://developer.apple.com/documentation/passkit/pkrecurringpaymentsummaryitem) describing the billing interval. `trialBilling` and `billingAgreement` are optional and are set on the transaction after it's constructed. It also accepts the same `shippingType` and `requiredShippingContactFields` parameters as `OneOffPaymentTransaction` above. `shippingMethods` are only supported on one-off payment transactions — recurring and disbursement transactions reject them:

```swift
import EvervaultPayment
import PassKit

let regularBilling = PKRecurringPaymentSummaryItem(label: "Pro Subscription", amount: 5.00)
regularBilling.intervalUnit = .month
regularBilling.intervalCount = 1

var recurring = try! RecurringPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [],
  paymentDescription: "Monthly Pro subscription",
  regularBilling: regularBilling,
  managementURL: URL(string: "https://www.merchant.com/manage-subscriptions")!
)

recurring.trialBilling = PKRecurringPaymentSummaryItem(label: "Trial", amount: 0)
recurring.billingAgreement = "https://www.merchant.com/billing-agreement"

let transaction = EvervaultPayment.Transaction.recurringPayment(recurring)
```

Both `OneOffPaymentTransaction` and `RecurringPaymentTransaction` support a coupon code field on the Apple Pay sheet. Set `supportsCouponCode: true`, and optionally pass an initial `couponCode`:

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  supportsCouponCode: true
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

Use the `onCouponCodeChange` modifier on `EvervaultPaymentViewRepresentable` (see [Render the Apple Pay button](#render-the-apple-pay-button)) to recalculate the summary items, or reject the code, when the customer changes it. Coupon codes aren't available on `DisbursementTransaction`, since that's a payout rather than a purchase.

#### Restrict issuer countries and pass application data

`OneOffPaymentTransaction` and `RecurringPaymentTransaction` accept a `supportedCountries` parameter to limit payments to cards issued in specific countries. Use ISO 3166 country codes. This maps to PassKit's [supportedCountries](https://developer.apple.com/documentation/passkit/pkpaymentrequest/supportedcountries) field. It isn't available on `DisbursementTransaction`, which has no equivalent property.

You can also attach merchant data to the request with `applicationData`. Apple includes a hash of this data in the payment token so you can verify it server-side. This maps to PassKit's [applicationData](https://developer.apple.com/documentation/passkit/pkpaymentrequest/applicationdata) field, and is also available on `DisbursementTransaction` using [PKDisbursementRequest.applicationData](https://developer.apple.com/documentation/passkit/pkdisbursementrequest/applicationdata).

```swift
import EvervaultPayment

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  supportedCountries: ["US", "CA"],
  applicationData: Data("order_123".utf8)
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

For payouts to a customer's card, use `DisbursementTransaction` and provide:

- a `disbursementItem` describing the payout.
- the `requiredRecipientDetails` you need to collect from the recipient.
- the `merchantCapability` your merchant account supports.

You can optionally pass an `instantOutFee` and [applicationData](#restrict-issuer-countries-and-pass-application-data).

```swift
import EvervaultPayment

let disbursement = try! DisbursementTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Withdrawal Summary", amount: Amount("41.00")),
    SummaryItem(label: "EUR Balance", amount: Amount("41.00"))
  ],
  disbursementItem: SummaryItem(label: "Disbursement", amount: Amount("41.00")),
  instantOutFee: SummaryItem(label: "Instant funds out fee", amount: Amount("1.00")),
  requiredRecipientDetails: [.emailAddress, .phoneNumber],
  merchantCapability: .instantFundsOut,
  applicationData: Data("payout_456".utf8)
)

let transaction = EvervaultPayment.Transaction.disbursement(disbursement)
```

#### Prefilling billing and shipping contact

If you know the customer's billing or shipping details (for example, from a logged-in checkout), you can prefill them on the Apple Pay sheet with `billingContact` and `shippingContact`. Include `.postalAddress` in `requestPayerDetails` and `requiredShippingContactFields` so the postal address fields appear on the sheet.

These options apply to payments and recurring transactions only. Disbursement transactions use `requiredRecipientDetails` on the transaction instead.

```swift
import EvervaultPayment

let billingContact = ApplePayPaymentContact(
  givenName: "Jane",
  familyName: "Doe",
  addressLines: ["123 Main St"],
  locality: "San Francisco",
  postalCode: "94105",
  administrativeArea: "CA",
  country: "United States",
  countryCode: "US"
)

let shippingContact = ApplePayPaymentContact(
  givenName: "Jane",
  familyName: "Doe",
  emailAddress: "jane.doe@example.com",
  phoneNumber: "+14155550100",
  addressLines: ["123 Main St"],
  locality: "San Francisco",
  postalCode: "94105",
  administrativeArea: "CA",
  country: "United States",
  countryCode: "US"
)

let oneOff = try! OneOffPaymentTransaction(
  country: "IE",
  currency: "EUR",
  paymentSummaryItems: [
    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
    SummaryItem(label: "Socks", amount: Amount("5.00")),
    SummaryItem(label: "Total", amount: Amount("35.00"))
  ],
  shippingType: .shipping,
  shippingMethods: [],
  requiredShippingContactFields: [.postalAddress],
  requestPayerDetails: [.postalAddress],
  billingContact: billingContact,
  shippingContact: shippingContact
)

let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)
```

#### Check if Apple Pay is supported

Before displaying Apple Pay as a payment option, use the `availability(supportedNetworks:)` method to check whether the device supports Apple Pay, and whether the customer has a card in their wallet. It returns one of three states, matching the [web SDK](#availability):

- `available`: Apple Pay is supported and the customer has a usable card.
- `unavailable`: Apple Pay is supported, but the customer hasn't added a card for the networks you accept.
- `unsupported`: Apple Pay isn't supported on this device.

```swift
let availability = EvervaultPaymentViewRepresentable.availability(supportedNetworks: [.visa, .masterCard, .amex])
```

Use `unsupported` to hide the Apple Pay button entirely. Use `unavailable` to show a **Set Up Apple Pay** button instead of a regular buy button (see [Customise the Apple Pay button](#customise-the-apple-pay-button) for more details).

If you support disbursement transactions, also check `supportsDisbursements()`. Disbursements require iOS 17+, so this returns `false` on earlier versions even if `availability(supportedNetworks:)` reports `available`:

```swift
let canDisburse = EvervaultPaymentViewRepresentable.supportsDisbursements()
```

> **Deprecated**
>
> `isAvailable()` only reports whether the device is capable of Apple Pay. It
>   doesn't tell you whether the customer has a card set up. Because of that, it
>   can't distinguish between "no card added" and "card not supported." Use
>   `availability(supportedNetworks:)` instead.

```swift
let isAvailable = EvervaultPaymentViewRepresentable.isAvailable()
```

#### Render the Apple Pay button

Next you can render the Apple Pay button. When you do this, you will need to pass in your Evervault App ID, your Apple Merchant Identifier, the transaction object, the card networks you support, and a callback closure:

- `authorizedResponse`: Whenever the user successfully authorizes the payment, the decrypted `ApplePayResponse` (containing token, card info, cryptogram, etc.) will be written into your `@State` variable. You can react to that state change however you like — navigate onward, show a confirmation screen, or send it off to your own backend to be sent via an Evervault Relay to your PSP. Refer to [this section](/sdks/ios#processing-the-payment) for the structure of the response.
- `onResult`: Use this callback to reset UI state or advance your checkout flow after the sheet closes with a definite outcome (either success or failure). Failures can happen when Apple Pay is unavailable, the transaction is invalid, presentation fails, or if Evervault can't decrypt the payment details. The callback returns a `Result<Void, EvervaultError>`. The `EvervaultError` includes a `localizedDescription` you can display in an alert, log for diagnostics, or present however appropriate. `onResult` doesn't fire if the customer cancels.
- `onCancel`: Use this modifier to detect when the customer dismisses the sheet without authorizing a payment (e.g., taps **Cancel**). This is distinct from the success or failure provided by `onResult`.
- `shouldAuthorize`: Use this modifier to inspect the authorized payment and approve or reject it before the sheet reports success. Return `.success(())` to proceed, or `.failure(reason)` to reject the payment, where `reason` is any `Error`. Rejections are reported through `onDecline`, never `onResult`. This closure runs on the main actor, so it's safe to update UI state directly inside it.
- `onDecline`: Use this modifier to handle a payment you rejected from `shouldAuthorize`. It fires only after the sheet closes, so it's safe to present your own UI in response. `onDecline` includes the `reason` passed in `shouldAuthorize`, and is distinct from `onResult`, which only reports SDK-level success or failure and doesn't fire for a decline.
- `onCouponCodeChange`: Use this modifier to react when the customer changes the coupon code on the Apple Pay sheet (shown only when `supportsCouponCode` is set on the transaction). If the coupon code is valid, return a [PKPaymentRequestCouponCodeUpdate](https://developer.apple.com/documentation/passkit/pkpaymentrequestcouponcodeupdate) with the recalculated summary items. If it's invalid, you can return `errors` instead (e.g., `PKPaymentRequest.paymentCouponCodeInvalidError(localizedDescription:)` to reject the coupon code.

```swift
// Example decline reason — conforms to `Error`, so `onDecline` can switch over it exhaustively.
enum DeclineReason: Error, LocalizedError {
  case prepaidCardNotAccepted

  var errorDescription: String? {
    switch self {
    case .prepaidCardNotAccepted:
      return "Prepaid cards are not accepted"
    }
  }
}

struct ContentView: View {
  @State private var applePayResponse: ApplePayResponse? = nil
  let transaction = buildTransaction()

  var body: some View {
    VStack(spacing: 20) {
      EvervaultPaymentViewRepresentable(
        appId: "YOUR_EVERVAULT_APP_ID",
        appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
        transaction: transaction,
        supportedNetworks: [.visa, .masterCard, .amex],
        authorizedResponse: $applePayResponse) { result in
            switch result {
            case .success(_):
                print("Payment sheet dismissed with success")
                if (applePayResponse != nil) {
                    // Send to PSP via Relay on your backend
                }
                break
            case let .failure(error):
                print("Payment error: \(error.localizedDescription)")
                break
            }
        }
        .onCancel {
            print("Payment sheet cancelled")
        }
        .onDecline { reason in
            print("Payment declined: \(reason.localizedDescription)")
        }
        .shouldAuthorize { response in
            // Example merchant rule: reject prepaid cards.
            if response?.card.funding == "prepaid" {
                return .failure(DeclineReason.prepaidCardNotAccepted)
            }
            return .success(())
        }
    }
  }
}
```

#### Processing the Payment

If the payment is handled successfully, the Evervault encrypted payment method is available in `$applePayResponse` (in the example above). The `authorizedResponse` is an `ApplePayResponse` object containing the payment method details encrypted with the Evervault public key. You can send this encrypted payment method to your server and use Evervault Relay to decrypt the payment details when you send them to your PSP.

The `ApplePayResponse` object represented as JSON contains the following fields:

```json
{
  "networkToken": {
    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
    "expiry": {
      "month": "12",
      "year": "31"
    },
    "rawExpiry": "12/31",
    "tokenServiceProvider": "Apple"
  },
  "card": {
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "ie",
    "currency": "eur",
    "issuer": "Revolut Bank Uab"
  },
  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",
  // The ECI value is optional with Apple Pay.
  // Learn more here: https://developer.apple.com/documentation/passkit/payment-token-format-reference#Detailed-payment-data-keys-3D-Secure
  "eci": "5",
  "paymentDataType": "3DSecure",
  "deviceManufacturerIdentifier": "string",
  "transactionType": "oneOff",
  "transactionId": "5ee9e294a2e79032ca7529b2050c2a878187c54a54f07559cff8281fb9b4716c",

  // Only present if you requested the corresponding contact fields on the transaction
  "billingContact": {
    "givenName": "John",
    "familyName": "Doe",
    "phoneticGivenName": null,
    "phoneticFamilyName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890",
    "postalAddress": {
      "street": "123 Main St",
      "city": "City",
      "state": "State",
      "postalCode": "12345",
      "country": "Country",
      "isoCountryCode": "XX"
    }
  },
  "shippingContact": {
    "givenName": "John",
    "familyName": "Doe",
    "phoneticGivenName": null,
    "phoneticFamilyName": null,
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "1234567890"
  }
}
```

- `rawExpiry`: the token's expiry in `MM/YY` format, as returned by Apple. Use `expiry.month`/`expiry.year` instead if you need the parsed values.
- `transactionType`: indicates the transaction category (`oneOff`, `recurring`, or `disbursement`) based on how you created the transaction.
- `transactionId`: Apple's identifier for the token, from the [PKPaymentToken header](https://developer.apple.com/documentation/passkit/payment-token-format-reference#Header-keys-and-values). Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself.
- `billingContact` / `shippingContact`: only populated when the transaction requested those contact fields.
- `phoneticFamilyName` / `phoneticGivenName`: populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). `null` otherwise.

#### Complete example

Below is a complete example of Evervault Apple Pay in action:

```swift
import SwiftUI
import EvervaultPayment

func buildTransaction() -> EvervaultPayment.Transaction {
  let oneOff = try! OneOffPaymentTransaction(
    country: "IE",
    currency: "EUR",
    paymentSummaryItems: [
      SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
      SummaryItem(label: "Socks", amount: Amount("5.00")),
      SummaryItem(label: "Total", amount: Amount("35.00"))
    ]
  )
  return Transaction.oneOffPayment(oneOff)
}

// Example decline reason — conforms to `Error`, so `onDecline` can switch over it exhaustively.
enum DeclineReason: Error, LocalizedError {
  case prepaidCardNotAccepted

  var errorDescription: String? {
    switch self {
    case .prepaidCardNotAccepted:
      return "Prepaid cards are not accepted"
    }
  }
}

struct ContentView: View {
  @State private var applePayResponse: ApplePayResponse? = nil
  let transaction = buildTransaction()
  let supportedNetworks: [Network] = [.visa, .masterCard, .amex]

  var body: some View {
    let availability = EvervaultPaymentViewRepresentable.availability(supportedNetworks: supportedNetworks)

    VStack(spacing: 20) {
      if availability != .unsupported {
        // Apple Pay is supported — show the setup button if there's no card yet
        EvervaultPaymentViewRepresentable(
          appId: "YOUR_EVERVAULT_APP_ID",
          appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
          transaction: transaction,
          supportedNetworks: supportedNetworks,
          buttonStyle: .whiteOutline,
          buttonType: availability == .unavailable ? .setUp : .checkout,
          authorizedResponse: $applePayResponse) { result in
              switch result {
              case .success(_):
                  print("Payment sheet dismissed with success")
                  if (applePayResponse != nil) {
                    // Send to PSP via Relay on your backend
                  }
                  break
              case let .failure(error):
                  print("Payment error: \(error.localizedDescription)")
                  break
              }
          }
          .onCancel {
              print("Payment sheet cancelled")
          }
          .onDecline { reason in
              print("Payment declined: \(reason.localizedDescription)")
          }
          .shouldAuthorize { response in
              // Example merchant rule: reject prepaid cards.
              if response?.card.funding == "prepaid" {
                  return .failure(DeclineReason.prepaidCardNotAccepted)
              }
              return .success(())
          }
      } else {
        Text("Not available")
      }
    }
  }
}

#Preview {
    ContentView()
}
```

#### Using EvervaultPaymentView directly (UIKit)

If your app doesn't use SwiftUI, render Apple Pay with the raw `EvervaultPaymentView` — a `UIView` subclass — and its `EvervaultPaymentViewDelegate` protocol, instead of `EvervaultPaymentViewRepresentable`:

```swift
import UIKit
import EvervaultPayment

class CheckoutViewController: UIViewController, EvervaultPaymentViewDelegate {
  private var applePayResponse: ApplePayResponse?

  override func viewDidLoad() {
    super.viewDidLoad()

    let paymentView = EvervaultPaymentView(
      appId: "YOUR_EVERVAULT_APP_ID",
      appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
      transaction: buildTransaction(),
      supportedNetworks: [.visa, .masterCard, .amex],
      buttonStyle: .whiteOutline,
      buttonType: .checkout
    )
    paymentView.delegate = self
    view.addSubview(paymentView)
    // Position `paymentView` with Auto Layout or a frame, as you would any other UIView.
  }

  // Required. Fired when a payment is authorized, before the sheet dismisses.
  func evervaultPaymentView(_ view: EvervaultPaymentView, didAuthorizePayment result: ApplePayResponse?) {
    applePayResponse = result
  }

  // Optional — mirrors the SwiftUI wrapper's `onResult`.
  func evervaultPaymentView(_ view: EvervaultPaymentView, didFinishWithResult result: Result<Void, EvervaultError>) {
    switch result {
    case .success:
      if applePayResponse != nil {
        // Send to PSP via Relay on your backend
      }
    case let .failure(error):
      print("Payment error: \(error.localizedDescription)")
    }
  }

  // Optional — mirrors the SwiftUI wrapper's `onCancel`.
  func evervaultPaymentViewDidCancel(_ view: EvervaultPaymentView) {
    print("Payment sheet cancelled")
  }
}
```

**Delegate methods**

`EvervaultPaymentViewDelegate` has multiple methods, but only `evervaultPaymentView(_:didAuthorizePayment:)` is required. The rest have default no-op implementations, so implement only the ones you need. Each maps to a modifier on the SwiftUI wrapper:

- `didAuthorizePayment`: the only required method. Writes the decrypted `ApplePayResponse` into your own state, in place of the SwiftUI wrapper's `authorizedResponse` binding.
- `didFinishWithResult`: mirrors `onResult`.
- `evervaultPaymentViewDidCancel`: mirrors `onCancel`.
- `didDeclinePayment`: mirrors `onDecline`.
- `shouldAuthorize`: mirrors `shouldAuthorize`.
- `didSelectShippingContact`: mirrors `onShippingAddressChange`.
- `didUpdatePaymentMethod`: mirrors `onPaymentMethodChange`.
- `didChangeCouponCode`: mirrors `onCouponCodeChange`.
- `prepareTransaction`: mirrors `prepareTransaction`.

**Static methods**

- `availability(supportedNetworks:)`: works the same as on `EvervaultPaymentViewRepresentable`.
- `supportsDisbursements()`: no equivalent on `EvervaultPaymentView`. Call PassKit's own `PKPaymentAuthorizationViewController.supportsDisbursements()` (iOS 17+) directly instead.

#### Customise the Apple Pay button

When initialising the `EvervaultPaymentViewRepresentable` you can pass two optional parameters — `buttonType` and `buttonStyle`.

Please refer to the [Apple PassKit documentation](https://developer.apple.com/documentation/passkit/pkpaymentbutton#Configuring-the-appearance) on what preset button styles and types are available.

```swift
EvervaultPaymentViewRepresentable(
  // other fields...
  buttonStyle: .whiteOutline,
  buttonType: .checkout,
)
```

If `availability(supportedNetworks:)` returns `unavailable`, Apple recommends showing the **Set Up Apple Pay** button instead of the default buy button. This takes the customer through the flow for adding a card rather than opening a payment sheet, which would fail.

```swift
EvervaultPaymentViewRepresentable(
  // other fields...
  buttonStyle: .whiteOutline,
  buttonType: availability == .unavailable ? .setUp : .checkout,
)
```

#### Error Handling

All errors from creating the `Transaction` object and the errors surfaced in the `onResult` callback on the `EvervaultPaymentViewRepresentable` can be cast to `EvervaultError`:

- `InvalidTransactionError`: This error is thrown when there is an issue with the transaction. As a guideline to help prevent encountering this error:
  - `amount`: The format of this value depends on the `currency`. It follows ISO 4217 and depends on the minor unit of the currency e.g the number of decimal points for`USD` is 2, so the amount must be formatted as `"50.00"`. This error will be thrown if you try to format the `amount` as `"50.0"`. As another example, `JPY` has no minor unit so the `amount` must be formatted as `"1000"`.
- `InvalidCurrencyError`: The currency is the three-letter ISO 4217 currency code that determines the currency the payment request uses. This error is thrown if the currency doesn't match this spec.
- `InvalidCountryError`: The country is the two-letter ISO 3166 country code. This error is thrown if the country doesn't match this spec.
- `EmptyTransactionError`: This error is thrown when a transaction has no summary items. The transaction must have at least one summary item, and the final item is the total.
- `ApplePayUnavailableError`: This error is thrown when Apple Pay isn't available on the device
- `ApplePayPaymentSheetError`: This error is thrown when an underlying error with the Apple Pay payment sheet occurs.
- `UnsupportedVersionError`: This error is thrown when trying to access a method that's not available on the current version of iOS.
- `ApplePayAuthorizationError`: This error is thrown when there's an issue authenticating with Apple Pay. The underlying error from Apple Pay is provided.
- `InternalError`: This error is thrown when something goes wrong during the handling of the payment data. An underlying reason is provided in this case.

### Full example

A complete working example is included in the [evervault-pay](https://github.com/evervault/evervault-pay) repository, in the [ios/Demo](https://github.com/evervault/evervault-pay/tree/main/ios/Demo) directory.

#### Running the Sample App

To run the sample app:

1. Open the `Demo.xcodeproj` file in Xcode.
2. Replace the `"YOUR_EVERVAULT_APP_ID"` and `"YOUR_APPLE_MERCHANT_ID"` placeholder strings in `ContentView.swift` with your own Evervault App ID and Apple Merchant Identifier.
3. Select a simulator or physical device as the build target.
4. Build and run the app.

## Reference

### EvervaultCore

#### Evervault.shared.config(teamId: String, appId: String)

A shared instance of the Evervault class. This is the simplest way to get up and running if you only need to use a single Evervault team/app.

```swift
import EvervaultCore

Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

**Parameters**

- `teamId` `String` _(required)_ — The Uuid of your Evervault Team
- `appId` `String` _(required)_ — The Uuid of your Evervault App

#### Evervault(teamId: String, appId: String)

Initializes a single instance of the Evervault class. You'll need to use this initializer if you require more than one Evervault team/app.

```swift
import EvervaultCore

let evervault = Evervault(teamId: "<TEAM_ID>", appId: "<APP_ID>")
```

**Parameters**

- `teamId` `String` _(required)_ — The Uuid of your Evervault Team
- `appId` `String` _(required)_ — The Uuid of your Evervault App

#### Evervault.encrypt(\_ data: Any, role: String?) async throws -> Any

Encrypts the provided data using [Evervault Encrypt](/developers/evervault-encryption) and an optional data role.

The encrypt function supports: `Boolean`, Numerics, `String`, `Array`, `Dictionary` and `Data`.

Note: Data Roles aren't yet supported when encrypting data of the `Data` type

```swift
let encryptedData = try await Evervault.shared.encrypt("Super Secret Password")
// or
let encryptedData = try await evervault.encrypt("Super Secret Password")
// or
let encryptedData = try await Evervault.shared.encrypt("Super Secret Password", "data-role")
```

**Parameters**

- `data` `Any` _(required)_ — The data you want to encrypt.

### EvervaultInputs

#### PaymentCardInput(cardData: PaymentCardData)

Create a PaymentCardInput SwiftUI view

```swift
import EvervaultInputs

struct ContentView: View {

    @State private var cardData = PaymentCardData()

    var body: some View {
        VStack {
            PaymentCardInput(cardData: $cardData)

            // Data captured:
            Text("Encrypted credit card number: \(cardData.card.number)")
        }
    }
}
```

**Parameters**

- `cardData` `PaymentCardData` _(required)_ — The card data state for the PaymentCardInput view

### EvervaultEnclaves

#### Evervault.enclaveAttestationSession(enclaveAttestationData: EnclaveAttestationData...) async -> URLSession

Create a `URLSession` that attests connections to your Evervault Enclave. Accepts one or more `EnclaveAttestationData` values, so a single session can attest connections to several Enclaves.

```swift
import EvervaultCore
import EvervaultEnclaves

let enclaveSession = await Evervault.enclaveAttestationSession(
  enclaveAttestationData: EnclaveAttestationData(
    enclaveName: "<ENCLAVE_NAME>",
    appUuid: "<APP_UUID>",
    pcrs: PCRs(
      pcr0: "<PCR0>",
      pcr1: "<PCR1>",
      pcr2: "<PCR2>",
      pcr8: "<PCR8>",
    )
  )
)
```

**Parameters**

- `enclaveAttestationData` `EnclaveAttestationData...` _(required)_ — The values used during the attestation handshake with your Enclave

#### EnclaveAttestationData

Config used to compare against the attestation doc served to the client from an Enclave.

Pass the expected measurements with `pcrs`, or pass a `provider` to fetch them at runtime so your clients stay in sync with your Enclave across deployments.

**EnclaveAttestationData**

- `enclaveName` `String` _(required)_ — The name of the Enclave to attest
- `pcrs` `PCRs...` _(required)_ — The platform configuration registers to compare against the attestation doc returned from the Enclave. Use this initializer when the expected measurements are known at build time.
- `provider` `(@escaping ([PCRs]?, Error?) -> Void) -> Void` _(required)_ — A callback that supplies the platform configuration registers to compare against the attestation doc returned from the Enclave. Use this initializer in place of `pcrs` to fetch the measurements at runtime.

#### PCRs

The attestation measurements measurement expected to be embedded in the attestation document returned from an Enclave.

**PCRs**

- `pcr0` `String` — The value for PCR0 to attest
- `pcr1` `String` — The value for PCR1 to attest
- `pcr2` `String` — The value for PCR2 to attest
- `pcr8` `String` — The value for PCR8 to attest

##### Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active versions of your Enclave which you can use to keep your clients in sync with your Enclave across deployments.

```swift
import EvervaultCore
import EvervaultEnclaves

struct AttestedEnclaveView: View {

    private let enclaveName = "my-enclave"
    private let appId = "app_123abc"
    private let enclaveHostname = "my-enclave.app-123abc.enclave.evervault.com"

    public struct EvervaultProviderResponse: Decodable {
        public let data: [PCRs]

        public init(data: [PCRs]) {
            self.data = data
        }
    }

    public var provider: (@escaping ([PCRs]?, Error?) -> Void) -> Void = { completion in
        var request = URLRequest(url: URL(string: "https://api.evervault.com/enclaves/\(enclaveName)/attestation")!)
        request.addValue(appId, forHTTPHeaderField: "x-evervault-app-id")

        URLSession.shared.dataTask(with: request) { data, _, error in
            guard let data = data, error == nil else {
                completion(nil, error ?? NSError(domain: "Evervault Provider", code: -1, userInfo: [NSLocalizedDescriptionKey: "No data or error."]))
                return
            }
            do {
                // Decode the data into a PCRContainer
                let container = try JSONDecoder().decode(EvervaultProviderResponse.self, from: data)
                // Extract the PCRs array from the container and pass it to the completion handler
                completion(container.data, nil)
            } catch {
                print("Error: ", error.localizedDescription)
                completion(nil, error)
            }
        }.resume()
    }

    @State private var responseText: String? = nil

    var body: some View {
        Group {
            if let responseText {
                Text(responseText)
            } else {
                Text("Loading...")
            }
        }
        .padding()
        .task {
            let url = URL(string: "https://\(enclaveHostname)/")!
            let urlSession = await Evervault.enclaveAttestationSession(
                enclaveAttestationData: EnclaveAttestationData(
                    enclaveName: enclaveName,
                    appUuid: appId,
                    provider: provider
                )
            )

            do {
                let response = try await urlSession.data(from: url)
                print(response)
            } catch {
                responseText = error.localizedDescription
                print("Error: \(error.localizedDescription)")
            }
        }
    }
}
```


---

# Java

_Encrypt data server-side, invoke Functions, Enclaves and proxy requests through Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

First, let's install the Evervault SDK using either Gradle or Maven.

### Initialize the SDK

Now, let's initialize the SDK using our App's ID and API key. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```java
import com.evervault.Evervault;

Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");
```

### Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

```java
String encrypted = (String) evervault.encrypt("Hello, world!");
```

## Reference

### Evervault()

The SDK constructor takes two parameters; your App's ID and API key.

```java
import com.evervault.Evervault;

var evervault = new Evervault("<APP_ID>", "<API_KEY>");
```

**Parameters**

- `app_id` `String` _(required)_ — Your Evervault App's ID.
- `api_key` `String` _(required)_ — Your Evervault App's API Key.

### encrypt()

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). Evervault Strings can be used across all of our products.

To encrypt data using the Java SDK, simply pass a value into the evervault.encrypt() function. encrypt() will encrypt your data and return an object which is a String in case you passed a literal type like bool, String, int, float, char, byte.

The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

```java
import com.evervault.Evervault;

Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");

String result = (String) evervault.encrypt("Hello, world!");
```

**Parameters**

- `data` `String | Map | int | float | char | bool | byte` _(required)_ — The data to encrypt.

### decrypt()

Decrypts the data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```java
private static class Bar {
    public String name;
}

void encryptAndDecrypt() throws EvervaultException {
    Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");

    // Encrypt some data
    String encryptedName = (String) evervault.encrypt("foo");

    // Decrypt the previously encrypted data
    Map<String, String> dataToDecrypt = new HashMap<String, String>();
    dataToDecrypt.put("name", encryptedName);

    // Decrypts and deserialises the encrypted data into a `Bar` instance
    Bar decryptedData = evervault.decrypt(dataToDecrypt, Bar.class);

    System.out.println(decryptedData.name); // Prints `foo`
}
```

**Parameters**

- `data` `Object` _(required)_ — The data to decrypt.
- `valueType` `Class<T>` _(required)_ — The value type of the dat to deserialize into.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### createClientSideDecryptToken()

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```java
String encryptedData = (String) evervault.encrypt("foo");
Instant timeInFiveMinutes = Instant.now().plus(minutes, ChronoUnit.MINUTES);

TokenResult token = evervault.createClientSideDecryptToken(encryptedData, timeInFiveMinutes);
```

**Parameters**

- `payload` `Object` _(required)_ — The payload containing encrypted data that the token will be used to decrypt.
- `expiry` `Instant` — The time the token will expire. Defaults to 5 minutes in the future.

### run()

Lets you invoke an [Evervault Function](/functions) with a given payload. The function result will be deserialized into an instance of `responseType` and will be returned.

```java

void runFunction() throws EvervaultException {
    Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");

    // Encrypt some data
    String encryptedSsn = (String) evervault.encrypt("478-32-9183");

    // Create the function payload
    Map<String, String> functionPayload = new HashMap<String, String>();
    functionPayload.put("ssn", encryptedSsn);

    // Deserializes the function response into a `Result` instance
    Result result = evervault.run("ssn-validation-function", functionPayload, Result.class);
    System.out.println("Validation result": + result.isValid);
}

public class Result {
    public boolean isValid;
}
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `payload` `Object` _(required)_ — The payload to pass to the function.
- `responseType` `Object` _(required)_ — The type into which the function's result will be serialized.
- `timeout` `int` — The request timeout defines the maximum duration the SDK will wait before aborting the function run if it has not completed.

### createRunToken()

Creates a single use, time bound token (5 minutes) for invoking an [Evervault Function](/functions) with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```java
import com.evervault.Evervault;

Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");

Map<String, String> payload = new HashMap<String, String>();
payload.put("ssn", "ev:encrypted_string")

RunToken runToken = evervault.createRunToken(
    "hello-function",
    payload
);
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `payload` `Object` — Payload that the token can be used with. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```


---

# JavaScript

_Encrypt data client-side, collect card details & perform 3D Secure authentication._

## Installation

Our JavaScript SDK is distributed from our CDN and can be loaded with a simple script tag. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

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

### Using npm

You can also install Evervault via the `@evervault/js` package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

```javascript
import { loadEvervault } from "@evervault/js";

const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");
```

Note: It is important to note that for PCI Compliance you must load the Evervault SDK directly from our CDN and cannot bundle it with your application. The loadEvervault function will always load the latest version of the Evervault SDK regardless of which version of @evervault/js you are using.

### Asynchronous Loading

You can load the SDK asynchronously using the `async` attribute on the script tag to prevent blocking the loading of your page. However, it is important to note that you will need to wait for the SDK to load before making any API calls.

```html
<!DOCTYPE html>
<html>
  <head>
    <script
      src="https://js.evervault.com/v2"
      onload="onEvervaultReady()"
      async
    ></script>
    <script>
      function onEvervaultReady() {
        const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
      }
    </script>
  </head>
</html>
```

## Usage

Once loaded, you can initialize the Evervault SDK with your Team and App ID found in the [Evervault Dashboard](https://app.evervault.com).

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const encrypted = await evervault.encrypt("Hello, World!");
```

## Reference

### Evervault

Creates an instance of the Evervault SDK using your Team and App ID.

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

**Parameters**

- `teamId` `string` _(required)_ — The ID of your Evervault team. This can be found inside of your team settings on the [Evervault dashboard](https://app.evervault.com).
- `appId` `string` _(required)_ — The ID of your Evervault app. This can be found inside of your app settings on the [Evervault dashboard](https://app.evervault.com).

### encrypt

Encrypts data using Evervault Encryption. The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Relay.

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const encrypted = await evervault.encrypt("Hello, world!");
```

**Parameters**

- `data` `string | Data | File | Blob` _(required)_ — The data to encrypt

### decrypt

Decrypts data previously encrypted with an Evervault product or SDK.

The decrypt() function uses Client-Side Tokens. 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.

```javascript
const encrypted = await evervault.encrypt("Hello, world!");
await evervault.decrypt("<CLIENT-SIDE-TOKEN>", encrypted);
```

**Parameters**

- `clientSideToken` `string` _(required)_ — A [Client-Side Token](/) with permission to decrypt the given payload.
- `encryptedData` `string` _(required)_ — The encrypted data to decrypt.

### ui.card

Initializes a Card component for [Card Collection](/cards/card-collection). The Card component makes it easy to collect and encrypt card data in a completely PCI-compliant environment.

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

const card = evervault.ui.card({
  theme: evervault.ui.themes.clean(),
});

card.on("change", (payload) => {
  console.log(payload.card.number);
  // ev:...
});

card.mount("#ev-card-fields");
```

**Parameters**

- `theme` — Allows you to completely customize the appearance of the component. See [Custom Styling](#custom-styling) for more information.
- `icons` `Boolean | Record<brand, string>` — If set to true, the component will display icons for the detected card brand. You can customize icons by passing an object with the brand as the key and src URL as the value.
- `autoFocus` `Boolean` — If set to true, the component will automatically focus when it mounts.
- `autoProgress` `Boolean` — If set to true, the component automatically moves focus to the next field when the current field is complete.
- `autoComplete` `Object` — Controls browser autocomplete behavior per field.
  - `autoComplete.name` `Boolean` — Enable browser autocomplete for the name field.
  - `autoComplete.number` `Boolean` — Enable browser autocomplete for the card number field.
  - `autoComplete.expiry` `Boolean` — Enable browser autocomplete for the expiry field.
  - `autoComplete.cvc` `Boolean` — Enable browser autocomplete for the CVC field.
- `acceptedBrands` `string[]` — Restricts the component to only accept the specified card brands. If not provided, all brands are accepted. Possible values are `visa`, `mastercard`, `american-express`, `diners-club`, `discover`, `jcb`, `unionpay`, `maestro`, `elo`, `mir`, `hiper`, `hipercard`, `szep`, `uatp`, `rupay`. Custom brands defined using `customBrands` are accepted regardless of this list.
- `customBrands` `CustomBrand[]` — An array of custom card brand definitions created with [`brands.create`](#brands-create). Custom brands are always accepted, even when `acceptedBrands` is set. See the [custom card brands](/cards/card-collection?client=browser#custom-card-brands) section for usage examples.
- `fields` `string[]` — Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
- `defaultValues` `Object` — Sets default values for card fields on mount.
  - `defaultValues.name` `string` — Default value for the cardholder name field.
- `redactCVC` `Boolean` — Sets the `type` attribute of the CVC field to `password` in order to visually redact the CVC field..
- `allow3DigitAmexCVC` `Boolean` — If set to false, rejects 3-digit CVCs for American Express cards and requires a 4-digit CVC. Defaults to `true`.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `translations` `Object` — Allows you to customize the text shown inside of the component.
  - `translations.name.label` — Customize the label for the name field.
  - `translations.name.placeholder` — Customize the placeholder for the name field.
  - `translations.name.errors.invalid` — Customize the error message for the name field when the value is invalid.
  - `translations.name.errors.regex` — Customize the error message for when the name field fails regex validation.
  - `translations.number.label` — Customize the label for the number field.
  - `translations.number.placeholder` — Customize the placeholder for the number field.
  - `translations.number.errors.invalid` — Customize the error message for the number field when the value is invalid.
  - `translations.expiry.label` — Customize the label for the expiry field.
  - `translations.expiry.placeholder` — Customize the placeholder for the expiry field.
  - `translations.expiry.errors.invalid` — Customize the error message for the expiry field when the value is invalid.
  - `translations.cvc.label` — Customize the label for the cvc field.
  - `translations.cvc.placeholder` — Customize the placeholder for the cvc field.
  - `translations.cvc.errors.invalid` — Customize the error message for the cvc field when the value is invalid.
- `validation` `Object` — Allows you to customize validation logic for the component.
  - `validation.name.regex` `RegExp` — A regex pattern that the name must match in order to be considered valid. You can use this option to only allow certain characters.
  - `validation.cvc.optional` `Boolean` — When set to `true`, the CVC field is treated as optional. The card is considered valid even if no CVC is entered. If a CVC is entered, it is validated as normal. Defaults to `false`.

#### card.mount

Mounts the component to a given DOM node.

```javascript
card.mount("#card-details");
```

#### card.on('change')

Subscribe to changes made to the component. The encrypted card details can be accessed from the payload passed to the callback. The change event will fire any time there is a state update in the component. This includes when the user types in a field, looses focus on a field, or when an error is displayed.

```javascript
card.on("change", (data) => {
  console.log(data.card.number);
  // ev:...
});
```

**Callback Parameters**

- `data.card` `Object` — Information about the entered card, including meta data as well as the encrypted number aned CVC.
  - `data.card.number` `string` — The encrypted card number.
  - `data.card.brand` `string` — The card brand.
  - `data.card.lastFour` `string` — The last four digits of the card number.
  - `data.card.bin` `string` — The bin for the card. This will only be present if the number is valid.
  - `data.card.expiry.month` `string` — The month of the card expiry date.
  - `data.card.expiry.year` `string` — The year of the card expiry date.
  - `data.card.cvc` `string` — The encrypted CVC.
  - `data.card.name` `string` — The card holder name.
- `data.errors` `Record<string, string>` — Validation errors related to the card details.
- `data.isValid` `Boolean` — Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate method. **Note**: This field represents if there are any errors shown, not if the card details are valid. You should use the isComplete field to determine if the user has successfully entered a valid card.
- `data.isComplete` `Boolean` — Whether or not the card details are valid. This will only be true if the user has entered a valid card number, expiry date and CVC.

#### card.on('complete')

The complete event will fire once the user has successfully filled out all fields in the Card Component with valid values.

```javascript
card.on("complete", (data) => {
  console.log(data.card.number);
  // ev:...
});
```

**Callback Parameters**

- `data.card` `Object` — Information about the entered card, including meta data as well as the encrypted number aned CVC.
  - `data.card.number` `string` — The encrypted card number.
  - `data.card.brand` `string` — The card brand.
  - `data.card.lastFour` `string` — The last four digits of the card number.
  - `data.card.bin` `string` — The bin for the card. This will only be present if the number is valid.
  - `data.card.expiry.month` `string` — The month of the card expiry date.
  - `data.card.expiry.year` `string` — The year of the card expiry date.
  - `data.card.cvc` `string` — The encrypted CVC.
  - `data.card.name` `string` — The card holder name.
- `data.errors` `Record<string, string>` — Validation errors related to the card details.
- `data.isValid` `Boolean` — Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate method. **Note**: This field represents if there are any errors shown, not if the card details are valid. You should use the isComplete field to determine if the user has successfully entered a valid card.
- `data.isComplete` `Boolean` — Whether or not the card details are valid. This will only be true if the user has entered a valid card number, expiry date and CVC.

#### card.on('ready')

The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

```javascript
card.on("ready", () => {
  document.getElementById("loading").addClass("hide");
  document.getElementById("card-details").removeClass("hide");
});
```

#### card.on('error')

The error event will be fired if the component fails to load. If you want to respond to validation errors you should use the [change event](#cardonchange) instead.

```javascript
card.on("error", () => {
  alert("Opps, something went wrong!");
});
```

#### card.on('swipe')

Subscribe to swipe events from card readers. The encrypted card details can be accessed from the payload passed to the callback. The component must have focus for the card reader event to be detected.

```javascript
card.on("swipe", (data) => {
  console.log(data.card.number);
  // ev:...
});
```

**Callback Parameters**

- `data.card` `Object` — Information about the entered card, including meta data as well as the encrypted number aned CVC.
  - `data.card.number` `string` — The encrypted card number.
  - `data.card.brand` `string` — The card brand.
  - `data.card.lastFour` `string` — The last four digits of the card number.
  - `data.card.bin` `string` — The bin for the card. This will only be present if the number is valid.
  - `data.card.month` `string` — The month of the card expiry date.
  - `data.card.year` `string` — The year of the card expiry date.
  - `data.card.cvc` `string` — The encrypted CVC.
  - `data.card.firstName` `string` — The card holder first name if one was detected.
  - `data.card.lastName` `string` — The card holder last name if one was detected.

#### card.on('validate')

Fired when `card.validate()` is called. Use this to read the validation result after triggering programmatic validation.

```javascript
card.on("validate", (data) => {
  console.log(data.isValid);
});

card.validate();
```

**Callback Parameters**

- `data.card` `Object` — Information about the card, including metadata, the encrypted number, and CVC.
  - `data.card.number` `string` — The encrypted card number.
  - `data.card.brand` `string` — The card brand.
  - `data.card.lastFour` `string` — The last four digits of the card number.
  - `data.card.bin` `string` — The BIN for the card. Only present when a valid card numbers is entered.
  - `data.card.expiry.month` `string` — The month of the card expiry date.
  - `data.card.expiry.year` `string` — The year of the card expiry date.
  - `data.card.cvc` `string` — The encrypted CVC.
  - `data.card.name` `string` — The cardholder name.
- `data.isValid` `Boolean` — Whether all fields are currently valid.
- `data.isComplete` `Boolean` — Whether all required fields are currently valid.
- `data.errors` `Record<string, string>` — Validation errors for each field.

#### card.on('focus')

Fired when a card field receives focus.

```javascript
card.on("focus", (event) => {
  console.log(event.field); // "number" | "expiry" | "cvc" | "name"
});
```

**Callback Parameters**

- `event.field` `string` — The field that received focus. One of `name`, `number`, `expiry`, or `cvc`.
- `event.data` `Object` — The current card payload at the time of the event. Same shape as the `change` event payload.

#### card.on('blur')

Fired when a card field loses focus.

```javascript
card.on("blur", (event) => {
  console.log(event.field); // "number" | "expiry" | "cvc" | "name"
});
```

**Callback Parameters**

- `event.field` `string` — The field that lost focus. One of `name`, `number`, `expiry`, or `cvc`.
- `event.data` `Object` — The current card payload at the time of the event.

#### card.on('keyup')

Fired on a key-up event within a card field.

```javascript
card.on("keyup", (event) => {
  console.log(event.field);
});
```

**Callback Parameters**

- `event.field` `string` — The active field. One of `name`, `number`, `expiry`, or `cvc`.
- `event.data` `Object` — The current card payload at the time of the event.

#### card.on('keydown')

Fired on a key-down event within a card field.

```javascript
card.on("keydown", (event) => {
  console.log(event.field);
});
```

**Callback Parameters**

- `event.field` `string` — The active field. One of `name`, `number`, `expiry`, or `cvc`.
- `event.data` `Object` — The current card payload at the time of the event.

#### card.update()

Update the configuration for the component after it has been initialized. Any arguments passed will be merged with the arguments passed when the component was initialized. This can be used to dynamically update the translations for the component, or update the styling.

```javascript
card.update({
  translations: {
    number: {
      label: "uimhir chárta",
    },
  },
});
```

**Parameters**

- `theme` — Allows you to completely customize the appearance of the component. See [Custom Styling](#custom-styling) for more information.
- `icons` `Boolean | Record<brand, string>` — If set to true, the component will display icons for the detected card brand. You can customize icons by passing an object with the brand as the key and src URL as the value.
- `autoFocus` `Boolean` — If set to true, the component will automatically focus when it mounts.
- `autoProgress` `Boolean` — If set to true, the component automatically moves focus to the next field when the current field is complete.
- `autoComplete` `Object` — Controls browser autocomplete behavior per field.
  - `autoComplete.name` `Boolean` — Enable browser autocomplete for the name field.
  - `autoComplete.number` `Boolean` — Enable browser autocomplete for the card number field.
  - `autoComplete.expiry` `Boolean` — Enable browser autocomplete for the expiry field.
  - `autoComplete.cvc` `Boolean` — Enable browser autocomplete for the CVC field.
- `acceptedBrands` `string[]` — Restricts the component to only accept the specified card brands. If not provided, all brands are accepted. Possible values are `american-express`, `visa`, `mastercard`, `discover`, `jcb`, `diners-club`, `unionpay`, `maestro`, `mir`, `elo`, `hipercard`, `hiper`, `szep`, `uatp`, `rupay`. Custom brands defined using `customBrands` are accepted regardless of this list.
- `customBrands` `CustomBrand[]` — An array of custom card brand definitions created with [`brands.create`](#brands-create). Custom brands are always accepted, even when `acceptedBrands` is set.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `fields` `string[]` — Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
- `defaultValues` `Object` — Sets default values for card fields.
  - `defaultValues.name` `string` — Default value for the cardholder name field.
- `allow3DigitAmexCVC` `Boolean` — If set to false, rejects 3-digit CVCs for American Express cards and requires a 4-digit CVC. Defaults to `true`.
- `translations` `Object` — Allows you to customize the text shown inside of the component.
  - `translations.name.label` — Customize the label for the name field.
  - `translations.name.placeholder` — Customize the placeholder for the name field.
  - `translations.name.errors.invalid` — Customize the error message for the name field when the value is invalid.
  - `translations.name.errors.regex` — Customize the error message for when the name field fails regex validation.
  - `translations.number.label` — Customize the label for the number field.
  - `translations.number.placeholder` — Customize the placeholder for the number field.
  - `translations.number.errors.invalid` — Customize the error message for the number field when the value is invalid.
  - `translations.expiry.label` — Customize the label for the expiry field.
  - `translations.expiry.placeholder` — Customize the placeholder for the expiry field.
  - `translations.expiry.errors.invalid` — Customize the error message for the expiry field when the value is invalid.
  - `translations.cvc.label` — Customize the label for the cvc field.
  - `translations.cvc.placeholder` — Customize the placeholder for the cvc field.
  - `translations.cvc.errors.invalid` — Customize the error message for the cvc field when the value is invalid.
- `validation` `Object` — Allows you to customize validation logic for the component.
  - `validation.name.regex` `RegExp` — A regex pattern that the name must match in order to be considered valid. You can use this option to only allow certain characters.
  - `validation.cvc.optional` `Boolean` — When set to `true`, the CVC field is treated as optional. The card is considered valid even if no CVC is entered. If a CVC is entered, it is validated as normal. Defaults to `false`.

#### card.validate()

Manually trigger validation for the card details fields. This method is useful if you want to force validation to display error messages inside of the component. This is an asynchronous operation and will not return an immediate result. You can use the `validate` event to listen for the result of calling this method.

```javascript
card.on("validate", (data) => {
  console.log(data.isValid);
});

card.validate();
```

#### card.unmount()

Removes the component from the DOM.

```javascript
card.unmount();
```

### brands.create

Creates a custom card brand definition that can be passed to the `customBrands` option on [`ui.card`](#uicard). Use this to add support for card networks that aren't included in Evervault's built-in brand list.

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

const acmeBrand = evervault.brands.create("acme-card", {
  numberValidationRules: {
    ranges: [[88000, 88999]],
    lengths: [16],
  },
  securityCodeValidationRules: {
    lengths: [3],
  },
});

const card = evervault.ui.card({
  customBrands: [acmeBrand],
});
```

**Parameters**

- `name` `string` _(required)_ — A unique identifier for the brand. This value is returned in the `localBrands` array of the card change payload.
- `options` `Object` _(required)_ — Configuration for the custom brand.
  - `options.numberValidationRules` `Object` _(required)_ — Rules used to validate card numbers for this brand.
    - `options.numberValidationRules.ranges` `Array<number | [number, number]>` _(required)_ — Bank identification number (BIN) prefixes or ranges that identify cards belonging to this brand. A single number matches cards starting with that prefix (e.g., `9900`). A two-element tuple defines an inclusive range of BIN prefixes (e.g., `[88000, 88999]`).
    - `options.numberValidationRules.lengths` `number[]` _(required)_ — The valid card number lengths for this brand.
    - `options.numberValidationRules.luhnCheck` `Boolean` — Whether to validate the card number using the Luhn algorithm. Defaults to `true`.
  - `options.securityCodeValidationRules` `Object` _(required)_ — Rules used to validate the CVC for this brand.
    - `options.securityCodeValidationRules.lengths` `Array<3 | 4>` _(required)_ — The valid CVC lengths for this brand. Accepts 3, 4 or both.
  - `options.iconSrc` `string` — A URL for the brand's icon. Displayed in the card component when a matching card number is entered.

### ui.pin

Initializes a component for collecting and encrypting PIN numbers in a PCI-compliant environment.

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

const pin = evervault.ui.pin({
  length: 4,
  mode: "numeric",
});

pin.on("complete", (data) => {
  console.log(data.value); // encrypted PIN
});

pin.mount("#pin-field");
```

**Parameters**

- `theme` — Allows you to customize the component's appearance. See [Custom Styling](#custom-styling) for more information.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `length` `number` — The number of PIN digits to collect. Defaults to `4`, maximum `10`.
- `autoFocus` `Boolean` — If set to true, the component automatically focuses when it mounts.
- `mode` `"numeric" | "alphanumeric"` — If set to `"alphanumeric"`, the PIN field accepts letters as well as digits. Defaults to `"numeric"`.
- `inputType` `"number" | "text" | "password"` — Sets the `type` attribute of the underlying input elements used to capture the PIN. Defaults to `"number"`.

#### pin.mount()

Mounts the component to a given DOM node.

```javascript
pin.mount("#pin-field");
```

#### pin.on('change')

Fired whenever the PIN value changes.

```javascript
pin.on("change", (data) => {
  console.log(data.value); // encrypted PIN or null
  console.log(data.isComplete);
});
```

**Callback Parameters**

- `data.value` `string | null` — The encrypted PIN value, or `null` if the field is empty.
- `data.isComplete` `Boolean` — Whether the PIN field is complete.

#### pin.on('complete')

Fired when the user enters all PIN digits.

```javascript
pin.on("complete", (data) => {
  console.log(data.value); // encrypted PIN
});
```

**Callback Parameters**

- `data.value` `string | null` — The encrypted PIN value.
- `data.isComplete` `Boolean` — Whether the PIN field is complete.

#### pin.on('ready')

Fired when the component loads and is ready to be displayed.

```javascript
pin.on("ready", () => {
  document.getElementById("pin-field").style.display = "block";
});
```

#### pin.on('error')

Fired if the component fails to load.

```javascript
pin.on("error", () => {
  console.error("PIN component failed to load");
});
```

#### pin.update()

Updates the component configuration after initialization. Any arguments passed are merged with the original options.

```javascript
pin.update({ length: 6 });
```

#### pin.unmount()

Removes the component from the DOM.

```javascript
pin.unmount();
```

### ui.threeDSecure

The ThreeDSecure component can be used in combination with the Evervault API to perform [3D Secure](/cards/3d-secure?client=Browser) authentication. In order to use the ThreeDSecure component you must first [create a 3D Secure session](api#createThreeDSSession) on your backend and pass it to your frontend. The component will display the 3D Secure iframe and handle the authentication process.

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const threeDSecure = evervault.ui.threeDSecure("tds_visa_123456789");
threeDSecure.mount();
```

**Parameters**

- `session` `string` _(required)_ — The 3D Secure session ID. A 3D Secure session can be created using the [Create 3D Secure Session](/api#createThreeDSSession) API endpoint.
- `options` — Configuration options for the ThreeDSecure component.
  - `options.colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
  - `options.theme` `Object` — Allows you to customize the appearance of the component. See [Custom Styling](#custom-styling) for more information. **Note**: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
  - `options.size` `{ width: string, height: string }` — This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
  - `options.failOnChallenge` `Boolean | () => Boolean | () => Promise<Boolean>` — If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

#### threeDSecure.mount()

Mounts the component to the DOM. If no selector is provided the component will be rendered as a modal window.

```javascript
threeDSecure.mount();
```

**Parameters**

- `selector` `string` — The selector of the DOM node to mount the component to. If no selector is provided the component will be rendered as a modal window.

#### threeDSecure.on('success')

The 'success' event will be fired once the 3D Secure authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session](/api#retrieveThreeDSSession) endpoint to retrieve the cryptogram for the session and complete the payment.

**Note**: The component is automatically unmounted after the 'success' event is fired.

```javascript
threeDSecure.on("success", () => {
  // 3DS is complete and payment can be finalized
});
```

#### threeDSecure.on('failure')

The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.

**Note**: The component is automatically unmounted after the 'failure' event is fired.

```javascript
threeDSecure.on("failure", () => {
  // 3DS failed and user should be informed
});
```

#### threeDSecure.on('ready')

The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

```javascript
threeDSecure.on("ready", () => {
  document.getElementById("threeDSecure").removeClass("hide");
});
```

#### threeDSecure.on('error')

The error event will be fired if the component fails to load.

```javascript
threeDSecure.on("error", (error) => {
  console.error(error);
});
```

**Callback Parameters**

- `error.error` `String` — A unique code representing the error that occurred.
- `error.message` `String` — A human readable message describing the error.

#### threeDSecure.update()

Update the configuration for the component after it has been initialized. Any arguments passed will be merged with the arguments passed when the component was initialized.

```javascript
threeDSecure.update({
  size: {
    width: "300px",
    height: "400px",
  },
});
```

**Parameters**

- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `theme` — Allows you to customize the appearance of the component. See [Custom Styling](#custom-styling) for more information. **Note**: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
- `size` `{ width: string, height: string }` — This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
- `failOnChallenge` `Boolean | () => Boolean | () => Promise<Boolean>` — If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

#### threeDSecure.unmount()

Removes the component from the DOM.

```javascript
threeDSecure.unmount();
```

### ui.reveal

The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. Before using Reveal you'll first need to have a JSON endpoint to retrieve data from. This is often your own API endpoint combined with Relay to decrypt previously encrypted data from your database or a third-party API.

> 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!

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
// Create a request to your endpoint to fetch the data
const request = new Request("<YOUR_ENDPOINT>");
// Create a reveal instance, passing the request as an argument
const reveal = evervault.ui.reveal(request);
// Use JSON path to select the data in the response you want to
// display and mount it to the DOM.
reveal.text("$.card.number").mount("#card-number");
```

#### reveal.on("ready")

The ready event will be fired once the request has been completed and all reveal consumer components are ready to be shown.

```javascript
reveal.on("ready", () => {
  console.log("Reveal is ready");
});
```

#### reveal.on("error")

The error event will be fired if the Reveal Component fails to load or the passed request fails.

```javascript
reveal.on("error", () => {
  console.log("Something went wrong");
});
```

#### reveal.text()

Creates a Reveal Text consumer. The Reveal Text consumer allows you to render a selected field from the request response.

```javascript
const request = new Request("<YOUR_ENDPOINT>");
const reveal = evervault.ui.reveal(request);
const text = reveal.text("$.card.number", {
  format: {
    regex: /(.{4})(.{4})(.{4})(.{4})/g,
    replace: "$1 $2 $3 $4",
  },
});

text.mount("#card-number");
```

**Parameters**

- `path` `string` _(required)_ — The JSON path to the field you want to display.
- `options.colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `options.theme` `Theme` — Allows you to completely customize the appearance of the component. See [Custom Styling](#custom-styling) for more information.
- `options.format` `Object` — Allows you to use regex matching to format the field value.
  - `format.regex` `RegExp` _(required)_ — The regex statment to match against the value.
  - `format.replace` `string` _(required)_ — The text to replace the value with. You can use $ to reference matched regex groups.

##### text.mount()

Mounts the Reveal Text component to a given DOM node.

```javascript
text.mount("#card-details");
```

##### text.unmount()

Removes the Text Component from the DOM.

```javascript
text.unmount();
```

#### reveal.copyButton()

Creates a Reveal Copy Button consumer. This renders a button which when clicked will copy a response field to the users clipboard.

```javascript
const request = new Request("<YOUR_ENDPOINT>");
const reveal = evervault.ui.reveal(request);
const text = reveal.copyButton("$.card.number", {
  theme: evervault.ui.themes.clean(),
  text: "Copy Number",
  format: {
    regex: /(.{4})(.{4})(.{4})(.{4})/g,
    replace: "$1 $2 $3 $4",
  },
});

text.mount("#card-number");
```

**Parameters**

- `path` `string` _(required)_ — The JSON path to the field you want to display.
- `options.text` `string` — The text to display on the button.
- `options.icon` `string` — A URL for an icon to display on the button.
- `options.colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `options.theme` `Theme` — Allows you to completely customize the appearance of the component. See [Custom Styling](#custom-styling) for more information.
- `options.format` `Object` — Allows you to use regex matching to format the field value.
  - `format.regex` `RegExp` _(required)_ — The regex statment to match against the value.
  - `format.replace` `string` _(required)_ — The text to replace the value with. You can use $ to reference matched regex groups.

##### copyButton.on("copy")

The copy event will be fired when the button is clicked and the value has been copied to the clipboard.

```javascript
copyButton.on("copy", () => {
  console.log("Copied to clipboard");
});
```

##### copyButton.mount()

Mounts the Reveal Copy Button component to a given DOM node.

```javascript
copyButton.mount("#node");
```

##### copyButton.unmount()

Removes the Copy Button Component from the DOM.

```javascript
copyButton.unmount();
```

### transactions.create

Creates a transaction object that can be used with Apple Pay and Google Pay components.

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const transaction = evervault.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  merchantId: "merchant_abc123",
});
```

**Parameters**

- `options.amount` `number` _(required)_ — The transaction amount in smallest currency unit (e.g., cents).
- `options.currency` `string` _(required)_ — The three-letter ISO currency code.
- `options.country` `string` _(required)_ — The two-letter ISO country code.
- `options.merchantId` `string` _(required)_ — Your Evervault merchant ID.
- `options.type` `payment | disbursement | recurring` — Specify the type of transaction. Disbursement requests are only available with Apple Pay. Default: `payment`.
- `options.lineItems` `TransactionLineItem[]` — Optional array of line items to display in the payment sheet.
  - `lineItem.amount` `number` _(required)_ — The line item amount in the smallest currency unit.
  - `lineItem.label` `string` _(required)_ — Description of the line item.
  - `lineItem.type` `final | pending` — Whether the line item amount is final or still estimated. When `"pending"`, the Apple Pay sheet hides the amount. Defaults to `"final"`.
  - `lineItem.category` `line_item | subtotal | tax | discount | shipping_option` — The kind of line item. Currently only used by Google Pay, where it maps to `displayItems[].type`. Has no effect on Apple Pay or disbursements. Defaults to `"line_item"`.
- `options.requiredRecipientDetails` `string[]` — Optional array of recipient details required for collection on a disbursement transaction. Possible values: `name`, `email`, `phone`, `address`.
- `options.merchantCapabilities` `string[]` — Optional array of Apple Pay merchant capabilities for disbursement transactions. When omitted, defaults to `supports3DS`, and adds `supportsInstantFundsOut` when `instantTransfer` is set. Supported values: `supports3DS`, `supportsEMV`, `supportsCredit`, `supportsDebit`, `supportsInstantFundsOut`. On iOS the equivalent is the singular `merchantCapability` field on `DisbursementTransaction`.
- `options.managementURL` `string` — URL for managing the recurring payment subscription. Required when `type` is `recurring`.
- `options.billingAgreement` `string` — Description of the billing agreement shown to the user. Required when `type` is `recurring`.
- `options.description` `string` — Description of the recurring payment. Required when `type` is `recurring`.
- `options.regularBilling` `object` — Billing details for the recurring charge. Required when `type` is `recurring`.
  - `regularBilling.amount` `string` _(required)_ — The billing amount as a decimal string (e.g., `"2.13"`).
  - `regularBilling.label` `string` _(required)_ — Description of the billing charge.
  - `regularBilling.recurringPaymentStartDate` `Date` _(required)_ — The start date for the recurring payment.
  - `regularBilling.recurringPaymentIntervalUnit` `minute | hour | day | week | month | year` — The interval unit for the recurring payment frequency. The default value is "month".
  - `regularBilling.recurringPaymentIntervalCount` `number` — The number of interval units between each recurring charge. The default value is 1.
- `options.trialBilling` `object` — Optional trial billing details for the recurring payment.
  - `trialBilling.amount` `string` _(required)_ — The trial billing amount as a decimal string (e.g., `"0.99"`).
  - `trialBilling.label` `string` _(required)_ — Description of the trial billing charge.
  - `trialBilling.trialPaymentStartDate` `Date` _(required)_ — The start date for the trial period.

### ui.applePay

Initializes an Apple Pay button that handles the payment flow and returns encrypted payment details.

In [Sandbox apps](/developers/sandbox), the encrypted `networkToken.number` maps to a [test card](/cards/apple-pay#testing-sandbox) that matches the brand of the card the customer selects in their Apple Wallet.

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const transaction = evervault.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  merchantId: "<MERCHANT_ID>",
});

const component = evervault.ui.applePay(transaction, {
  process: async (data, { fail }) => {
    try {
      await processPayment(data);
    } catch (error) {
      fail({
        message: "Payment failed",
      });
    }
  },
});

component.mount("#apple-pay");
```

**Parameters**

- `transaction` `Transaction` _(required)_ — The transaction object created with [`transactions.create`](#transactionscreate).
- `options` `Object` _(required)_ — Configuration options for the Apple Pay button.
  - `options.process` `Function` _(required)_ — Callback function called when payment is authorized. Receives encrypted payment data and helper functions.
  - `options.type` `string` — Apple Pay button type. Possible values: `add-money`, `book`, `buy`, `check-out`, `continue`, `contribute`, `donate`, `order`, `pay`, `plain`, `reload`, `rent`, `set-up`, `subscribe`, `support`, `tip`, `top-up`
  - `options.style` `string` — Apple Pay button style. Possible values: `black`, `white`, `white-outline`
  - `options.locale` `string` — An ISO-639-1 code for localization.
  - `options.padding` `string` — The padding around the button as a CSS string with units (e.g., `"10px"`).
  - `options.borderRadius` `string | number` — The border radius of the button. This can be a string with units (e.g., `"10px"`) or a number (e.g., `10`).
  - `options.size` `{ width: number | string, height: number | string }` — An object defining the width and height of the button.
  - `options.allowedCardNetworks` `string[]` — An array of supported card networks. Supported card networks: `amex`, `bancomat`, `bancontact`, `cartesBancaires`, `chinaUnionPay`, `dankort`, `discover`, `eftpos`, `electron`, `elo`, `girocard`, `interac`, `jcb`, `mada`, `maestro`, `masterCard`, `mir`, `privateLabel`, `visa`, `vPay`
  - `options.requestPayerDetails` `string[]` — An array of payer details to request. Possible values: `name`, `email`, `phone`, `postalAddress`. `postalAddress` has no effect on recurring transactions. It's only honored for one-off payment transactions.
  - `options.requestBillingAddress` `boolean` — Whether to request billing address information.
  - `options.requestShipping` `boolean` — Whether to request shipping information.
  - `options.shippingType` `string` — Label for the shipping section on the Apple Pay sheet. One of `shipping`, `delivery`, `storePickup`, or `servicePickup`. Defaults to `shipping`.
  - `options.shippingMethods` `Object[]` — Shipping methods the customer can choose on the sheet. One-off payment transactions only — rejected for recurring and disbursement. Providing methods enables shipping on the sheet. Amounts use the same smallest-currency-unit convention as line items (e.g. cents).
    - `options.shippingMethods[].id` `string` _(required)_ — Unique identifier for the method. Returned as `shippingMethod.id` on the `process()` payload.
    - `options.shippingMethods[].label` `string` _(required)_ — Display label on the sheet (e.g. `"Standard Shipping"`).
    - `options.shippingMethods[].amount` `number` _(required)_ — Cost in the smallest currency unit (e.g. cents).
    - `options.shippingMethods[].detail` `string` — Optional secondary description (e.g. delivery estimate).
    - `options.shippingMethods[].selected` `boolean` — When `true`, this method is selected by default. If none are marked selected, the first method is selected. If the transaction `amount` already includes this method's cost, mark it selected.
  - `options.billingContact` `Object` — Prefill billing contact details on the Apple Pay sheet. Requires `requestBillingAddress: true` for the postal address to appear. Payment and recurring transactions only — ignored for disbursements.
    - `options.billingContact.givenName` `string` — Given (first) name.
    - `options.billingContact.familyName` `string` — Family (last) name.
    - `options.billingContact.emailAddress` `string` — Email address.
    - `options.billingContact.phoneNumber` `string` — Phone number.
    - `options.billingContact.addressLines` `string[]` — Street address lines.
    - `options.billingContact.locality` `string` — City or locality.
    - `options.billingContact.administrativeArea` `string` — State, province, or region.
    - `options.billingContact.postalCode` `string` — Postal or ZIP code.
    - `options.billingContact.countryCode` `string` — Two-letter ISO country code.
    - `options.billingContact.country` `string` — Country name.
    - `options.billingContact.phoneticGivenName` `string` — Phonetic reading of the given name (common in locales like Japan).
    - `options.billingContact.phoneticFamilyName` `string` — Phonetic reading of the family name (common in locales like Japan).
    - `options.billingContact.subLocality` `string` — Neighborhood or district within the locality.
    - `options.billingContact.subAdministrativeArea` `string` — County or subdivision within the administrative area.
  - `options.shippingContact` `Object` — Prefill shipping contact details on the Apple Pay sheet. Requires `requestShipping: true` for the postal address to appear. Payment and recurring transactions only — ignored for disbursements. Accepts the same fields as `billingContact`.
  - `options.supportsCouponCode` `boolean` — When `true`, shows a coupon code field on the Apple Pay sheet.
  - `options.couponCode` `string` — Initial coupon code shown in the sheet when `supportsCouponCode` is `true`.
  - `options.onCouponCodeChange` `Function` — Called when the customer changes the coupon code on the sheet. Receives the new coupon code string and must return a promise resolving to an updated `amount` and optional `lineItems`. You can also return an optional `error` (`code`: `couponCodeInvalid` or `couponCodeExpired`, plus `message`) to show validation feedback in the Apple Pay UI. Requires `supportsCouponCode: true`.
  - `options.applicationData` `string` — Opaque merchant data included on the Apple Pay request (`ApplePayRequest.applicationData`). Must be a Base64-encoded string.
  - `options.supportedCountries` `string[]` — Restrict payments to cards issued in these ISO 3166 country codes (`ApplePayRequest.supportedCountries`).
  - `options.onPaymentMethodChange` `Function` — Called when the user changes their payment method. Receives the new payment method and returns a promise resolving to an updated `amount` and optional `lineItems`. Requires `requestBillingAddress: true` to receive billing address data.
  - `options.onShippingAddressChange` `Function` — Called when the user changes their shipping address. Receives the new address and returns a promise resolving to an updated `amount` and optional `lineItems`. Requires `requestShipping: true`.
  - `options.onShippingMethodSelected` `Function` — Called when the user selects a shipping method on the sheet. Receives the selected method (`id`, `label`, `amount`, optional `detail`) and returns a promise resolving to an updated `amount` and optional `lineItems`. Requires `shippingMethods`. If omitted, the SDK recomputes the total from the selected method's amount.
  - `options.prepareTransaction` `Function` — Called before the Apple Pay modal is shown. Use this to perform async logic (e.g., fetch a discount) and return an updated `amount` and optional `lineItems`.
  - `options.appleMerchantId` `string` — Optional Apple Pay merchant identifier for the payment sheet. Defaults to `merchant.com.evervault.{merchantId}`, which works with Evervault's domain verification and merchant-session flow. A custom value is only used by the browser to open the Apple Pay sheet. It doesn't change merchant validation — that still uses Evervault's registered identifier unless separately configured with Apple for your domain.
  - `options.paymentOverrides` `Object` — Advanced overrides for the underlying Payment Request.
    - `options.paymentOverrides.paymentMethodData` `PaymentMethodData[]` — Override the payment method data passed to the Payment Request API.
    - `options.paymentOverrides.paymentDetails` `PaymentDetailsInit` — Override the payment details passed to the Payment Request API.
  - `options.disbursementOverrides` `Object` — Advanced overrides for disbursement Payment Requests.
    - `options.disbursementOverrides.disbursementDetails` `PaymentDetailsInit` — Override the disbursement details passed to the Payment Request API.

The object passed to `options.process` includes metadata on `card` when present. Optional `card.paymentMethodType` is `credit`, `debit`, `prepaid`, or `store` when the wallet reports the funding type for the card the user selected. See the [Apple Pay](/cards/apple-pay#process-the-payment) guide for how this relates to BIN-derived fields such as `funding`.

`paymentDataType` reflects the Apple token format from the credentials API (for example `3DSecure`). `transactionType` indicates the transaction category (`oneOff`, `recurring`, or `disbursement`) based on how you created the transaction. `transactionId` is Apple's identifier for the token, and comes from the [PKPaymentToken header](https://developer.apple.com/documentation/passkit/payment-token-format-reference#Header-keys-and-values). Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself. `billingContact` and `shippingContact` are only populated when the transaction requested those contact fields. `shippingMethod` is populated when you configured `shippingMethods` and the customer selected one. `phoneticFamilyName` and `phoneticGivenName` are populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). If there's no phonetic reading, then these two values are `null`.

#### applePay.mount()

Mounts the Apple Pay button to a given DOM node.

```javascript
component.mount("#apple-pay");
```

#### applePay.unmount()

Removes the Apple Pay button from the DOM. If an Apple Pay session is active, the sheet is dismissed first.

```javascript
component.unmount();
```

#### applePay.abort()

Programmatically dismisses the Apple Pay sheet while a session is in progress. This maps to the browser's [`PaymentRequest.abort()`](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/abort) API. When the sheet closes, the `cancel` event is fired.

Use this when you need to close and reopen Apple Pay — for example, when a shipping address change requires a different currency. Currency cannot be updated mid-session via `onShippingAddressChange`; abort the session, update the transaction, and let the user open Apple Pay again.

```javascript
onShippingAddressChange: async (address) => {
  const newCurrency = currencyForCountry(address.country);

  if (newCurrency !== transaction.details.currency) {
    await apple.abort();
    updateCheckoutCurrency(newCurrency);
    return { amount: 0, lineItems: [] };
  }

  return { amount: updatedAmount, lineItems };
},
```

`abort()` is a no-op when no session is in progress. After the user authorizes payment, use `fail()` in the `process` callback instead.

#### applePay.availability()

Checks whether Apple Pay is available on the current device. Returns a promise resolving to `"available"`, `"unavailable"`, or `"unsupported"`.

```javascript
const availability = await component.availability();

if (availability === "available") {
  component.mount("#apple-pay");
} else {
  // Show a fallback payment method
}
```

#### applePay.on("ready")

Fired when the Apple Pay button is mounted and ready to be displayed.

#### applePay.on("success")

Fired when the payment has been successfully authorized.

#### applePay.on("error")

Fired if there's an error initializing the Apple Pay button.

#### applePay.on("cancel")

Fired when the user cancels the Apple Pay payment flow.

### ui.googlePay

Initializes a Google Pay button that handles the payment flow and returns encrypted payment details.

```javascript
const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");
const transaction = evervault.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  merchantId: "MERCHANT_ID",
});

const googlePay = evervault.ui.googlePay(transaction, {
  type: "pay",
  color: "black",
  borderRadius: 4,
  allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
  allowedCardNetworks: ["VISA", "MASTERCARD"],
  process: async (data, { fail }) => {
    try {
      await processPayment(data);
    } catch (error) {
      fail({
        message: "Payment failed",
      });
    }
  },
});

googlePay.mount("#google-pay-button");
```

**Parameters**

- `transaction` `Transaction` _(required)_ — The transaction object created with [`transactions.create`](#transactionscreate).
- `options` `Object` _(required)_ — Configuration options for the Google Pay button.
  - `options.process` `Function` _(required)_ — Callback function called when payment is authorized. Receives encrypted payment data and helper functions.
  - `options.type` `string` — Google Pay button type. Possible values: `short`, `book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, `subscribe`
  - `options.color` `string` — Google Pay button color. Possible values: `black`, `white`
  - `options.locale` `string` — An ISO-639-1 code for localization.
  - `options.size` `{ width: number | string, height: number | string }` — An object defining the width and height of the button.
  - `options.allowedAuthMethods` `string[]` — Allowed authentication methods. With `CRYPTOGRAM_3DS` set, users on mobile can authenticate with their fingerprint which acts as a Strong Customer Authentication and so a cryptogram and ECI value are returned. Users on web cannot authenticate with their fingerprint so only the PAN is returned. Possible values: `PAN_ONLY`, `CRYPTOGRAM_3DS`
  - `options.allowedCardNetworks` `string[]` — An array of supported card networks. Supported card networks: `AMEX`, `DISCOVER`, `ELECTRON`, `ELO`, `ELO_DEBIT`, `INTERAC`, `JCB`, `MAESTRO`, `MASTERCARD`, `VISA`
  - `options.colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
  - `options.emailRequired` `boolean` — When set to true, the user will be required to provide their email address.
  - `options.billingAddress` `boolean | Object` — Request billing address information.
    - `billingAddress.format` `FULL | MIN` — Format of the billing address. `FULL` will request the full address, `MIN` will only request name, country code and postal code.
    - `billingAddress.phoneNumber` `boolean` — Whether to request the phone number.
  - `options.checkoutOption` `string` — Whether to show a `Continue` or `Pay Now` button on the Google Pay sheet. Possible values: `DEFAULT`, `COMPLETE_IMMEDIATE_PURCHASE`, `CONTINUE_TO_REVIEW`. `COMPLETE_IMMEDIATE_PURCHASE` requires `totalPriceStatus` to be `FINAL` (the default), or Google Pay rejects the request. Defaults to `DEFAULT`.
  - `options.transactionId` `string` — A merchant-generated ID for this transaction, used by Google Pay for fraud correlation.
  - `options.totalPriceStatus` `string` — Whether the total price is known and final, or still an estimate. Possible values: `FINAL`, `ESTIMATED`. Defaults to `FINAL`.
  - `options.allowPrepaidCards` `boolean` — Whether to allow prepaid cards. Defaults to `true`.
  - `options.allowCreditCards` `boolean` — Whether to allow credit cards. Defaults to `true`.
  - `options.softwareInfo` `Object` — Identifies the software used to integrate with Google Pay, for Google's own metrics.
    - `softwareInfo.id` `string` — An identifier for your integration. Your domain name can be used as the identifier.
    - `softwareInfo.version` `string` — The version of your integration.
  - `options.assuranceDetailsRequired` `boolean` — When true, requests that Google Pay perform cardholder ID&V or possession checks and return the result as `assuranceDetails` on the `process` payload. Defaults to `false`.
  - `options.existingPaymentMethodRequired` `boolean` — When true, the button is only displayed if the user has a saved payment method in their Google account. This is checked when the button is set up, not when it's clicked. Defaults to `false`.
  - `options.prefetchPaymentData` `boolean` — When true, Google Pay prepares the payment sheet as soon as the button is ready, so it opens faster on click. It has no effect on the `process` result. Defaults to `false`.

The object passed to `options.process` includes metadata on `card` when present. Optional `card.paymentMethodType` matches Google Pay's funding source for the selected card when available. Fields like `brand`, `funding`, `segment`, `country`, `currency`, and `issuer` are optional and omitted when unavailable. See the [Google Pay](/cards/google-pay#process-the-payment) guide.

When `assuranceDetailsRequired` is set, the payload also includes an `assuranceDetails` object (cleartext, not processed by Evervault's backend) when Google Pay returns one.

#### googlePay.on("success")

Fired when the payment has been successfully authorized.

#### googlePay.on("error")

Fired if there's an error initializing the Google Pay button.

#### googlePay.on("cancel")

Fired when the user cancels the Google Pay payment flow.

#### googlePay.on("ready")

Fired when the Google Pay button is ready to be displayed.

### Custom Styling

Some components in the SDK allow you to customize the appearance of the component using a `theme` object. A theme is just an object with a `styles` property. This styles property uses a CSS-as-JS format to define CSS rules for the component. These rules will be compiled to CSS and injected into the iframe.

Although you can customize the CSS inside of the iframe, you cannot modify the HTML. We know that layout can have a big impact on style definitions and so to help with this, we apply custom attributes to various elements within the iframe. These attributes are prefixed with ev-.

You can see our premade [Card Collection themes](https://github.com/evervault/evervault-js/tree/master/packages/themes) for an example of how these attributes can be used when creating themes.

```javascript
const theme = {
  styles: {
    ":root": {
      "color-scheme": "light",
    },
    label: {
      fontSize: 11,
      fontWeight: 500,
      textTransform: "uppercase",
    },
    ".error": {
      color: "red",
      fontSize: 12,
      marginTop: 5,
    },
    ".field input": {
      marginTop: 5,
      padding: "8px 12px",
      border: "2px solid #dddddd",
    },
    ".field:focus-within input": {
      borderColor: "#6633ee",
    },
  },
};
```

#### Responsive Styling

You can define media queries inside of the themes `styles` object, however, this may lead to unexpected behaviour as the media queries will be matched against the iframe document, not the parent document. To get around this, we provide a media utility which allows you to define styles based on media queries that match the parent document.

To access the media utility you will need to define your theme as a function that returns a theme object. This function will be passed a utilities object as an argument, which contains the media utility. The media utility should be spread into the styles object of the returned theme.

```javascript
const theme = (utilities) => {
  return {
    styles: {
      label: {
        fontSize: 16,
      },
      ...utilities.media("(max-width: 400px)", {
        label: {
          fontSize: 20,
        },
      }),
    },
  };
};
```


---

# Node.js

_Encrypt data server-side, invoke Functions, Enclaves and proxy requests through Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

First, let's install the Evervault SDK using your package manager of choice.

### Initialize the SDK

Now, let's initialize the SDK using our app's ID and our app's API key. If you don't have an API key yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");
```

## Relay proxies

SDKs that support using proxies can be configured to use Relay, use the `createRelayHttpsAgent()` function to return a pre-configured `HTTPSProxyAgent`. The Agent will use the HTTP CONNECT protocol to establish a connection to Relay. Below is how you would configure Relay with the Stripe Node.js SDK.

```javascript
const httpsAgent = evervault.createRelayHttpsAgent();

const stripe = Stripe("sk_test_...", {
  maxNetworkRetries: 1,
  httpAgent: httpsAgent,
  timeout: 1000,
  host: "api.example.com",
  port: 123,
  telemetry: true,
});
```

The `HTTPSProxyAgent` can also be used with popular HTTP clients like [axios](https://github.com/axios/axios). Its important to note that the URL of the request is not the Relay URL but the URL of the target.

```javascript
// Send a singular request with encrypted data to a third-party API
const httpsAgent = evervault.createRelayHttpsAgent();
const payload = { sensitiveField: "sensitive value" };
const response = await axios.post("https://example.com", payload, {
  httpsAgent,
  headers: {
    "Content-Type": "application/json",
  },
});
```

## Reference

### Evervault

You have to pass your app's ID and API key to initialize the SDK. You can also pass an `options` object with additional configuration settings.

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");
```

**Parameters**

- `appId` `String` _(required)_ — Your Evervault App's ID.
- `apiKey` `String` _(required)_ — Your Evervault app's API key.
- `options` `Object` — An optional configuration object.
  - `options.httpAgent` `http.Agent` — A custom Node.js [HTTP Agent](https://nodejs.org/api/http.html#class-httpagent) used for all outbound HTTP SDK requests. This can be used for local development or testing if you need to mock responses from Evervault, but don't use it in production systems.
  - `options.httpsAgent` `https.Agent` — A custom Node.js [HTTPS Agent](https://nodejs.org/api/https.html#class-httpsagent) used for all outbound HTTPS SDK requests. Use this when you need granular control over networking behavior, such as connection pooling, keep-alive settings, or routing requests through an HTTP proxy. When omitted, the SDK uses the default global agent.

#### Using a custom agent

You can pass a custom agent to control connection behavior for all requests made by the SDK. This is useful for scenarios such as connection pooling with `keepAlive`, or routing SDK traffic through a corporate proxy.

```javascript
const https = require("https");
const Evervault = require("@evervault/sdk");

// Keep connections alive to reduce latency on subsequent requests
const agent = new https.Agent({ keepAlive: true });

const evervault = new Evervault("<APP_ID>", "<API_KEY>", { httpsAgent: agent });
```

To route SDK requests through an HTTP proxy, use a proxy agent library such as [https-proxy-agent](https://www.npmjs.com/package/https-proxy-agent).

```javascript
const { HttpsProxyAgent } = require("https-proxy-agent");
const Evervault = require("@evervault/sdk");

const agent = new HttpsProxyAgent("https://proxy.example.com:8080");

const evervault = new Evervault("<APP_ID>", "<API_KEY>", { httpsAgent: agent });
```

### encrypt()

Encrypts data using [Evervault Encryption](/developers/evervault-encryption).

To encrypt strings using the Node.js SDK, simply pass a String or an Object into the evervault.encrypt() function. To encrypt a file, pass a `Buffer`.

The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with [Relay](/relay).

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");

// encrypt a string
const encrypted = await evervault.encrypt("Hello, world!");

// encrypt a file
const fileContents = fs.readFileSync("<input-file>");
const encryptedFile = await evervault.encrypt(fileContents);
fs.writeFileSync("<output-file>", encryptedFile);
```

**Parameters**

- `data` `String | Boolean | Number | Object | Buffer` _(required)_ — The data to encrypt.

### decrypt()

Decrypts data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");

const encrypted = await evervault.encrypt("Hello, world!");
const decrypted = await evervault.decrypt(encrypted);
console.log(decrypted);
// Hello, world!
```

**Parameters**

- `data` `String | Object | Buffer` _(required)_ — The data to decrypt.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### createClientSideDecryptToken()

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```javascript
const encryptedData = await evervault.encrypt("foo");
const now = new Date();
const timeInFiveMinutes = now.setMinutes(now.getMinutes() + 5);

const token = await evervault.createClientSideDecryptToken(
  encryptedData,
  timeInFiveMinutes
);
```

**Parameters**

- `payload` `String | Object | Buffer` _(required)_ — The payload containing the encrypted data that the token will be used to decrypt.
- `timeToLive` `Number` — The time the token will expire. Defaults to 5 minutes in the future.

### run()

Lets you invoke an Evervault [Function](/functions) with a given payload.

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");

const result = await evervault.functions.run("hello-function", {
  name: "Claude Shannon",
  ssn: "ev:encrypted_string",
});
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `data` `Object` _(required)_ — The payload to pass to the function.

Successful Function runs will return an object containing a Function Run ID and the result from your Function in the following format:

```json
{
  "id": "func_run_09413338da56",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name",
    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
  }
}
```

### createRunToken()

Creates a single use, time bound token (5 minutes) for invoking an Evervault [Function](/functions) with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```javascript
const Evervault = require("@evervault/sdk");
const evervault = new Evervault("<APP_ID>", "<API_KEY>");

const runToken = await evervault.createRunToken("hello-function", {
  name: "Claude Shannon",
  ssn: "ev:encrypted_string",
});
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `data` `Object` — The data you want to send to the function. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

When you create a Run Token, the SDK will return a JSON object containing your token.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWZ1bmN0aW9uIiwicnVuSWQiOiI0YjI4ZjMzZS1lNzY2LTQyNjgtYjZmNi01MmM2ZDNlZjBkM2MiLCJleHAiOjE3NjcyMjU2MDB9.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
}
```

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```

### enableOutboundRelay()

> We recommend using the `createRelayHttpsAgent()` function instead of this
>   function if the SDK you are using supports proxy agents.

Automatically configures your application to proxy requests through Relay when making requests to domains you have configured Relays for inside of the Evervault Dashboard. See [Relay](/relay) to learn more.

```javascript
await evervault.enableOutboundRelay();
```

**Parameters**

- `options.decryptionDomains` `String[]` — Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created in the Evervault dashboard.
- `options.debugRequests` `Boolean` — Output request domains and whether they were sent through Relay.

### createRelayHttpsAgent()

The HTTPSProxyAgent allows for more granular control over what requests gets sent through Relay. This can be passed to any client that supports the [Node.js Agent](https://nodejs.org/api/http.html#class-httpagent) as a parameter.

```javascript
const axios = require("axios");
const httpsAgent = evervault.createRelayHttpsAgent();
const payload = { sensitiveField: "sensitive value" };
const response = await axios.post("https://example.com", payload, {
  httpsAgent,
  headers: {
    "Content-Type": "application/json",
  },
});
```

### createEnclaveHttpsAgent()

Returns a HTTPS Agent which can be used to attest all TLS connections to your Evervault Enclave. See Enclave's [TLS Attestation](/enclaves#attestation) to learn more.

```javascript
const AttestationBindings = require("@evervault/attestation-bindings");

const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent(
  {},
  AttestationBindings
);

const response = await axios.post(
  "https://my-enclave.my-app.enclave.evervault.com",
  encrypted,
  {
    httpsAgent: enclaveHttpsAgent,
  }
);
```

**Parameters**

- `enclaveAttestationData` `Object` — A mapping of Enclave names to their PCRs or Callbacks which resolve to PCRs. This is optional. When included, the connection will only be attested when the PCRs match exactly. The provided data can be either a single Object, or an Array of Objects to allow roll-over between different sets of PCRs. If not provided, the attestation doc and its signature will be validated but the PCRs will be ignored.
  - `enclaveAttestationData.[enclaveName].pcr0` `String` — The PCR0 to use when attesting the given Enclave. Defaults to undefined.
  - `enclaveAttestationData.[enclaveName].pcr1` `String` — The PCR1 to use when attesting the given Enclave. Defaults to undefined.
  - `enclaveAttestationData.[enclaveName].pcr2` `String` — The PCR2 to use when attesting the given Enclave. Defaults to undefined.
  - `enclaveAttestationData.[enclaveName].pcr8` `String` — The PCR8 to use when attesting the given Enclave. Defaults to undefined.
- `evervaultAttestationBindings` — The Evervault Attestation Bindings distributed as `@evervault/attestation-bindings` on npm. For testing, you can provide a mock object with a single async attestEnclave function.

#### Using static PCRs

The most simple way to set up your Evervault client to attest Enclaves is to provide hardcoded PCRs. This approach is not recommended for production deployments, as your clients will fall out of sync from the Enclave during deployments.

```javascript
const AttestationBindings = require("@evervault/attestation-bindings");
const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent({
  "my-enclave": {
    pcr0: "...",
    pcr1: "...",
    pcr2: "...",
    pcr8: "...",
  },
  AttestationBindings,
});
```

#### Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active deployments of an Enclave. This can be used to keep your Client in sync with your Enclave across deployments.

```javascript
const AttestationBindings = require("@evervault/attestation-bindings");
const axios = require("axios");

async function resolveEnclavePCRsFromEvervaultAPI() {
  const { data: responseBody } = await axios.get(
    "https://api.evervault.com/enclaves/my-enclave/attestation",
    {
      headers: {
        "x-evervault-app-id": "app_1234", // replace with your app uuid
      },
    }
  );
  /**
   * The API Responds with the enclave attestation under the top level data key:
   * { "data": [{ "pcr0": "...",  ... }] }
   */
  return responseBody.data;
}

const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent(
  {
    "my-enclave": resolveEnclavePCRsFromEvervaultAPI,
  },
  AttestationBindings
);
```


---

# PHP

_Encrypt data server-side, invoke Functions, Enclaves and proxy requests through Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Dependencies

> The Evervault SDK requires PHP 7.1.0 or later.

The bindings also require the following extensions; `openssl`, `curl`, `json`, and `mbstring`.

If you install the bindings using Composer, these should automatically be installed. Otherwise, ensure that the extensions are available on your system.

### Install the SDK

Our PHP SDK is distributed via [Composer](https://getcomposer.org/), or it can be installed manually.

### Initialize the SDK

The SDK needs to be initialized with an App's ID and API key. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```php
<?php
use \Evervault\Evervault;

$evervault = new Evervault('<APP_ID>', '<API_KEY>');
```

### Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

```php
$encrypted = $evervault->encrypt('Hello, world!');
```

## Reference

### encrypt()

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). Evervault Strings can be used across all of our products. To encrypt data using the PHP SDK, simply pass a string or array into the encrypt() method. The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

```php
<?php
$evervault = new Evervault('<APP_ID>', '<API_KEY>');

$encrypted = $evervault->encrypt('Alice');

echo $encrypted;
```

**Parameters**

- `data` `string | array` _(required)_ — The data to encrypt.

### decrypt()

Decrypts the data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```php
$decrypted = $evervault->decrypt($encrypted)
```

**Parameters**

- `data` `string | array` _(required)_ — The data to decrypt.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### createClientsideDecryptToken()

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```php
<?php
$evervault = new Evervault('<APP_ID>', '<API_KEY>');
$encrypted = $evervault->encrypt('Alice');
$timeInFiveMinutes = time() + 5*60;

$token = $evervault->createClientSideDecryptToken($encrypted, $timeInFiveMinutes);
```

**Parameters**

- `payload` `string | array` _(required)_ — The payload containing encrypted data that the token will be used to decrypt.
- `expiry` `int` — The time the token will expire in Epoch seconds. Defaults to 5 minutes in the future.

### run()

Lets you invoke an [Evervault Function](/functions) with a given payload.

```php
<?php
$evervault = new Evervault('<APP_ID>', '<API_KEY>');

$encrypted = $evervault->encrypt('Alice');

$result = $evervault->run(
    'hello-function',
    (object) [
        'name' => 'Claude Shannon',
        'ssn' => 'ev:encrypted_string'
    ]
);
```

**Parameters**

- `functionName` `string` _(required)_ — The name of the function to invoke.
- `payload` `object` _(required)_ — The payload to pass to the function.

The `run()` function returns an associative array. This array includes a unique run ID, the status of the execution denoted as success or failure, and, in cases of a successful run, the output generated by the function.

```json
{
  "id": "func_run_09413338da56",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name",
    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
  }
}
```

### createRunToken()

Creates a single use, time bound token (5 minutes) for invoking an [Evervault Function](/functions) with a given payload. If the payload is an empty object, the Run Token will be valid for any payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```php
<?php
$evervault = new Evervault('<APP_ID>', '<API_KEY>');

$runToken = $evervault->createRunToken(
    'hello-function',
    (object) [
        'name' => 'Claude Shannon',
        'ssn' => 'ev:encrypted_string'
    ]
);

var_dump($runToken);
```

**Parameters**

- `functionName` `string` _(required)_ — The name of the function to invoke.
- `payload` `object` _(required)_ — Payload that the token can be used with.

When you create a Run Token, the SDK will return a JSON object **containing** your token which can then be passed to your client-side application.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
}
```

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```

> The payload used to invoke your Function must be identical to the payload used
>   to create the Run Token.

### enableOutboundRelay()

Configures your application to proxy HTTP requests using [Relay](/relay) for any requests to Relay destinations sent using the cURL handler provided.

Relay must be enabled for a `CurlHandle` after the destination URL has been set, and before `curl_exec()` is called.

```php
<?php
$evervault = new Evervault('<APP_ID>', '<API_KEY>');

$curlHandler = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://example.com');
$evervault->enableOutboundRelay($curlHandler);

$response = curl_exec($ch);
curl_close($ch);
```

**Parameters**

- `curlHandler` `CurlHandle` _(required)_ — If the destination URL has been added as an Relay destination in the Evervault Dashboard, any requests sent to this destination using the `CurlHandle` provided will be proxied through Relay.


---

# Python

_Encrypt data server-side, invoke Functions, Enclaves and proxy requests through Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

Our Python SDK is distributed via [pypi](https://pypi.org/project/evervault/), and can be installed using `pip`.

```bash
pip install evervault
```

### Initialize the SDK

The SDK needs to be initialized with an App's ID and API key. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

```python
import evervault
evervault.init("<APP_ID>", "<API_KEY>")
```

### Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

```python
encrypted = evervault.encrypt("Hello, world!")
```

## Reference

### init

Initializes the SDK with your API Key and App ID.

```python
import evervault

evervault.init(
    # Your App's ID
    app_id="<APP_ID>"
    # Your App's API key
    api_key="<API_KEY>",
)
```

**Parameters**

- `app_id` `String` _(required)_ — Your Evervault App's ID.
- `api_key` `String` _(required)_ — Your Evervault App's API Key.

### encrypt

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). To encrypt a string using the Python SDK, simply pass a `str` or a `dict`, to encrypt a file, pass a `bytes` or `bytearray`. The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with [Relay](/relay).

```python
import evervault
evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")

## encrypt a string
encrypted = evervault.encrypt("Hello, world!")

## encrypt a file
with open("<input-filename>", mode="rb") as plaintext_file:
  contents = plaintext_file.read()
  encrypted_contents = evervault.encrypt(contents)
  with open("<output-filename>", "wb") as encrypted_file:
    encrypted_file.write(encrypted_contents)
```

**Parameters**

- `data` `str | dict | bytes | bytearray` _(required)_ — The data to encrypt.

### decrypt

Decrypts the data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```python
import evervault
evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
encrypted = evervault.encrypt("Hello, world!")
decrypted = evervault.decrypt(encrypted)
```

**Parameters**

- `data` `str | list | dict | bytes | bytearray` _(required)_ — The data to decrypt.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### run

Lets you invoke an [Evervault Function](/functions) with a given payload.

```python
import evervault
evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")

result = evervault.run("hello-function", {
  "name": "Claude Shannon",
  "ssn": "ev:encrypted_string"
})
```

**Parameters**

- `function_name` `str` _(required)_ — The name of the function to invoke.
- `payload` `dict` _(required)_ — The payload to pass to the function.
- `run_async` `bool` — Whether to run the Function asynchronously or not. Callback URL must be configured in the Evervault Dashboard to receive a webhook on Function completion. Asynchronous Function invocations must be enabled for your team by contacting support@evervault.com.

Successful Function runs will return a dictionary containing a Function Run ID and the result from your Function in the following format:

```json
{
  "id": "func_run_09413338da56",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name",
    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
  }
}
```

In the case of an asynchronous Function invocation the result will be in the following format:

```json
{
  "id": "func_run_09413338da56",
  "status": "scheduled"
}
```

### create_run_token

Creates a single use, time bound token (5 minutes) for invoking an [Evervault Function](/functions) with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```python
import evervault
evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")

result = evervault.create_run_token(
    "hello-function",
    {
        "name": "Claude Shannon",
        "ssn": "ev:encrypted_string"
    }
)
```

**Parameters**

- `function_name` `str` _(required)_ — The name of the function to invoke.
- `data` `dict` — Payload that the token can be used with. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

### create_client_side_decrypt_token

Client Side Decyrpt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads. By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```python
from datetime import datetime, timedelta
import evervault

evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
encrypted = evervault.encrypt("Hello, world!")
now = datetime.now()
time_in_five_minutes = now + timedelta(minutes=5)

token = evervault.create_client_side_decrypt_token(encrypted_data, time_in_five_minutes)
```

**Parameters**

- `payload` `str | list | dict | bytes | bytearray` _(required)_ — The data to decrypt.
- `expiry` `datetime` — The time the token will expire. Defaults to 5 minutes in the future.

When you create a Run Token, the SDK will return a JSON object containing your token.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
}
```

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```

### enable_outbound_relay

> This should only be used when you need to configure third party SDKs with
>   Relay. All other use cases should call Relay with a HTTP Client.

Configures your application to proxy HTTP requests using [Relay](/relay) based on the configuration created in the Evervault dashboard. See [Relay](/relay) to learn more.

Asynchronous HTTP requests are supported with [aiohttp](https://docs.aiohttp.org/). Pass in a [aiohttp.ClientSession](https://docs.aiohttp.org/en/stable/client_reference.html) to enable them for that session.

```python
evervault.enable_outbound_relay()
```

**Parameters**

- `decryption_domains` `str[]` — Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created using the Evervault dashboard.
- `debug_requests` `bool` — Output request domains and whether they were sent through Relay.
- `client_session` `aiohttp.ClientSession` — The [aiohttp](https://docs.aiohttp.org/) client session to enable relay on. Requires Python 3.11+.

### attestable_encalve_session

Returns a `Requests` session with will attest your Enclave during the [TLS handshake](/enclaves#attestationintls).

By default the client will attest the Enclave using the attestation document but will not make any assertions about the values of the PCRs. The attestation can be further scoped to the software running in your enclave by passing a dict mapping Enclave names to their corresponding PCRs.

```python
# assert that the Enclave was signed with a known cert
attested_session = evervault.attestable_enclave_session({
  'my-enclave': { 'pcr_8': '606e2c1cae65ee569799803388d2ca285ad5c325f9d7c0d4a38b3aa30bd729ba96a9a13e64577a622a0a1f050f722123' }
})

attested_session.post(
  'https://my-enclave.my-app.enclave.evervault.com',
  data=sensitive_payload
)
```

**Parameters**

- `enclave_attestation_data` — Optional constraints to assert that the PCRs present in the Enclave's attestation doc match the expected values. This can be either a single dict, or a list of dicts to allow roll-over between different sets of PCRs.You can also provide a callback function which returns a set of PCRs for an Enclave. This can make it easier to migrate your clients across Enclave deployments as the PCRs inevitably change.
  - `enclave_attestion_data.[enclaveName].pcr0` `str` — The PCR0 to use when attesting the given Enclave.
  - `enclave_attestion_data.[enclaveName].pcr1` `str` — The PCR1 to use when attesting the given Enclave.
  - `enclave_attestion_data.[enclaveName].pcr2` `str` — The PCR2 to use when attesting the given Enclave.
  - `enclave_attestion_data.[enclaveName].pcr8` `str` — The PCR8 to use when attesting the given Enclave.

#### Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active deployments of an Enclave. This can be used to keep your Client in sync with your Enclave across deployments.

```python
import evervault
import requests
import json

evervault.init(app_id="app_1234", api_key="my_api_key")

def resolve_pcrs_from_evervault():
   resp = requests.get('https://api.evervault.com/enclaves/my-enclave/attestation', headers={'x-evervault-app-id': 'app-1234'})
   payload = json.loads(resp)

   #The API returns PCRs in camelCase, so we convert them to snake_case
   snake_case_pcrs = {"data": [{k.replace('pcr', 'pcr_'): v for k, v in pcr.items()} for pcr in payload["data"]]}
   return snake_case_pcrs["data"]

attested_session = evervault.attestable_enclave_session({
  'my-enclave': resolve_pcrs_from_evervault
})

attested_session.post('https://my-enclave.app-1234.enclave.evervault.com', headers = { 'api-key': 'my_api_key' })
```


---

# React

_Encrypt data client-side, collect card details & perform 3D Secure authentication._

## Getting Started

Our React SDK is distributed via npm and can be installed using your preferred package manager.

Once installed, Initialize the SDK by wrapping your application with the `EvervaultProvider` component.

```jsx
import { EvervaultProvider } from "@evervault/react";

export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      ...
    </EvervaultProvider>
  );
}
```

## Encrypting Data

Once you've added the `<EvervaultProvider>`, you can access the `useEvervault()` hook in its children. The `useEvervault()` hook returns an initialized instance of the [JavaScript SDK](/sdks/javascript), which includes the `encrypt()` function. The `encrypt()` function can be used to encrypt plaintext data in your application.

```jsx
import { useState } from "react";
import { useEvervault } from "@evervault/react";

export default function ChildComponent() {
  const evervault = useEvervault();
  const [message, setMessage] = useState("");

  const handleSubmit = async (e) => {
    e.preventDefault();
    const encryptedMessage = await evervault.encrypt(message);
    alert(encryptedMessage);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button>Submit</button>
    </form>
  );
}
```

## Components

### EvervaultProvider

Sets up a client for interacting with Evervault. You must provide a `teamId` and `appId` to the provider.

```jsx
<EvervaultProvider teamId={String} appId={String}>
  {children}
</EvervaultProvider>
```

**Props**

- `teamId` `String` _(required)_ — The unique identifier for your Team.
- `appId` `String` _(required)_ — The unique identifier for your App.
- `onLoadError` `(error: unknown) => void` — A callback function that is called if the SDK fails to load. Use the [isScriptLoadError](/sdks/react#isscriptloaderror) utility to determine the cause of the error.
- `loadTimeout` `Number` — The timeout in milliseconds for the SDK to load. Defaults to `15000` (15s).

The `EvervaultProvider` accepts a `ref` that exposes a `reload()` method that you can use to reload the script if it fails.

**Ref Methods**

- `reload` `() => void` — Attempts to reload the Evervault script. Typically called in response to an `onLoadError` event.

### Card

The Card Component allows you to collect and encrypt card data in a completely PCI-compliant environment. See [Card Collection](/cards/card-collection) for more information.

```jsx
import { Card, themes } from "@evervault/react";
const theme = themes.clean();

export function Checkout() {
  const handleChange = (details) => {
    console.log(details);
  };

  return (
    <div>
      <Card theme={theme} onChange={handleChange} />
    </div>
  );
}
```

**Props**

- `theme` `Object` — The theme to use for the Card. See the [styling section](/cards/card-collection#styling) for more information.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `icons` `Boolean | Record<brand, string>` — If set to true, the component will display icons for the detected card brand. You can customize icons by passing an object with the brand as the key and src URL as the value.
- `autoFocus` `Boolean` — If set to true, the component will automatically focus the first field when the component is mounted.
- `autoProgress` `Boolean` — If set to true, the component automatically moves focus to the next field when the current field is complete.
- `autoComplete` `Object` — Controls browser autocomplete behavior per field.
  - `autoComplete.name` `Boolean` — Enable browser autocomplete for the name field.
  - `autoComplete.number` `Boolean` — Enable browser autocomplete for the card number field.
  - `autoComplete.expiry` `Boolean` — Enable browser autocomplete for the expiry field.
  - `autoComplete.cvc` `Boolean` — Enable browser autocomplete for the CVC field.
- `acceptedBrands` `string[]` — Restricts the component to only accept the specified card brands. If not provided, all brands are accepted. Possible values are `visa`, `mastercard`, `american-express`, `diners-club`, `discover`, `jcb`, `unionpay`, `maestro`, `elo`, `mir`, `hiper`, `hipercard`, `szep`, `uatp`, `rupay`. Custom brands defined using `customBrands` are accepted regardless of this list.
- `customBrands` `CustomBrand[]` — An array of custom card brand definitions. Use `evervault.brands.create` from the browser SDK to create them. Custom brands are always accepted, even when `acceptedBrands` is set. See the [custom card brands](/cards/card-collection?client=react#custom-card-brands) section for usage examples.
- `fields` `String[]` — Allows you to configure the fields displayed in the component. Possible values are `name`, `number`, `expiry`, and `cvc`. By default only number, expiry and cvc will be shown.
- `defaultValues` `Object` — Sets default values for card fields on mount.
  - `defaultValues.name` `String` — Default value for the cardholder name field.
- `redactCVC` `Boolean` — Sets the `type` attribute of the CVC field to `password` in order to visually redact the CVC field..
- `allow3DigitAmexCVC` `Boolean` — If set to false, rejects 3-digit CVCs for American Express cards and requires a 4-digit CVC. Defaults to `true`.
- `translations` `Object` — Allows you to customize the translations of the component.
  - `translations.name.label` — Customize the label for the name field.
  - `translations.name.placeholder` — Customize the placeholder for the name field.
  - `translations.name.errors.invalid` — Customize the error message for the name field when the value is invalid.
  - `translations.number.label` — Customize the label for the number field.
  - `translations.number.placeholder` — Customize the placeholder for the number field.
  - `translations.number.errors.invalid` — Customize the error message for the number field when the value is invalid.
  - `translations.expiry.label` — Customize the label for the expiry field.
  - `translations.expiry.placeholder` — Customize the placeholder for the expiry field.
  - `translations.expiry.errors.invalid` — Customize the error message for the expiry field when the value is invalid.
  - `translations.cvc.label` — Customize the label for the cvc field.
  - `translations.cvc.placeholder` — Customize the placeholder for the cvc field.
  - `translations.cvc.errors.invalid` — Customize the error message for the cvc field when the value is invalid.
- `validation` `Object` — Allows you to customize the validation logic of the component.
  - `validation.name.regex` `RegExp` — A regex pattern that the name must match in order to be considered valid. You can use this option to only allow certain characters.
  - `validation.cvc.optional` `Boolean` — When set to `true`, the CVC field is treated as optional. The card is considered valid even if no CVC is entered. If a CVC is entered, it is validated as normal. Defaults to `false`.
- `onChange` `(payload: Object) => void` — Triggered whenever the component's state is updated. **Payload** - `card.name` `String` — The card holder name. - `card.number` `String` — The encrypted card number. This will only be present if the number is valid. - `card.brand` `String` — The brand that issued the card. - `card.lastFour` `String` — The last 4 digits of the card. This will only be present if the number is valid. - `card.bin` `String` — The bin for the card. This will only be present if the number id valid. - `card.expiry.month` `String` — The month for the card expiry field. - `card.expiry.year` `String` — The year for the card expiry field. - `card.cvc` `String` — The encrypted card CVC. - `card.errors` `Object` — Validation errors related to the card details. - `card.isValid` `Boolean` — Whether or not there are any errors shown in the component. - `card.isComplete` `Boolean` — Whether or not all of the fields have been filled out successfully with valid values.
- `onComplete` `(payload: Object) => void` — Triggered when the component is complete. **Payload** - `card.name` `String` — The card holder name. - `card.number` `String` — The encrypted card number. This will only be present if the number is valid. - `card.brand` `String` — The brand that issued the card. - `card.lastFour` `String` — The last 4 digits of the card. This will only be present if the number is valid. - `card.bin` `String` — The bin for the card. This will only be present if the number id valid. - `card.expiry.month` `String` — The month for the card expiry field. - `card.expiry.year` `String` — The year for the card expiry field. - `card.cvc` `String` — The encrypted card CVC. - `card.errors` `Object` — Validation errors related to the card details. - `card.isValid` `Boolean` — Whether or not there are any errors shown in the component. - `card.isComplete` `Boolean` — Whether or not all of the fields have been filled out successfully with valid values.
- `onValidate` `(payload: Object) => void` — Triggered when the component is programmatically validated with the `validate()` ref method. **Payload** - `card.name` `String` — The card holder name. - `card.number` `String` — The encrypted card number. This will only be present if the number is valid. - `card.brand` `String` — The brand that issued the card. - `card.lastFour` `String` — The last 4 digits of the card. This will only be present if the number is valid. - `card.bin` `String` — The bin for the card. This will only be present if the number id valid. - `card.expiry.month` `String` — The month for the card expiry field. - `card.expiry.year` `String` — The year for the card expiry field. - `card.cvc` `String` — The encrypted card CVC. - `card.errors` `Object` — Validation errors related to the card details. - `card.isValid` `Boolean` — Whether or not there are any errors shown in the component. - `card.isComplete` `Boolean` — Whether or not all of the fields have been filled out successfully with valid values.
- `onSwipe` `(payload: Object) => void` — Triggered when the component is swiped.
  - `brand` `String` — The brand that issued the card.
  - `localBrands` `String[]` — The brands that are supported by the component.
  - `number` `String` — The card number.
  - `expiry` `Object` — The expiry date of the card.
  - `firstName` `String` — The first name of the card holder.
  - `lastName` `String` — The last name of the card holder.
  - `lastFour` `String` — The last 4 digits of the card.
  - `bin` `String` — The bin for the card.
- `onFocus` `(event: { field: string, data: Object }) => void` — Triggered when a card field receives focus. The `field` property identifies which field received focus (`name`, `number`, `expiry`, or `cvc`).
- `onBlur` `(event: { field: string, data: Object }) => void` — Triggered when a card field loses focus. The `field` property identifies which field lost focus (`name`, `number`, `expiry`, or `cvc`).
- `onKeyUp` `(event: { field: string, data: Object }) => void` — Triggered on a key-up event within a card field. The `field` property identifies the active field.
- `onKeyDown` `(event: { field: string, data: Object }) => void` — Triggered on a key-down event within a card field. The `field` property identifies the active field.
- `onReady` `() => void` — Triggered when the component has loaded and is ready to be used.
- `onError` `() => void` — Triggered when the component encounters an error and fails to load.

The `Card` component accepts a `ref` that exposes the following methods:

**Ref methods**

- `validate` `() => void` — Programmatically triggers validation on all card fields and emits a `validate` event with the current payload. Use this with the `onValidate` callback to implement submit-time validation.

### ThreeDSecure

The ThreeDSecure component can be used instead of the [useThreeDSecure](/sdks/react#useThreeDSecure) hook when you want more control over how and where the 3D Secure iframe is displayed. In order to use the component you must first [create a 3D Secure session](/api#createThreeDSSession) on your backend.

```jsx
import { ThreeDSecure } from "@evervault/react";

export function MyComponent() {
  const handleSuccess = () => {
    console.log("3D Secure authentication complete");
  };

  return (
    <ThreeDSecure session="tds_visa_123456789" onSuccess={handleSuccess} />
  );
}
```

**Props**

- `session` `String` _(required)_ — The 3D Secure session ID. A 3D Secure session can be created using the [API](/api#createThreeDSSession).
- `theme` `Object` — Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `size` `{ width: string, height: string }` — This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
- `failOnChallenge` `Boolean | () => Boolean | () => Promise<Boolean>` — If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.
- `onSuccess` `Function` — The 'success' event will be fired once the 3D Secure authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session](/api#retrieveThreeDSSession) endpoint to retrieve the cryptogram for the session and complete the payment.
- `onFailure` `Function` — The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.
- `onError` `Function` — The error event will be fired if the component fails to load.
- `onReady` `Function` — The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

### Reveal

The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. See [Card Reveal](/cards/reveal) for more information.

```jsx
import { useMemo } from "react";
import { Reveal } from "@evervault/react";

export function MyComponent() {
  const request = useMemo(() => {
    return new Request("<YOUR_ENDPOINT>");
  }, []);

  return (
    <Reveal request={request}>
      <Reveal.Text path="$.card.number" />
      <Reveal.CopyButton path="$.card.number" text="Copy Number" />
    </Reveal>
  );
}
```

**Props**

- `request` `Request` _(required)_ — The request to use to fetch the encrypted data.
- `onReady` `Function` — Triggered when the component has fully loaded and is ready to be shown.
- `onError` `Function` — Triggered when the component fails to load.

### Reveal.Text

Creates a Reveal Text consumer component. The Reveal Text consumer allows you to render a selected field from the request response. This component must be rendered as a child of the Reveal component.

```jsx
import { useMemo } from "react";
import { Reveal } from "@evervault/react";

export function MyComponent() {
  const request = useMemo(() => {
    return new Request("<YOUR_ENDPOINT>");
  }, []);

  return (
    <Reveal request={request}>
      <Reveal.Text path="$.user.pin" />
    </Reveal>
  );
}
```

**Props**

- `theme` `Object` — Allows you to completely customize the appearance of the component.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `path` `String` _(required)_ — A [JSON path](https://jsonpath.com/) selector for the response field you want to display.
- `format` `Object` — Allows you to use regex matching to format the field value.
  - `regex` `String` _(required)_ — The regex statement to match against the value.
  - `replace` `String` _(required)_ — The text to replace the value with. You can use $ to reference matched regex groups.

### Reveal.CopyButton

Creates a Reveal Copy Button consumer component. This renders a button which when clicked will copy a response field to the users clipboard. This component must be rendered as a child of the Reveal component.

```jsx
import { useMemo } from "react";
import { Reveal } from "@evervault/react";

export function MyComponent() {
  const request = useMemo(() => {
    return new Request("<YOUR_ENDPOINT>");
  }, []);

  return (
    <Reveal request={request}>
      <Reveal.CopyButton path="$.card.number" />
    </Reveal>
  );
}
```

**Props**

- `path` `String` _(required)_ — A [JSON path](https://jsonpath.com/) selector for the response field you want to copy.
- `theme` `Object` — Allows you to completely customize the appearance of the component.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `format` `Object` — Allows you to use regex matching to format the field value.
  - `regex` `String` _(required)_ — The regex statement to match against the value.
  - `replace` `String` _(required)_ — The text to replace the value with. You can use $ to reference matched regex groups.
- `onCopy` `() => void` — A callback function that is called when the button is clicked.

### Pin

Creates a Pin component which allows you to collect and encrypt pin numbers in a completely PCI-compliant environment.

```jsx
import { Pin, themes } from "@evervault/react";
const theme = themes.clean();

export function MyComponent() {
  const handleChange = (details) => {
    console.log(details);
  };

  return (
    <div>
      <Pin theme={theme} onChange={handleChange} />
    </div>
  );
}
```

**Props**

- `theme` `Object` — The theme to use for the Pin.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `autoFocus` `Boolean` — If set to true, the component will automatically steal focus when it mounts.
- `length` `Number` — Change the length of the pin number.
- `mode` `numeric | alphanumeric` — If set to 'alphanumeric' the pin number will also accept letters as input.
- `inputType` `"number" | "text" | "password"` — Sets the `type` attribute of the underlying input elements used to capture the pin. Defaults to `"number"`.
- `onChange` `(payload: Object) => void` — Triggered whenever the component's state is updated.
  - Payload
  - `value` `String` — The encrypted pin number.
  - `isComplete` `Boolean` — Whether or not the pin number field is complete.
- `onComplete` `(payload: Object) => void` — Triggered when the pin number field has been fully filled out by the user.
  - Payload
  - `value` `String` — The encrypted pin number.
  - `isCompleteBoolean` `Boolean` — Whether or not the pin number field is complete.
- `onReady` `Function` — Triggered when the component has fully loaded and is ready to be shown.
- `onError` `Function` — Triggered when the component fails to load. If you want to respond to validation errors you should use the change event instead.

## Hooks

### useEvervault

The `useEvervault` hook is accessible in children of the EvervaultProvider, and returns an initialized instance of the Evervault [JavaScript SDK](/sdks/javascript). One of the functions included in the returned object is `encrypt()`, which can be passed any plaintext data structure.

```jsx
const evervault = useEvervault();
```

#### .encrypt()

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products. It is accessible on the returned value from the `useEvervault()` hook. To encrypt data using the React.js SDK, simply pass a String or an Object into the `evervault.encrypt()` function.

The encrypted data can be passed to your server and stored in your database as normal. It can also be used with any of Evervault's other services.

```jsx
function MyComponent() {
  const evervault = useEvervault();

  const handleEncrypt = async () => {
    const encrypted = await evervault.encrypt("Hello, world!");
    console.log(encrypted);
  };

  return <button onClick={handleEncrypt}>Encrypt</button>;
}
```

**Parameters**

- `data` `String | Object | Array | File | Blob` _(required)_ — The data to encrypt.

#### .decrypt()

Allows you to decrypt a previously encrypted piece of data using a client side token. The token is a time bound token for decrypting data. The token can be generated using our [backend SDKs](/sdks) or through our [REST API](/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.

```jsx
const evervault = useEvervault();
const data = await evervault.encrypt("Hello, world!");
const decrypted = await evervault.decrypt("[client-side-token]", data);
```

**Parameters**

- `token` `String` _(required)_ — A valid [client-side token](/api#client-side-tokens) with permissions to decrypt the data.
- `data` `String | Object` _(required)_ — The encrypted data to decrypt.

#### .brands.create()

Creates a custom card brand definition that can be passed to the `customBrands` prop on [`Card`](#card). Use this to add support for card networks that aren't included in Evervault's built-in brand list.

```javascript
const acmeBrand = evervault.brands.create("acme-card", {
  numberValidationRules: {
    ranges: [9900, [88000, 88999]],
    lengths: [16],
  },
  securityCodeValidationRules: {
    lengths: [3],
  },
})
```

**Parameters**

- `name` `string` _(required)_ — A unique identifier for the brand. This value is returned in the `localBrands` array of the card change payload.
- `options` `Object` _(required)_ — Configuration for the custom brand.
  - `options.numberValidationRules` `Object` _(required)_ — Rules used to validate card numbers for this brand.
    - `options.numberValidationRules.ranges` `Array<number | [number, number]>` _(required)_ — Bank identification number (BIN) prefixes or ranges that identify cards belonging to this brand. A single number matches cards starting with that prefix (e.g., `9900`). A two-element tuple defines an inclusive range of BIN prefixes (e.g., `[88000, 88999]`).
    - `options.numberValidationRules.lengths` `number[]` _(required)_ — The valid card number lengths for this brand.
    - `options.numberValidationRules.luhnCheck` `Boolean` — Whether to validate the card number using the Luhn algorithm. Defaults to `true`.
  - `options.securityCodeValidationRules` `Object` _(required)_ — Rules used to validate the CVC for this brand.
    - `options.securityCodeValidationRules.lengths` `Array<3 | 4>` _(required)_ — The valid CVC lengths for this brand. Accepts 3, 4 or both.
  - `options.iconSrc` `string` — A URL for the brand's icon. Displayed in the card component when a matching card number is entered.

### useThreeDSecure

The useThreeDSecure hook can be used in combination with the Evervault API to perform 3D Secure authentication. In order to use the hook you must first [create a 3D Secure session](/api#createThreeDSSession) on your backend and pass it to your frontend. The hook will manage displaying the 3D Secure iframe inside of a modal window and handle the authentication process.

Note: If you want more control over how and where the 3D Secure iframe is displayed you can use the [ThreeDSecure](/sdks/react#three-d-secure) component instead.

See [3D Secure](/cards/3d-secure) for more information.

```jsx
import { Card, useThreeDSecure } from "@evervault/react";
import { createThreeDSSession, finalizePayment } from "./api";

function Checkout() {
  const threeDSecure = useThreeDSecure();

  const handlePay = async () => {
    const session = await createThreeDSSession();
    threeDSecure.start(session, {
      onSuccess: () => {
        finalizePayment(session);
      },
    });
  };

  return (
    <>
      <Card />
      <button onClick={handlePay}>Pay</button>
    </>
  );
}
```

**Options**

- `theme` `Object` — Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
- `colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `size` `{ width: string, height: string }` — This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
- `failOnChallenge` `Boolean | () => Boolean | () => Promise<Boolean>` — If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

#### threeDSecure.start()

The start function is used to begin the 3D Secure authentication process.

**Parameters**

- `session` `String` _(required)_ — The 3D Secure session ID. A 3D Secure session can be created using the [API](/api#createThreeDSSession).
- `options.onSuccess` `Function` — The 'success' event will be fired once the 3D Secure authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session](/api#retrieveThreeDSSession) endpoint to retrieve the cryptogram for the session and complete the payment.
- `options.onFailure` `Function` — The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.
- `options.onError` `Function` — The error event will be fired if the component fails to load.
- `options.onReady` `Function` — The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

#### threeDSecure.update()

The update function updates the options passed to the active 3D Secure instance without restarting the authentication flow.

**Parameters**

- `options.theme` `Object` — Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
- `options.colorScheme` `string` — Allows you to set the root [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
- `options.size` `{ width: string, height: string }` — This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
- `options.failOnChallenge` `Boolean | () => Boolean | () => Promise<Boolean>` — If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

## Utilities

### isScriptLoadError

The `isScriptLoadError` function can be used to determine if an error was caused by the Evervault.js browser script failing to load.

```jsx
<EvervaultProvider teamId="..." appId="..." onLoadError={(error) => {
  if (isScriptLoadError(error)) {
    console.error("Failed to load for reason:", error.code, error.message);
  } else {
    console.error("An error occurred:", error);
  }
}}>
```

**Known Error Codes**

- `window_not_available` — The window object isn't available.
- `head_or_body_not_found` — The document's head or body element wasn't found to mount the Evervault script tag.
- `script_error` — The &lt;script&gt; tag encountered an error when loading the Evervault script.
- `timed_out` — The script failed to load before the specified [loadTimeout](/sdks/react#evervault-provider-loadtimeout) period.
- `evervault_not_available` — The Evervault object wasn't available after the script loaded.
- `amd_module_not_exported` — When using the AMD module loader, the Evervault module wasn't available after the script loaded.
- `amd_module_error` — The AMD module loader encountered an error when loading the Evervault module.

## Content Security Policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.

```text
script-src https://js.evervault.com;
connect-src https://keys.evervault.com https://api.evervault.com;
frame-src https://ui-components.evervault.com;
```


---

# React Native

_Encrypt data client-side, collect card details & perform 3D Secure authentication._

## Installation

Our React Native SDK is distributed via [npm](https://www.npmjs.com/), and can be installed using your preferred package manager.
The [react-native-webview](https://www.npmjs.com/package/react-native-webview) package is a peer dependency and will need to be installed as well.

> **Compatibility**
>
> Our React Native SDK requires [React Native 0.76](https://reactnative-archive-august-2025.netlify.app/docs/0.76/getting-started) or higher. We recommend upgrading if possible.
>
> If you are unable to upgrade, you will need to use our [legacy React Native SDK](/sdks/react-native-legacy).

### Linking

This package supports [autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md).

### Expo

This library has native code, so it does not work with [Expo Go](https://expo.dev/go). However, you can install it using a [custom development build](https://docs.expo.dev/develop/development-builds/create-a-build/).

### Proguard Rules

If you are using code shrinking with ProGuard for Android, you will need to specify exclusion rules for several Evervault dependencies. The required ProGuard rules can be found in our [Android SDK docs](/sdks/android#proguard-rules).

## Quickstart

### Add the EvervaultProvider

Wrap your app with the [{'<EvervaultProvider />'}](#evervault-provider) component and pass your Team and App ID as props.

Your Team and App ID can be found in the [Evervault Dashboard](https://app.evervault.com).

```tsx
import { EvervaultProvider } from "@evervault/react-native";

function App() {
  return (
    <EvervaultProvider teamId="team_id" appId="app_id">
      <YourApp />
    </EvervaultProvider>
  );
}
```

### Collect Card Data

You can use the [{'<Card />'}](#card) component to collect card data securely.

```tsx
import { Card, type CardPayload } from "@evervault/react-native";
import { Button, Form } from "@your/ui";

function CardForm({ onSubmit }: CardFormProps) {
  const [data, setData] = useState<CardPayload | null>(null);

  return (
    <Form>
      <Card onChange={setData}>
        <Card.Number />
        <Card.Expiry />
        <Card.Cvc />
        <Card.Holder />
      </Card>

      <Button disabled={!data?.isValid || !data?.isComplete} onPress={onSubmit}>
        Pay
      </Button>
    </Form>
  );
}
```

If you don't need to collect all four types of supported Card Data, you can omit the relevant components.

However, the components cannot be used individually outside of the `<Card />` component.

### Perform 3D Secure Authentication

You can use the [{'<ThreeDSecure />'}](#three-d-secure) component in combination with the Evervault API to perform 3DS authentications.

In order to use the 3DS component you must first [create a 3DS session on your backend](/api#createThreeDSSession) and pass it to your frontend. You can then use the [{'<ThreeDSecure.Frame />'}](#three-d-secure-frame) component to display the 3DS webview.

```tsx
import { ThreeDSecure, useThreeDSecure } from "@evervault/react-native";
import { createThreeDSecureSession } from "@your/api";
import { Button, Form, Modal } from "@your/ui";

function Checkout({ onSuccess, onFailure, onError }: CheckoutProps) {
  const tds = useThreeDSecure();

  async function handlePayment() {
    // Create a 3DS session on your backend
    const sessionId = await createThreeDSecureSession();

    tds.start(sessionId, {
      onSuccess,
      onFailure,
      onError,
    });
  }

  return (
    <Form>
      <Button onPress={handlePayment}>Pay</Button>

      <ThreeDSecure state={tds}>
        <Modal onRequestClose={() => tds.cancel()}>
          <ThreeDSecure.Frame />
        </Modal>
      </ThreeDSecure>
    </Form>
  );
}
```

## Components

### {'<EvervaultProvider />'}

Wraps your app in a new Evervault context, scoped to a specific team and app.

```tsx
import { EvervaultProvider } from "@evervault/react-native";

function App() {
  return (
    <EvervaultProvider teamId="team_123" appId="app_123">
      <YourApp />
    </EvervaultProvider>
  );
}
```

**Props**

- `teamId` _(required)_ — The Team ID found in the [Evervault Dashboard](https://app.evervault.com).
- `appId` _(required)_ — The App ID found in the [Evervault Dashboard](https://app.evervault.com).

### {'<Card />'}

The Card component is used to securely collect cardholder data from your users.

```tsx
import { Card, type CardPayload } from "@evervault/react-native";

function CardForm() {
  const [data, setData] = useState<CardPayload | null>(null);

  return (
    <Card onChange={setData}>
      <Card.Number />
    </Card>
  );
}
```

It is a wrapper component that manages the state of the child input components:

- [{'<Card.Holder />'}](#card-holder)
- [{'<Card.Number />'}](#card-number)
- [{'<Card.Expiry />'}](#card-expiry)
- [{'<Card.Cvc />'}](#card-cvc)

You do not have to render all of the available child input components as children. For example, if you only need to collect a card number and expiry, you can omit the Card.Cvc and Card.Holder components.

The `onComplete` field will be `true` once all **rendered** fields are filled out successfully with valid values.

**Props**

- `acceptedBrands` `CardBrandName[]` — An array of card brands that are accepted. If not provided, all brands are accepted. Possible values are 'american-express', 'visa', 'mastercard', 'discover', 'jcb', 'diners-club', 'unionpay', 'maestro', 'mir', 'elo', 'hipercard', 'hiper', 'szep', 'uatp', 'rupay'.
- `defaultValues` `CardForm` — Default values for the card fields.
  - `name` `string` — The card holder name.
  - `number` `string` — The unencrypted card number field.
  - `expiry` `string` — The expiry date for the card. Takes the format MMYY
  - `cvc` `string` — The unencrypted three (or four) digit CVC code for the card.
- `validationMode` `'onChange' | 'onBlur' | 'onTouched' | 'all'` — The validation mode for the card fields. Defaults to `all`.
- `onChange` `(payload: CardPayload) => void` — A callback function that is called whenever the card data changes. **Payload** - `card.name` `String` — The card holder name. - `card.number` `String` — The encrypted card number. This will only be present if the number is valid. - `card.brand` `String` — The brand that issued the card. - `card.lastFour` `String` — The last 4 digits of the card. This will only be present if the number is valid. - `card.bin` `String` — The bin for the card. This will only be present if the number id valid. - `card.expiry.month` `String` — The month for the card expiry field. - `card.expiry.year` `String` — The year for the card expiry field. - `card.cvc` `String` — The encrypted card CVC. - `card.errors` `Object` — Validation errors related to the card details. - `card.isValid` `Boolean` — Whether or not there are any errors shown in the component. - `card.isComplete` `Boolean` — Whether or not all of the fields have been filled out successfully with valid values.
- `onError` `(error: Error) => void` — A callback function that is called when a native error occurs.

#### Ref

The `Card` component exposes an imperative handle using `ref`.

```tsx
import { useRef } from "react";
import { Card } from "@evervault/react-native";

function CardForm() {
  const cardRef = useRef<Card>(null);

  return (
    <Card ref={cardRef}>
      <Card.Number />
    </Card>
  );
}
```

**Methods**

- `reset()` `() => void` — Resets the form to its default values and state.

### {'<Card.Holder />'}

Used as a child of [{'<Card />'}](#card) to collect the name of a card holder.

```tsx
import { Card } from "@evervault/react-native";

function CardForm() {
  return (
    <Card>
      <Card.Holder placeholder="Johnny Appleseed" />
    </Card>
  );
}
```

**Props**

- `placeholder` `string` — The placeholder text to display in the input field.

### {'<Card.Number />'}

Used as a child of [{'<Card />'}](#card) to collect the card number.

```tsx
import { Card } from "@evervault/react-native";

function CardForm() {
  return (
    <Card>
      <Card.Number placeholder="1234 1234 1234 1234" />
    </Card>
  );
}
```

**Props**

- `placeholder` `string` — The placeholder text to display in the input field.
- `obfuscateValue` `boolean | string` — If `true`, all but the first 6 characters of the card number will be obfuscated. If a string is provided, it will be used as the obfuscation character (defaults to `•`).

### {'<Card.Expiry />'}

Used as a child of [{'<Card />'}](#card) to collect the expiry date of a card.

```tsx
import { Card } from "@evervault/react-native";

function CardForm() {
  return (
    <Card>
      <Card.Number />
      <Card.Expiry placeholder="MM / YY" />
    </Card>
  );
}
```

**Props**

- `placeholder` `string` — The placeholder text to display in the input field.

### {'<Card.Cvc />'}

Used as a child of [{'<Card />'}](#card) to collect the CVC code of a card.

```tsx
import { Card } from "@evervault/react-native";

function CardForm() {
  return (
    <Card>
      <Card.Number />
      <Card.Cvc placeholder="CVC" />
    </Card>
  );
}
```

**Props**

- `placeholder` `string` — The placeholder text to display in the input field.
- `obfuscateValue` `boolean | string` — If `true`, all of the CVC will be obfuscated. If a string is provided, it will be used as the obfuscation character (defaults to `•`).

### {'<ThreeDSecure />'}

The ThreeDSecure component is used to provide access to the 3DS authentication process.

This component allows you to use the [{'<ThreeDSecure.Frame />'}](#three-d-secure-frame) component to display the 3DS webview. Any custom components you want to display alongside the 3DS webview should be wrapped in the ThreeDSecure component.

It should be used in combination with the [useThreeDSecure](#use-three-d-secure) hook.

**Props**

- `state` `ThreeDSecureState` _(required)_ — The 3DS state object returned by the [useThreeDSecure](#use-three-d-secure) hook.

### {'<ThreeDSecure.Frame />'}

The ThreeDSecure.Frame component is used to display the 3DS webview, which will handle the authentication process.

If the user closes the frame before completion, you will need to use the `cancel()` method (from the [useThreeDSecure](#usethreedsecure) hook) to properly close the webview and clean up the session.

```tsx
import { ThreeDSecure, useThreeDSecure } from "@evervault/react-native";
import { createThreeDSSession } from "@your/api";
import { Button, Form, Modal } from "@your/ui";

function CustomCheckout() {
  const tds = useThreeDSecure();

  async function handlePayment() {
    // Create a 3DS session on your backend
    const sessionId = await create3DSecureSession();

    tds.start(sessionId, {
      onSuccess: () => {
        console.log("3DS successful");
      },
      onFailure: (error: Error) => {
        console.error("3DS failed", error);
      },
      onError: (error: Error) => {
        console.warn("3DS errored", error);
      },
    });
  }

  return (
    <Form>
      <Button onPress={handlePayment}>Pay</Button>

      <ThreeDSecure state={tds}>
        <Modal onRequestClose={tds.cancel}>
          <ThreeDSecure.Frame />
        </Modal>
      </ThreeDSecure>
    </Form>
  );
}
```

**Props**

- `style` `StyleProp<ViewStyle>` — Style applied to the WebView container.

**Parameters**

- `session` `string` _(required)_ — The 3D Secure session ID.
- `options` `ThreeDSSessionOptions` — The options for the 3DS authentication process.
  - `failOnChallenge` `boolean | () => Promise<boolean>` — If set to true (or a function that returns true), the authentication will fail if a challenge is required.
  - `onRequestChallenge` `(event: ThreeDSecureEvent) => void` — The `requestChallenge` event will be fired if the 3DS authentication process requires a challenge. If you'd like to fail the authentication, you should call `preventDefault` on the passed event.
  - `onSuccess` `() => void` — The 'success' event will be fired once the 3DS authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session endpoint](/api#retrieveThreeDSSession) to retrieve the cryptogram for the session and complete the payment.
  - `onFailure` `(error: Error) => void` — The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again. If the user cancels the 3DS authentication process this event will be fired.
  - `onError` `(error: Error) => void` — The error event will be fired if the component fails to load.

## Hooks

### useEvervault

The `useEvervault` hook is used to access the current Evervault scope in context.

Any component that uses this hook must be wrapped in the [{'<EvervaultProvider />'}](#evervault-provider) component.

```tsx
import { useEvervault } from "@evervault/react-native";
import { Button, Text, TextInput, View } from "react-native";

function YourApp() {
  const { teamId, appId, encrypt } = useEvervault();

  const [data, setData] = useState("");
  const [encryptedData, setEncryptedData] = useState("");

  async function handleEncrypt() {
    const encrypted = await encrypt(data);
    setEncryptedData(encrypted);
  }

  return (
    <View>
      <Text>
        Encrypting data for team {teamId} and app {appId}
      </Text>

      <TextInput value={data} onChangeText={setData} />
      <Button title="Encrypt" onPress={handleEncrypt} />

      <Text>Encrypted Data: {encryptedData}</Text>
    </View>
  );
}
```

#### Returns

##### encrypt

Encrypts the provided data using native encryption modules and the Evervault API.

**Parameters**

- `data` `string | number | boolean | object | array` _(required)_ — The data to encrypt.

### useThreeDSecure

The `useThreeDSecure` hook is used to manage the 3DS authentication process.

The hook returns an object with `start()` and `cancel()` methods. The returned object should be used with the [{'<ThreeDSecure />'}](#three-d-secure) component.

**Options**

- `failOnChallenge` `boolean | () => Promise<boolean>` — If set to true (or a function that returns true), the authentication will fail if any sessions require a challenge. Can be overridden on a per-session basis by the failOnChallenge option passed to the `start()` method.

#### Returns

##### start

The start function is used to kick off the 3DS authentication process.

**Parameters**

- `sessionId` `string` _(required)_ — The 3DS session ID. A 3DS session can be created using the [Evervault API](/api#createThreeDSSession).
- `options` `ThreeDSSessionOptions` — The options for the 3DS authentication process.
  - `failOnChallenge` `boolean | () => Promise<boolean>` — If set to true (or a function that returns true), the authentication will fail if a challenge is required.
  - `onRequestChallenge` `(event: ThreeDSecureEvent) => void` — The `requestChallenge` event will be fired if the 3DS authentication process requires a challenge. If you'd like to fail the authentication, you should call `preventDefault` on the passed event.
  - `onSuccess` `() => void` — The 'success' event will be fired once the 3DS authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session endpoint](/api#retrieveThreeDSSession) to retrieve the cryptogram for the session and complete the payment.
  - `onFailure` `(error: Error) => void` — The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again. If the user cancels the 3DS authentication process this event will be fired.
  - `onError` `(error: Error) => void` — The error event will be fired if the component fails to load.

##### cancel

The `cancel()` function is used to cancel the ongoing 3DS authentication process. This can be particularly useful for canceling a session when a custom cancel button is triggered.

##### session

The current `ThreeDSecureSession` object, or `null` if no session was created.

##### isVisible

A boolean indicating whether the 3DS webview should currently be rendered. Use this to conditionally display the `ThreeDSecure` component and its children.

## V2 Migration Guide

If your app currently uses the older `@evervault/evervault-react-native` package, you can follow [our migration guide](/sdks/react-native/v2-migration) to upgrade to the new package.


---

# React Native SDK (Legacy)

_Encrypt data and embed UI Components with React Native_

> **Deprecated**
>
> This is the legacy version of our React Native SDK. It is no longer actively
>   maintained. If you are on React Native 0.76 or higher you can migrate to our
>   new [React Native SDK](/sdks/react-native#migration-guide).

You can use our React Native SDK to:

- Encrypt data client-side
- Collect Card Data securely
- Perform 3D Secure authentication

## Quickstart

### Install SDK

Our React Native SDK is distributed via `npm`, and can be installed using your preferred package manager.

```bash
## Using npm
npm install @evervault/evervault-react-native

## Using yarn
yarn add @evervault/evervault-react-native
```

### Add the EvervaultProvider

Wrap your app with the `EvervaultProvider` component and pass your Team and App ID as props.

Your Team and App ID can be found in the [Evervault Dashboard](https://app.evervault.com).

```tsx
import { EvervaultProvider } from "@evervault/evervault-react-native";

function App() {
  return (
    <EvervaultProvider teamId="team_id" appId="app_id">
      <YourApp />
    </EvervaultProvider>
  );
}
```

### Collect card data

You can use the `<Card />` component to collect card data securely.

```tsx
import { Card, type CardPayload } from "@evervault/evervault-react-native";

function CardData() {
  const [cardData, setCardData] = useState<CardPayload | undefined>(undefined);

  const handleCardChange = (card: CardPayload) => {
    if (card.isComplete) {
      // note that the user can enter further data even when the Card is in a complete state.
      // For example entering the remainder of their name after the first few characters.
      console.log("Card is complete!");
    }

    setCardData(card);
  };

  return (
    <Card onChange={handleCardChange}>
      <Card.Number />
      <Card.Expiry />
      <Card.CVC />
      <Card.Holder />
    </Card>
  );
}
```

If you don't need to collect all four types of supported Card Data, you can omit the relevant components.

However, the components cannot be used individually outside of the `<Card />` component.

### Perform 3D Secure Authentication

You can use the [`<ThreeDSecure />`](#three-d-secure) component in combination with the Evervault API to perform 3DS authentications. In order to use the 3DS component you must first [create a 3DS session on your backend](/api#createThreeDSSession) and pass it to your frontend. You can then use the [`<ThreeDSecure.Frame>`](#three-d-secure-frame) component to display the 3DS webview.

```tsx
import {
  ThreeDSecure,
  useThreeDSecure,
} from "@evervault/evervault-react-native";
import { createThreeDSSession, finalizePayment } from "./api";
import { Modal, TouchableOpacity, Text, View } from "react-native";

function Checkout() {
  const tds = useThreeDSecure();

  const handlePayment = async () => {
    // Create a 3DS session on your backend
    const sessionId = await create3DSecureSession();

    tds.start(sessionId, {
      onSuccess: () => {
        console.log("3DS successful");
      },
      onFailure: (error: Error) => {
        console.error("3DS failed", error);
      },
      onError: (error: Error) => {
        console.log("3DS errored", error);
      },
    });
  };

  const close3DS = async () => {
    await tds.cancel();
  };

  return (
    <ThreeDSecure state={tds}>
      <Modal animationType="slide" transparent={true}>
        <View style={[styles.modalContainer]}>
          <View style={[styles.modalContent]}>
            <View style={[styles.titleBar]}>
              <TouchableOpacity style={[styles.closeButton]} onPress={close3DS}>
                <Text style={[styles.closeButtonText]}>"X"</Text>
              </TouchableOpacity>
              <Text style={[styles.titleText]}>"Verification"</Text>
            </View>
            <ThreeDSecure.Frame />
          </View>
        </View>
      </Modal>
    </ThreeDSecure>
  );
}
```

### Proguard Rules

If you are using code shrinking with ProGuard for Android, you will need to specify exclusion rules for several Evervault dependencies. The required ProGuard rules can be found in [our Android SDK docs](/sdks/android#proguard-rules).

## Reference

### {'<EvervaultProvider />'}

```tsx
import { EvervaultProvider } from "@evervault/evervault-react-native";

function App() {
  return (
    <EvervaultProvider teamId="team_123" appId="app_123">
      <YourApp />
    </EvervaultProvider>
  );
}
```

**Props**

- `teamId` `string` _(required)_ — The Team ID found in the [Evervault Dashboard](https://app.evervault.com).
- `appId` `string` _(required)_ — The App ID found in the [Evervault Dashboard](https://app.evervault.com).

### CardPayload

```tsx
import { type CardPayload } from "@evervault/evervault-react-native";
```

The Payload returned by the onChange callback of the `<Card />` component.

**Properties**

- `card.name` `string` — The card holder name.
- `card.number` `string` — The encrypted card number. This will only be present if the number is valid.
- `card.brand` `string` — The global payment card brand associated with the card.
- `card.localBrands` `Array<String>` — The local payment card brands that are accepted by the card
- `card.lastFour` `string` — The last 4 digits of the card. This will only be present if the number is valid.
- `card.bin` `string` — The bin for the card. This will only be present if the number id valid.
- `card.expiry.month` `string` — The month for the card expiry field.
- `card.expiry.year` `string` — The year for the card expiry field.
- `card.cvc` `string` — The encrypted card CVC.
- `card.errors` `Object` — Validation errors related to the card details.
- `card.isValid` `boolean` — Whether or not there are any errors shown in the component.
- `card.isComplete` `boolean` — Whether or not all of the fields have been filled out successfully with valid values.

### {"<Card />"}

```tsx
import {
  init,
  Card,
  type CardPayload,
} from "@evervault/evervault-react-native";

function App() {
  const submitCardData = (payload: CardPayload) => {
    console.log("Card Data", payload);
  };

  useEffect(() => {
    init("team_id", "app_id");
  }, []);

  return (
    <Card>
      <Text>Card Number</Text>
      <Card.Number />
    </Card>
  );
}
```

The Card component is used to collect card data securely. It is a wrapper component that manages the state of the child components.

Make sure you have initialized the Evervault SDK before using the Card component.

You may render some or all of the available Card Sub-Components.

The `isComplete` field of the payload will be `true` when all of the **currently rendered** fields are filled out successfully with valid values. For example, if you were to omit the `<Card.CVC />` component and render the `<Card.Number />`, `<Card.Expiry />` and `<Card.Holder />` components. The `isComplete` field will be true, when the three rendered components have valid values.

**Props**

- `config` `CardConfig` — The config for the card component.
  - `acceptedBrands` `Array<CardBrandName>` — An array of card brands that are accepted. If not provided, all brands are accepted. Possible values are 'american-express', 'visa', 'mastercard', 'discover', 'jcb', 'diners-club', 'unionpay', 'maestro', 'mir', 'elo', 'hipercard', 'hiper', 'szep', 'uatp', 'rupay'.
- `initialValue` `CardForm` — Initial Values for the card fields.
  - `number` `String` — The unencrypted card number field.
  - `expiry` `String` — The expiry date for the card. Takes the format MMYY
  - `cvc` `String` — The unencrypyted three digit CVC code for the card.
  - `holder` `String` — The card holder name.
- `onChange` `(payload: CardPayload) => void` — A callback function that is called whenever the card data changes.
- `style` `StyleProp<TextStyle>` — The style to apply to the container component.

### Card Input Components

The `Card` component has support for collecting Card Number, Expiry, CVC and Card Holder information. These components accept almost all the same properties as the standard React Native TextInput component.

```ts
import { type TextInputProps } from "react-native";

// Props accepted by the Card Input Components
Omit<
  TextInputProps,
  "onChange" | "onChangeText" | "inputMode" | "autoComplete" | "value"
>;
```

### {'<Card.Number />'}

Used as a child of [{'<Card />'}](#card) to collect a card number.

```tsx
import { Card } from "@evervault/evervault-react-native";

function App() {
  return (
    <Card>
      <Card.Number
        autofocus
        placeholder="4242 4242 4242 4242"
        style={{ borderWidth: 1 }}
      />
    </Card>
  );
}
```

### {'<Card.Expiry />'}

Used as a child of [{'<Card />'}](#card) to collect a card expiry.

```tsx
import { Card } from "@evervault/evervault-react-native";

function App() {
  return (
    <Card>
      <Card.Number />
      <Card.Expiry placeholder="MM / YY" />
    </Card>
  );
}
```

### {'<Card.CVC />'}

Used as a child of [{'<Card />'}](#card) to collect a card CVC.

```tsx
import { Card } from "@evervault/evervault-react-native";

function App() {
  return (
    <Card>
      <Card.Number />
      <Card.CVC placeholder="123" />
    </Card>
  );
}
```

### {'<Card.Holder />'}

Used as a child of [{'<Card />'}](#card) to collect the name of a card holder.

```tsx
import { Card } from "@evervault/evervault-react-native";

function App() {
  return (
    <Card>
      <Card.Number />
      <Card.Holder placeholder="John Doe" />
    </Card>
  );
}
```

### {'useThreeDSecure()'}

The `useThreeDSecure` hook is used to manage the 3DS authentication process. It returns an object with `start()` and `cancel()` methods. The returned object should be used with the [`<ThreeDSecure />`](#three-d-secure) component.

#### Returns

##### {"start()"}

The start function is used to kick off the 3DS authentication process.

**Parameters**

- `sessionId` `String` _(required)_ — The 3DS session ID. A 3DS session can be created using the [Evervault API](/api#createThreeDSSession).
- `callbacks` `ThreeDSSessionCallbacks` _(required)_ — The callbacks to be called when the 3DS authentication process is finished.
  - `onSuccess` `Function` — The 'success' event will be fired once the 3DS authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the [Retrieve 3DS Session](/api#retrieveThreeDSSession) endpoint to retrieve the cryptogram for the session and complete the payment.
  - `onFailure` `Function` — The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again. If the user cancels the 3DS authentication process this event will be fired.
  - `onError` `Function` — The error event will be fired if the component fails to load.

##### {"cancel()"}

The `cancel()` function is used to cancel the ongoing 3DS authentication process. This can be particularly useful for canceling a session when a custom cancel button is triggered.

### {"<ThreeDSecure />"}

This is a provider module which provides access to the 3DS authentication process. It should be used in combination with the [`useThreeDSecure`](#usethreedsecure) hook. The `<ThreeDSecure />` provider component allows you to use the [`<ThreeDSecure.Frame>`](#three-d-secure-frame) component to display the 3DS webview. Any custom components you want to display alongside the 3DS webview should be wrapped in the `<ThreeDSecure />` component.

**Props**

- `state` `ThreeDSecureState` — The 3DS session state returned from the [`useThreeDSecure`](#useThreeDSecure) hook.

### {"<ThreeDSecure.Frame />"}

The `<ThreeDSecure.Frame />` component is used to display the 3DS webview inside your own custom components. It is available within the [`<ThreeDSecure />`](#three-d-secure) provider component. It should be used in combination with the [`useThreeDSecure`](#usethreedsecure) hook. The component returns a webview which will handle the authentication process. You will need to use the `cancel()` method, returned from the [`useThreeDSecure`](#usethreedsecure) hook, to handle the user closing the 3DS webview before completion.

```tsx
import { ThreeDSecure, useThreeDSecure} from '@evervault/evervault-react-native';
import { createThreeDSSession, finalizePayment } from "./api"
import { CustomIcon } from "./CustomIcon"

function CustomCheckout() {
  const tds = useThreeDSecure();

  const handlePayment = async () => {
    // Create a 3DS session on your backend
    const sessionId = await create3DSecureSession();

    tds.start(sessionId, {
      onSuccess: () => {
        console.log("3DS successful");
        setPaymentStatus("success");
      },
      onFailure: (error: Error) => {
        console.error("3DS failed", error);
        setPaymentStatus("failed");
      },
      onError: (error: Error) => {
        console.log("3DS errored", error);
        setPaymentStatus("failed");
      },
    });
  }

  const cancelSession = async () => {
    await tds.cancel();
  };

  return (
    <ThreeDSecure state={tds}>
      <View>
        <CustomIcon onPress={cancelSession}> // Use ThreeDSecure.Frame to display the 3DS webview with your own components
        <ThreeDSecure.Frame />
      </View>
    </ThreeDSecure>
  );
}
```

### {'encrypt()'}

```tsx
import { encrypt } from "@evervault/evervault-react-native";

async function encryptData(data: string) {
  try {
    const encrypted = await encrypt(data);
    console.log("Encrypted Data", encrypted);
  } catch (err) {
    console.log("There was an error encrypting the data");
  }
}
```

**Parameters**

- `data` `any` _(required)_ — The data to encrypt.

On iOS you can pass data types like Booleans, Objects and Arrays to the encrypt function. The full list of supported data types can be found in our [iOS SDK Documentation](/sdks/ios#encrypting-data).

Currently on Android only encrypting Strings is supported.

### {'init()'}

> **Deprecated**
>
> The init method has been deprecated and will be removed from the Evervault SDK in a future release.
>
> Use the [EvervaultProvider](#evervault-provider) component to initialize the Evervault SDK instead.

```tsx
import { init } from "@evervault/evervault-react-native";

function App() {
  useEffect(() => {
    init("team_id", "app_id");
  }, []);
}
```

The init function initializes the Evervault SDK with your Team and App ID. You only need to do this once in your application, but must run the command before using any other Evervault functions or components.

**Parameters**

- `teamId` `String` _(required)_ — The Team ID found in the [Evervault Dashboard](https://app.evervault.com).
- `appId` `String` _(required)_ — The App ID found in the [Evervault Dashboard](https://app.evervault.com).


---

# Ruby

_Use the Evervault Ruby SDK to encrypt/decrypt data, run Functions, create client tokens, and enable Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

Our Ruby SDK is distributed via RubyGems, and can be installed via the command line or a Gemfile.

### Initialize the SDK

The SDK needs to be initialized with an App's ID and API key. If you don't have one yet, you can get one by creating an App in the [Evervault Dashboard](https://app.evervault.com).

### Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

```ruby
encrypted = Evervault.encrypt("Hello, world!")
```

## Reference

### encrypt

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). Evervault Strings can be used across all of our products. To encrypt data using the Ruby SDK, simply pass a String, Hash or Array into the encrypt() method. The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted = Evervault.encrypt("Hello, world!")
```

**Parameters**

- `data` `String | Boolean | Number | Array | Hash` _(required)_ — The data to encrypt.

### decrypt

Decrypts the data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted_data = Evervault.encrypt("Hello, world!")
decrypted = Evervault.decrypt(encrypted_data)
```

**Parameters**

- `data` `String | Boolean | Number | Array | Hash` _(required)_ — The data to decrypt.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### create_client_side_decrypt_token

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads. By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted_data = Evervault.encrypt("Hello, world!")
five_minutes = Time.now + 300

token = Evervault.create_client_side_decrypt_token(encrypted_data, five_minutes)
```

**Parameters**

- `payload` `String | Boolean | Number | Array | Hash` _(required)_ — The data to decrypt.
- `expiry` `Time` — The time the token will expire. Defaults to 5 minutes in the future.
### run

Lets you invoke an [Evervault Function](/functions) with a given payload.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

result = Evervault.run("hello-function", {
  "name": "Claude Shannon",
  "ssn": "ev:encrypted_string"
})
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `payload` `Hash` _(required)_ — The payload to pass to the function.

Successful Function runs will return a hash containing a Function Run ID and the result from your Function in the following format:

```json
{
  "id": "func_run_09413338da56",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name",
    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
  }
}
```

### create_run_token

Creates a single use, time bound token (5 minutes) for invoking an [Evervault Function](/functions) with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

run_token = Evervault.create_run_token("hello-function", {
  "name": "Claude Shannon",
  "ssn": "ev:encrypted_string"
})
```

**Parameters**

- `functionName` `String` _(required)_ — Name of the Function the Run Token is for.
- `payload` `Hash` — Payload that the token can be used with. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

When you create a Run Token, the SDK will return a JSON object containing your token.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
}
```

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```

### enable_outbound_relay

> This should only be used when you need to configure third party SDKs with
>   Relay. All other use cases should call Relay with a HTTP Client.

Configures your application to proxy HTTP requests using [Relay](/relay) based on the configuration created in the Evervault dashboard.

```ruby
Evervault.enable_outbound_relay()
```

**Parameters**

- `decryption_domains` `String[]` — Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created using the Evervault dashboard.


---

# V2 Migration Guide

_Steps to migrate from the legacy Evervault React Native package to @evervault/react-native v2._

## Install react-native-webview

The `react-native-webview` package is now a peer dependency and will need to be installed as well.

```bash
## Using npm
npm install react-native-webview

## Using yarn
yarn add react-native-webview

## Using Expo
npx expo install react-native-webview
```

## Update your imports

The package name has been updated to `@evervault/react-native`.

```diff
- import { EvervaultProvider } from '@evervault/evervault-react-native';
+ import { EvervaultProvider } from '@evervault/react-native';
```

## Remove top-level function calls

In the previous version, you could call `init()` and `encrypt()` directly from the package.

These functions are no longer exposed at the top level. Instead:

- Initializing the SDK is now done via the [{'<EvervaultProvider />'}](/sdks/react-native#evervault-provider) component.
- Encrypting data is now done via the `encrypt()` method returned from the [`useEvervault`](/sdks/react-native#use-evervault) hook.

```diff
- import { init } from '@evervault/evervault-react-native';
+ import { EvervaultProvider } from '@evervault/react-native';

  function App() {
-   useEffect(() => {
-     init('team_id', 'app_id');
-   }, []);

    return (
+     <EvervaultProvider teamId="team_id" appId="app_id">
        <YourApp />
+     </EvervaultProvider>
    );
  }
```

```diff
- import { encrypt } from '@evervault/evervault-react-native';
+ import { useEvervault } from '@evervault/react-native';

  function App() {
+   const { encrypt } = useEvervault();

    async function handleEncrypt() {
      const encrypted = await encrypt('data');
    }
  }
```

### Update Card props

In the previous version, you could pass styles to the [{'<Card />'}](/sdks/react-native#card) component via the `style` prop.

The Card component no longer renders a View, so you should move the styles to a parent or child View.

```diff
- <Card style={{ padding: 16 }} />
+ <View style={{ padding: 16 }}>
+   <Card />
+ </View>
```

The previous version also accepted `acceptedBrands` via the `config` prop. This has been moved top-level:

```diff
- <Card config={{ acceptedBrands: ['visa', 'mastercard'] }} />
+ <Card acceptedBrands={['visa', 'mastercard']} />
```

Finally, the `initialValue` prop has been renamed to `defaultValues`:

```diff
- <Card initialValue={{ name: 'John Doe' }} />
+ <Card defaultValues={{ name: 'John Doe' }} />
```

### Rename Card.CVC to Card.Cvc

The `Card.CVC` prop has been renamed to `Card.Cvc`.

```diff
- <Card.CVC placeholder="CVC" />
+ <Card.Cvc placeholder="CVC" />
```