> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/api-reference/3ds-configurations.md).

# 3D Secure Configurations

Configure 3D Secure (3DS) authentication for your merchants, discover available 3DS providers, and evaluate whether a prospective transaction requires authentication.

For background on 3DS authentication and when to use it, see the [3D Secure (3DS) Authentication](https://github.com/plexouy/gitbook-public-docs/tree/main/api-rest/core-concepts/3ds-authentication.md) concept page and the [3D Secure Integration Guide](https://github.com/plexouy/gitbook-public-docs/tree/main/api-rest/guides/payments/3ds-integration.md).

**Authentication:** All endpoints require Basic Auth or Bearer Token.

**Authorization:** Endpoints scoped to a merchant require the merchant to belong to the authenticated client. Secondary API keys are additionally restricted to the merchants explicitly granted to them.

***

## Endpoints overview

| Method | Path                                                                   | Description                                                                           |
| ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET`  | `/v1/threeds/providers`                                                | [List available 3DS providers](#list-3ds-providers)                                   |
| `GET`  | `/v1/threeds/providers/{code}`                                         | [Get a 3DS provider](#get-a-3ds-provider)                                             |
| `GET`  | `/v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds` | [Get 3DS settings for a payment method](#get-3ds-settings-for-a-payment-method)       |
| `POST` | `/v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds` | [Create 3DS settings for a payment method](#create-3ds-settings-for-a-payment-method) |
| `PUT`  | `/v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds` | [Update 3DS settings for a payment method](#update-3ds-settings-for-a-payment-method) |
| `POST` | `/v1/merchants/{merchantId}/threeds/check`                             | [Check whether 3DS is required](#check-whether-3ds-is-required)                       |

***

## List 3DS providers

`GET /v1/threeds/providers`

Returns the catalog of 3DS providers available for configuration. Each entry exposes the provider code expected by the settings endpoints and the metadata fields a provider requires.

### Response (200 OK)

```json
[
  {
    "name": "Cybersource",
    "code": "CYBERSOURCE",
    "enabled": true,
    "requiredFields": ["merchantId", "orgId", "apiKey", "sharedSecret"],
    "supportedPaymentMethods": ["visa", "mastercard", "amex"]
  }
]
```

### Response codes

| Code  | Description                                        |
| ----- | -------------------------------------------------- |
| `200` | Provider catalog returned.                         |
| `400` | The provider catalog could not be retrieved.       |
| `401` | Authentication failed or credentials not provided. |

***

## Get a 3DS provider

`GET /v1/threeds/providers/{code}`

Returns the public details of a single provider. The `code` lookup is case-insensitive.

### Path parameters

| Parameter | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| `code`    | string | Yes      | Provider code (case-insensitive), for example `CYBERSOURCE`. |

### Response (200 OK)

```json
{
  "name": "Cybersource",
  "code": "CYBERSOURCE",
  "enabled": true,
  "requiredFields": ["merchantId", "orgId", "apiKey", "sharedSecret"],
  "supportedPaymentMethods": ["visa", "mastercard", "amex"]
}
```

### Response codes

| Code  | Description                                        |
| ----- | -------------------------------------------------- |
| `200` | Provider returned.                                 |
| `401` | Authentication failed or credentials not provided. |
| `404` | Provider not found.                                |

***

## Get 3DS settings for a payment method

`GET /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`

Retrieves the current 3DS settings configured for a merchant's payment method.

### Path parameters

| Parameter         | Type    | Required | Description                                                                    |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `merchantId`      | integer | Yes      | Unique identifier of the merchant.                                             |
| `paymentMethodId` | string  | Yes      | Case-sensitive payment method identifier (for example `visa` or `mastercard`). |

### Response (200 OK)

```json
{
  "provider": "CYBERSOURCE",
  "metadata": {
    "merchantId": "merchant_12345",
    "orgId": "org_67890"
  },
  "enabled": true,
  "rules": {
    "enabled": true,
    "tier": "tier1",
    "basic": {
      "amount": {
        "checkout": { "USD": 100.00, "UYU": 3000.00 },
        "api": { "USD": 50.00, "UYU": 1500.00 }
      }
    }
  }
}
```

### Response codes

| Code  | Description                                         |
| ----- | --------------------------------------------------- |
| `200` | Settings returned.                                  |
| `400` | Merchant not found or invalid payment method.       |
| `401` | Authentication failed or credentials not provided.  |
| `403` | The API key is not allowed to access this merchant. |
| `404` | No 3DS settings configured for this payment method. |

***

## Create 3DS settings for a payment method

`POST /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`

Creates 3DS settings for the specified merchant payment method. The provider must come from the [provider catalog](#list-3ds-providers), and the `metadata` object must include every field listed in the provider's `requiredFields`.

### Request body

```json
{
  "provider": "CYBERSOURCE",
  "metadata": {
    "merchantId": "merchant_12345",
    "orgId": "org_67890",
    "apiKey": "...",
    "sharedSecret": "..."
  },
  "enabled": true,
  "rules": {
    "enabled": true,
    "tier": "tier1",
    "basic": {
      "amount": {
        "checkout": { "USD": 100.00, "UYU": 3000.00 },
        "api": { "USD": 50.00, "UYU": 1500.00 }
      }
    }
  }
}
```

### Response codes

| Code  | Description                                                          |
| ----- | -------------------------------------------------------------------- |
| `200` | Settings created and returned.                                       |
| `400` | Invalid request, missing required metadata, or unsupported provider. |
| `401` | Authentication failed or credentials not provided.                   |
| `403` | The API key is not allowed to access this merchant.                  |

***

## Update 3DS settings for a payment method

`PUT /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}/threeds`

Updates the existing 3DS settings for a payment method. Use this endpoint to switch providers, adjust amount thresholds, or toggle the `enabled` flag.

The request body has the same shape as the create endpoint.

### Response codes

| Code  | Description                                                          |
| ----- | -------------------------------------------------------------------- |
| `200` | Settings updated and returned.                                       |
| `400` | Invalid request, missing required metadata, or unsupported provider. |
| `401` | Authentication failed or credentials not provided.                   |
| `403` | The API key is not allowed to access this merchant.                  |

***

## Check whether 3DS is required

`POST /v1/merchants/{merchantId}/threeds/check`

Evaluates a prospective transaction against the merchant's configured 3DS rules and returns whether 3DS authentication must be performed. This endpoint does not create a 3DS session.

The authenticated client and the merchant from the route are always used for evaluation. Any equivalent fields in the request body are ignored.

Either `token` or `paymentMethodId` is required. When `token` is supplied, it must be a GUID and must belong to the authenticated client.

> Rate limit: this endpoint is rate-limited per client IP. Repeated bursts return `429 Too Many Requests` with a `Retry-After` header.

### Request body

```json
{
  "referenceId": "order-2024-001",
  "token": "tok_1234567890abcdef",
  "paymentMethodId": "visa",
  "bin": "411111",
  "amount": 250.00,
  "currency": "USD",
  "indicator": "purchase",
  "processingMethod": "api",
  "browserDetails": {
    "userAgent": "Mozilla/5.0 ...",
    "ipAddress": "203.0.113.10",
    "deviceFingerprint": "...",
    "device": "desktop",
    "operativeSystem": "Windows"
  }
}
```

### Response (200 OK)

```json
{
  "isRequired": true,
  "paymentMethodId": "visa"
}
```

`paymentMethodId` is populated when a `token` was supplied and the payment method could be derived from the stored instrument.

### Response codes

| Code  | Description                                                                            |
| ----- | -------------------------------------------------------------------------------------- |
| `200` | Evaluation returned.                                                                   |
| `400` | Missing `token` and `paymentMethodId`, invalid token format, or rule evaluation error. |
| `401` | Authentication failed or credentials not provided.                                     |
| `403` | The API key is not allowed to access this merchant.                                    |
| `429` | Rate limit exceeded.                                                                   |

***

## Related guides

* [3D Secure (3DS) Authentication](https://github.com/plexouy/gitbook-public-docs/tree/main/api-rest/core-concepts/3ds-authentication.md)
* [3D Secure Integration Guide](https://github.com/plexouy/gitbook-public-docs/tree/main/api-rest/guides/payments/3ds-integration.md)