> 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/blob/main/api-rest/core-concepts/3ds-authentication.md) concept page and the [3D Secure Integration Guide](https://github.com/plexouy/gitbook-public-docs/blob/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      | Payment method identifier (for example `VISA`). |

### 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/blob/main/api-rest/core-concepts/3ds-authentication.md)
* [3D Secure Integration Guide](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/guides/payments/3ds-integration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/api-reference/3ds-configurations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.