Skip to main content

3-D Secure connector configuration

The 3-D Secure connector configuration is an important aspect of integrating IXOPAY platform with 3-D Secure enabled connectors. This configuration sets the operational parameters for handling and processing 3-D Secure transactions.

The configuration settings for 3-D Secure are accessible via the Connector - Settings vault endpoint. The vaultConfig.threeDV2Config field in the response contains the available configuration fields.

"baseConfig": {
// other connector configurations
"vaultConfig": {
// vault connector configurations
"threeDV2Config": {
// ...

The fields described in this documentation should be set in the config.vault field of the request body when making a Connector – Create or Connector – Update call.

Here's an illustrative example of a request body for a Connector – Create call:

"name": "Example 3-D Secure Connector",
"adapter": "SimulatorPci",
"method": "Creditcard",
"apiKey": "example-3ds-connector",
"publicIntegrationKey": "XTcSyLgJ04b7cHkvKScG",
"sharedSecret": "V0WkgQPsHAUH4iXCsqWGYDeFKc4O6G",
"config": {
"vault": {
"threeDV2Config": {
"enabled": true,
"3dsOnDemand": true,
"acquirers": [
"scheme": "visa",
"bin": "412345",
"merchantId": "M123456789"
"merchant": {
"mcc": "5944",
"country": "840",
"name": "Alex's Artisan Goods"
"preferredProtocolVersion": "latest",
"enforcePreferredProtocolVersion": false

The following sections provide a detailed explanation of each configuration parameter, its data type, and its function.

3-D Secure 2.x configuration


The list of parameters may be updated over time. To ensure you have the most recent set of parameters, make a call to the Connector - Settings vault endpoint.

The config.vault.threeDV2Config object contains the following parameters:

enabledbooleanEnable 3-D Secure v2.
3dsOnDemandbooleanActivates and retries on SCA soft-decline.
acquirersarray[Acquirer]An array of acquirer BINs, see Acquirer for more details.
merchantobject[Merchant]See Merchant for more details.
parameterConfigobject[Parameter configuration]see Parameter configuration for more details.
preferredProtocolVersionstringPreferred protocol version, must be one of:
  • 2.1.0
  • 2.2.0
  • latest
enforcePreferredProtocolVersionbooleanEnforcees the preferred protocol version.
overrideRequestorIdstringOverrides the requestor ID.
overrideRequestorNamestringOverrides the requestor name.


The config.vault.threeDV2Config.acquirers[i] object contains the following parameters:

schemestringMust be one of the following:
  • visa
  • mastercard
  • amex
  • jcb
  • discover
  • unionpay
  • diners
binstringBank Identification Number (BIN).
merchantIdstringMerchant ID (MID).


The config.vault.threeDV2Config.merchant object contains the following parameters:

mccstringMerchant Category Code (MCC).
countrystringMerchant country code (ISO 3166-1 numeric country code.).
namestringMerchant name.
siretstringSysteme d'Identification du Repertoire des ETablissements (SIRET) number. Required for Carte Bancaire (CB) only.

Parameter configuration

The config.vault.threeDV2Config.parameterConfig object contains the following parameters:

challengeIndicatorstringForce challenge indicator. Must be one of the following:
  • 01 - No preference
  • 02 - No challenge requested
  • 03 - Challenge requested: 3DS Requestor Preference
  • 04 - Challenge requested: Mandate