threeDSRequest

The threeDSRequest object allows to:

  • determine if a payment is made with or without 3D Secure authentication,
  • transmit the information related to 3D Secure.

If no values are set for this object, a payment without 3D Secure authentication will be made by default.

The objects and attributes of the threeDSRequest object vary depending on the payment type.

  • Payment without 3D Secure

A payment without 3D Secure authentication is a debit operation where the cardholder authentication is not performed.

Only one attribute is required:

threeDSRequest
Attribute Format
mode

Selecting the mode for 3D Secure authentication.

DISABLED

Payment without 3D Secure authentication. Default parameter used in case no values have been populated.

string

Note: all the other attributes are not taken into account when creating a payment without 3D Secure.

  • Payment with 3D Secure

    Payments with 3D Secure authentication require who calls to createPayment operation.

    • The first call for verifying whether the card is enrolled and retrieving the information required for buyer redirection to the ACS.

      Only one attribute is required:

      threeDSRequest
      Attribute Format
      mode

      Selecting the mode for 3D Secure authentication.

      ENABLED_CREATE

      Allows to verify if the card is enrolled for 3D Secure before proceeding to payment.

      string

      Note: all the other attributes are not taken into account when creating a payment with 3D Secure.

    • The second call for analyzing the response of 3D Secure and finalizing the transaction.

      Two attributes are required:

      threeDSRequest
      Attribute Format
      mode

      Selecting the mode for 3D Secure authentication.

      ENABLED_FINALIZE

      Allows to finalize a 3D Secure payment.

      string
      requestId

      With the ENABLED_FINALIZE mode, this attribute must contain the value returned in the threeDSRequestId attribute of the threeDsResponse object in the createPayment operation with the ENABLED_CREATE mode.

      string
      pares

      The PaRes (Payer Authentication Response) message returned by the ACS.

      string

      Note: all the other attributes are not taken into account when creating a payment with 3D Secure.

  • Payment with 3D Secure authentication made by the merchant plug-in (MPI )

Several attributes must be sent for this type of payment.

Warning: setting a specific attribute value may imply setting another attribute value!

Table 1. The threeDSRequest object
threeDSRequest
Attribute Required Format
mode

Selecting the mode for 3D Secure authentication.

MERCHANT_3DS

Allows to make a 3DS payment with the MPI of the merchant.

string
brand

Card scheme.

string
enrolled

Cardholder's enrollment status. The possible values are:

  • Y for enrolled status.
  • N for non-enrolled status.
  • U for unknown status.
string
status

Cardholder's authentication status. The possible values are:

  • Y for 3 DS authenticated status.
  • N for authentication error.
  • U for authentication impossible.
  • A for authentication attempt.

If enrolled is set to Y

string
eci

E-commerce indicator.

The eci value depends on the 3DS authentication status and the card type. The possible values are:
  status =Y status = A status = U status =N
VISA - AMEX 05 06 07 -
MasterCard 02 01 - -

If status is set to Y or A

string
xid

3DS transaction number.

If status is set to Y

string
cavv

ACS certificate.

If status is set to Y or A

string
algorithm

Cardholder Authentication Verification Value (CAVV). The possible values are:

  • 0 for HMAC.
  • 1 for CVV.
  • 2 for CVV_ATN.
  • 3 for Mastercard SPA.

If status is set to Y or A

string