> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3-D Secure Setup

> Configure 3-D Secure for your merchant account, turn it on for your connections, and learn how Gr4vy picks a scheme profile for each transaction.

Setting up 3-D Secure (3DS) takes two steps:

1. Add a 3DS configuration for each card scheme to your merchant account.
2. For Embed, Hosted 3DS, and API transactions, turn on 3DS for each card connection that should use it.

This setup is only required when using Gr4vy's 3DS solutions, such as Gr4vy Embed, Hosted 3DS, or native 3DS. No configuration is needed if [passing through 3DS data](./external) from an external source.

## Add a merchant account configuration

A 3DS configuration holds the acquirer details that Gr4vy sends to the card scheme when it authenticates a transaction. Configurations belong to the merchant account and are shared across all its connections. You can add more than one configuration per card scheme, and Gr4vy picks one for each transaction based on its currency and metadata. See [scheme profile resolution](#scheme-profile-resolution) for how Gr4vy picks a configuration.

To add a configuration, follow these steps:

1. Go to **Settings** in the Gr4vy Admin Panel.
2. Click **Edit merchant** and select the **3-D Secure** tab.
3. Add a [scheme profile](./schemes) for each card scheme to enable 3DS for.

You can also manage these configurations with the [3DS configuration API](/reference/merchant-accounts/three-ds-configurations/new-three-ds-configuration).

If you use more than one connection, see [3DS with multiple connections](./multiple-connections) before adding your configurations.

## Turn on 3DS for a connection

For transactions created through Embed, Hosted 3DS, or the API, 3DS only runs on connections that have it turned on.

1. Go to the **Connections** tab.
2. Select an active card connection and go to the **3-D Secure** tab.
3. Switch the **Enable 3DS** toggle on.

The **3-D Secure** tab is only shown for connections that accept 3DS data from Gr4vy.

[Native 3DS](./native) and [Click to Pay](/guides/features/click-to-pay/tas) authenticate before a connection is chosen, so they use the merchant account configuration directly.

## Connection-level scheme profiles

Some accounts also have scheme profiles configured on individual connections. This was the original way to set up 3DS, and it's no longer available by default. New accounts use merchant account configurations only.

If a connection has a scheme profile for the card's scheme, Gr4vy uses it instead of the merchant account configuration. Connection-level profiles don't support Click to Pay or native 3DS. To move your 3DS setup to the merchant account, contact the support team.

## Scheme profile resolution

When a transaction requires 3DS, Gr4vy determines which configuration to use based on the following order:

1. **Connection-level profile**: If the connection has a [connection-level scheme profile](#connection-level-scheme-profiles) for the card's scheme, that profile is used.
2. **Merchant account configuration**: Otherwise, Gr4vy uses a merchant account configuration that matches the transaction.

### Matching a merchant account-level configuration

A merchant account-level configuration matches a transaction when all of the following are true:

* The **scheme** equals the card scheme of the transaction.
* The **currency** equals the currency of the transaction, or the configuration applies to all currencies.
* Every key-value pair in the configuration's **metadata** is also present in the transaction's `metadata`, with the same value. The transaction can include other keys. For [native 3DS](/guides/features/3ds/native) and [Click to Pay](/guides/features/click-to-pay/tas), Gr4vy uses the checkout session's `metadata` instead.

The buyer's country, the amount, and the connection aren't used to match a configuration.

<Warning>
  Metadata on a 3DS configuration is a filter, not a label. A configuration
  with metadata only matches transactions that send all of its metadata
  key-value pairs. Leave the metadata empty unless you want to use different
  3DS details for different transactions.
</Warning>

A configuration with empty metadata matches every transaction for its scheme and currency, including transactions without metadata. A transaction without metadata only matches configurations with empty metadata.

### Choosing between matching configurations

When more than one configuration matches a transaction, Gr4vy picks one in this order:

1. A configuration for the transaction's currency is used before a configuration for all currencies.
2. If more than one configuration remains, the oldest one is used.

The number of metadata keys doesn't affect this order. An older configuration with empty metadata is picked before a newer configuration with matching metadata. To use a configuration for specific transactions only, make sure no older configuration with empty metadata exists for the same scheme and currency.

Each configuration needs a unique combination of scheme, currency, and metadata. Adding a duplicate returns a `409` error.

### When no configuration matches

If 3DS is enabled on the connection but no scheme profile or merchant account configuration matches the transaction, the transaction continues without 3DS. Gr4vy doesn't return an error. The transaction is processed without authentication, and its `three_d_secure` field is `null`. This happens before Flow rules are applied, so a Flow rule that forces 3DS doesn't change the outcome.

To avoid this, add a configuration with empty metadata for each card scheme you accept, and use it as a fallback. If you also add configurations with metadata, create the fallback last, or make it apply to all currencies while the others set a currency. Otherwise the fallback is picked before them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.