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:

Parameter	Type	Description
`enabled`	required`boolean`	Enable 3-D Secure v2.
`3dsOnDemand`	optional`boolean?`	Activates and retries on SCA soft-decline.
`acquirers`	optional`array?`[Acquirer]	An array of acquirer BINs, see Acquirer for more details.
`merchant`	optional`object?`[Merchant]	See Merchant for more details.
`parameterConfig`	optional`object?`[Parameter configuration]	See Parameter configuration for more details.
`mcIdentityCheck`	optional`boolean?`	Mastercard Identity Check Insights enabled.

Acquirer

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

Parameter	Type	Description
`scheme`	required`string` one of:[`visa`, `mastercard`, `amex`, `jcb`, `discover`, `unionpay`, `diners`]	Credit-card scheme.
`bin`	required`string`Regex: `/^[0-9]{5,11}$/`	Bank Identification Number (BIN).
`merchantId`	required`string`	Merchant ID (MID).

Merchant

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

Parameter	Type	Description
`mcc`	optional`string?`	Merchant Category Code (MCC).
`country`	optional`string?`Regex: `/^[0-9]{3}$/`	Merchant country code (ISO 3166-1 numeric country code.).
`name`	optional`string?`Regex: `/^.{0,22}$/`	Merchant name.
`siret`	optional`string?`Regex: `/^\d+$/`	Systeme 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:

Parameter	Type	Description
`challengeIndicator`	optional`string?`one of:[`01`, `02`, `03`, `04`]	Force 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