# Evervault Plugin

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.

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

To perform 3DS authentication, you need your Finix Merchant ID and the acquirer BINs for each card network. Please reach out to Evervault for acquirer BINs. They will provide the acquirer BINs for each network.

You can find your Merchant ID in the Finix Dashboard under **Developer → Finix Integration → Merchant ID**.

img
Pass your Merchant ID and the appropriate acquirer BIN into the `acquirer` field of Evervault's Create 3DS Session endpoint. Read more about creating a 3DS session [here](https://docs.evervault.com/api#createThreeDSSession).


```shell Sample 3DS Session Request on Everfvault
curl https://api.evervault.com/payments/3ds-sessions \
  --request POST \
  --user 'app_id:api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchantID": "MUaLqUUsZwMbGGYiQnubhNAb",
    "merchantName": "<MERCHANT_NAME>",
    "acquirerBIN": {{acquirerBIN}},
    "acquirerName": "Pathward, National Association",
    "acquirerCountry": "UNITED STATES",
    "acquirerRegion": "UNITED STATES",
    "identityCheckExpress": "Y"
  }'
```

### Step 5: 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