diff --git a/content/docs/admin-api/guides/payment-methods/bankcard.mdx b/content/docs/admin-api/guides/payment-methods/bankcard.mdx
index 40c710c..4b423b7 100644
--- a/content/docs/admin-api/guides/payment-methods/bankcard.mdx
+++ b/content/docs/admin-api/guides/payment-methods/bankcard.mdx
@@ -467,9 +467,18 @@ Older integrations load `iframe-v1.min.js` and call `Spreedly` directly. Replace
3DS2 payments are fully supported via the Admin API to process the customer through an authentication flow, with the final transaction information and results provided back to your application.
-Your store must have a 3DS2-enabled gateway to process 3DS2 transactions.
+Your store must have a 3DS2-enabled gateway to process 3DS2 transactions. A gateway is 3DS2-enabled when its `three_ds_mode` is `smart` or `always`.
+### Smart mode gateways
+
+A gateway in `smart` mode decides per order whether to use 3DS. Orders with a billing address in the United States, Canada, Australia or New Zealand skip 3DS unless they score above the store's risk tolerance. All other orders use 3DS. See [3DS2 Payments](https://docs.nextcommerce.com/docs/features/payments/3ds2-payments#smart-mode) for the full rules.
+
+`payment_return_url` is required on every order to a `smart` gateway, including orders that end up skipping 3DS, because the gateway decides per order. Handle both responses:
+
+- **3DS used:** the response carries a `payment_complete_url`. Continue with the redirect flow below.
+- **3DS skipped:** the order is charged directly and the response is the created order, the same as a gateway with 3DS off.
+
### API payment redirect flow
diff --git a/public/api/admin/2023-02-10.yaml b/public/api/admin/2023-02-10.yaml
index 005993c..8b48aec 100644
--- a/public/api/admin/2023-02-10.yaml
+++ b/public/api/admin/2023-02-10.yaml
@@ -6240,9 +6240,10 @@ components:
- integer
- 'null'
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
+ readOnly: true
gateway_groups:
items:
$ref: '#/components/schemas/PaymentGatewayGroup'
@@ -6291,6 +6292,19 @@ components:
type:
- boolean
- 'null'
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -21676,6 +21690,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.created
object: gateway
@@ -21732,7 +21747,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -21891,6 +21906,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -22014,6 +22042,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.updated
object: gateway
@@ -22070,7 +22099,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -22229,6 +22258,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
diff --git a/public/api/admin/2024-04-01.yaml b/public/api/admin/2024-04-01.yaml
index 6c7863f..72024e6 100644
--- a/public/api/admin/2024-04-01.yaml
+++ b/public/api/admin/2024-04-01.yaml
@@ -6555,9 +6555,10 @@ components:
- integer
- 'null'
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
+ readOnly: true
gateway_groups:
items:
$ref: '#/components/schemas/PaymentGatewayGroup'
@@ -6606,6 +6607,19 @@ components:
type:
- boolean
- 'null'
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -27049,6 +27063,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.created
object: gateway
@@ -27105,7 +27120,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -27264,6 +27279,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -27387,6 +27415,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.updated
object: gateway
@@ -27443,7 +27472,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -27602,6 +27631,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
diff --git a/public/api/admin/unstable.yaml b/public/api/admin/unstable.yaml
index ec3d4a6..a7e5f72 100644
--- a/public/api/admin/unstable.yaml
+++ b/public/api/admin/unstable.yaml
@@ -6513,9 +6513,10 @@ components:
- integer
- 'null'
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
+ readOnly: true
gateway_groups:
items:
$ref: '#/components/schemas/PaymentGatewayGroup'
@@ -6564,6 +6565,19 @@ components:
type:
- boolean
- 'null'
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -26883,6 +26897,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.created
object: gateway
@@ -26939,7 +26954,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -27098,6 +27113,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies
@@ -27221,6 +27249,7 @@ webhooks:
is_default: false
name: string
re_attemp_intitial_charge: null
+ three_ds_mode: 'off'
event_id: a7a26ff2-e851-45b6-9634-d595f45458b7
event_type: gateway.updated
object: gateway
@@ -27277,7 +27306,7 @@ webhooks:
minimum: 1
type: integer
enable_3ds2:
- description: Transactions are attempted with 3DS authentication.
+ description: Derived from `three_ds_mode`. True when the mode is `smart` or `always`.
title: Enable 3D Secure Transactions
type: boolean
gateway_groups:
@@ -27436,6 +27465,19 @@ webhooks:
description: Reattempt soft declines with another gateway.
title: Re-attempt declined initial charge attempts
type: boolean
+ three_ds_mode:
+ description: |-
+ 3DS mode for the gateway.
+
+ * `off` - Off
+ * `smart` - Smart
+ * `always` - Always On
+ enum:
+ - 'off'
+ - 'smart'
+ - 'always'
+ title: 3DS Mode
+ type: string
required:
- card_types
- currencies