# Evervault

Integrate 3D Secure authentication with Finix using [Evervault](https://evervault.com).

img
## Finix for Evervault Overview

Connecting Evervault to Finix allows merchants to perform 3D Secure authentication on card transactions before processing payments through Finix.

Implementing 3D Secure for online payments provides several benefits:

- **Reduced Fraud:** Requiring an additional authentication step could decreases the risk of unauthorized transactions by verifying the cardholder's identity.
- **Liability Shift:** When a transaction is authenticated with 3D Secure and later turns out to be fraudulent, the chargeback liability can shift from the merchant to the card issuer.
- **Regulatory Compliance:** 3D Secure helps merchants comply with regulations such as PSD2/SCA in different geographic areas.


### Finix Requirements

- Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment.
- Finix Live Account to run card or ACH transactions.


### Evervault Requirements

- Evervault account with 3DS Server access. See Evervault's [Getting Started](https://docs.evervault.com/cards/3d-secure) documentation for a full guide on the 3D Secure authentication process.


## Integration

### Step 1: Sign up for a Finix Account

To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account.

### Step 2: Create Finix API Keys

API Environments
API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments).

To create an API Key:

1. Navigate to **Developers → API Keys** in the Finix dashboard.
2. Click **Create API Key** and enter a **Display Name**.
3. Save the credentials somewhere secure.


Store API Keys Securely
Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis.

To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation.

### Step 3: Collect and Tokenize Card Data with Evervault

Finix does not pass raw PANs to Evervault directly. To use 3DSecure you must use Evervault's Card Collection iframe to collect and encrypt card data.

#### Register an Acquirer with Evervault

Register your acquirer configuration with Evervault. This is a **one-time setup** — save the returned acquirer `id`for later.


```shell Register Acquirer with Evervault
curl https://api.evervault.com/payments/acquirers \
  --request POST \
  --user 'app_id:api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Ollivanders Wand Shop Production Configuration",
    "description": "Ollivanders Wand Shop Production Configuration",
    "default": true,
    "configurations": [
      {
        "network": "mastercard",
        "bin": "424242",
        "acquirerMerchantIdentifier": "38191048173",
        "country": "ie"
      },
      {
        "network": "visa",
        "bin": "424242",
        "acquirerMerchantIdentifier": "38191048173",
        "country": "ie"
      }
    ]
  }'
```

Production BIN Numbers
For production, contact Evervault to get the correct BIN numbers to include in your acquirer configuration.

The response includes an `id` for your acquirer configuration:


```json Sample Acquirer Registration Response
{
  "id": "acquirer_adk3kdljc3",
  ...
}
```

One-Time Registration
You only need to register your acquirer once. After that, reference the same acquirer `id`.

#### Evervault Card Collection

For a full integration guide, see Evervault's [Card Collection documentation](https://docs.evervault.com/cards/card-collection#getting-started).

Once you collect the card data using Evervault, you will need to configure Evervault's Relay to create a corresponding `Payment Instrument` on Finix's API.

#### Evervault Relay

Relay is Evervault's network proxy that decrypts encrypted card data in transit before forwarding requests to Finix.

For a full integration guide, see Evervault's [Relay Documenation](https://docs.evervault.com/cards/card-collection#processing-encrypted-card-data).

**1. Configure a Relay**

In the Evervault Dashboard, click on **Add Route** and configure a new route.

- **Path:** Set to `/**` to match all requests, or specify paths like `/payment_instruments`.
- **Decryption:** Add a request action to decrypt JSON fields.


img
**2. Send Requests via the Relay**

Send your `createPaymentInstrument` request to the Relay URL instead of the Finix API directly. The Relay decrypts the encrypted PAN in transit so Finix receives the raw card data.

After creating the Payment Instrument on Finix, map the Finix Payment Instrument ID against the Evervault token. Use the Finix Payment Instrument ID for all subsequent Finix API calls.

#### Conduct a 3DSecure Authentication

Completing 3DS authentication requires three steps: creating a session, authenticating the session on the client, and forwarding the resulting credentials to Finix. For a full guide, see Evervault's [3D Secure documentation](https://docs.evervault.com/cards/3d-secure#getting-started-with-3d-secure).

**1. Create a 3DS Session**

From your backend, call the Evervault create session endpoint with the card, merchant, and payment details. Use the acquirer `id` you saved from the registration step above.


```shell Create a 3DS Session
curl https://api.evervault.com/payments/3ds-sessions \
  --request POST \
  --user 'app_id:api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant": {
      "name": "<MERCHANT_NAME>",
      "website": "<MERCHANT_WEBSITE>",
      "categoryCode": "<MERCHANT_CATEGORY_CODE>",
      "country": "<MERCHANT_COUNTRY>"
    },
    "acquirer": "<ACQUIRER_ID>",
    "card": {
      "number": "<CARD_NUMBER>",
      "expiry": {
        "month": "<EXPIRY_MONTH>",
        "year": "<EXPIRY_YEAR>"
      }
    },
    "payment": {
      "type": "one-off",
      "amount": <AMOUNT>,
      "currency": "<CURRENCY_CODE>"
    },
    "challenge": {
      "preference": "challenge-requested"
    }
  }'
```

The response returns a session `id` — pass this to your client-side code.

**2. Authenticate the Session on the Client**

Use Evervault's JavaScript SDK to render the authentication challenge. Initialize the SDK with your Team ID and App ID, then call `evervault.ui.threeDSecure` with the session ID and mount the modal. Handle success and failure events in the callbacks.

As an alternative to the SDK, you can redirect the browser to Evervault's 3DS endpoint with the session ID and a callback URL — Evervault will redirect back with the authentication status appended.

**3. Retrieve and Forward Credentials**

After successful authentication, retrieve the ECI and cryptogram from the Evervault session. Pass these values to Finix in the authorization or transfer request (see Step 4 below).

### Step 4: Create a 3DSecure Sale or Authorization

Once the 3DS session is resolved, map the Evervault 3DS response values to the Finix authorization request:


```json
{
  "3d_secure_authentication": {
    "cardholder_authentication": "<EVERVAULT_CRYPTOGRAM>",
    "electronic_commerce_indicator": "<ECI_ENUM>",
    "transaction_id": "<ACS_TRANSACTION_ID>"
  }
}
```

Map the following values from the Evervault 3DS session response:

| Evervault Field | Finix Field |
|  --- | --- |
| `cryptogram` | `cardholder_authentication` |
| ECI (see mapping table below) | `electronic_commerce_indicator` |
| `accessControlServer.transactionIdentifier` | `transaction_id` |


#### ECI Mapping

Finix requires a specific enum for the `electronic_commerce_indicator` field. Map the raw ECI values from the 3DS session as follows:

| Raw ECI Value | Finix Enum |
|  --- | --- |
| `02` (Mastercard), `05` (all others) | `AUTHENTICATED` |
| `01` (Mastercard), `06` (all others) | `ATTEMPTED` |
| Any other value | `NON_AUTHENTICATED` |


ATTEMPTED Status
An `ATTEMPTED` status still provides a liability shift. It means the card network performed authentication on behalf of the issuing bank because the bank doesn't support 3DS or the card isn't enrolled. A cryptogram is only provided when 3DS authentication is successful.

If you are using Evervault's UI Components, send the authorization request to the Relay proxy URL (e.g., `https://finix-live-payments-api-com.relay.evervault.app/authorizations`) instead of the Finix API directly.

#### Sale Example

Example
API Definition
#### Authorization Example

Example
API Definition