3-D Secure v2

Introduction

Almost every card scheme implements an authentication system : 3-D Secure for Visa, Secure Code for Mastercard, Safekey for American Express (…)
3-D Secure is an authentication protocol designed to be an additional security layer for online transactions. The 3-D Secure protocol helps you to mitigate fraud and provide a liability shift to your transactions in case of chargebacks.
The 3-D Secure process concerns payment and authorization transactions in e-commerce.

tips

Payplug Premium anti-fraud solution helps you lower your fraud rates under RTS thresholds. Contact you Payment Manager for more information.

There are 2 versions of the 3-D Secure protocol:

  • 3-D Secure v1: existing version of 3-D Secure. An authentication is not always required before a payment is authorized. When it is, the cardholder is redirected to the card issuer’s site to provide authentication data such as an SMS verification code or a password.
  • 3-D Secure v2: new version of 3-D Secure that should fully replace 3-D Secure v1 by 2022. For payments and authorizations within the PSD2 scope, an authentication will always have to be completed successfully before a payment is authorized. However, the authentication will not always require extra interactions from the cardholder. For instance, low-risk transactions will be frictionless for cardholders.

If you are already using Payplug Internal 3-D Secure server, only small changes should be made to support 3-D Secure v2. Our gateway will automatically handle the 3-D Secure v2 protocol and transition:

  • Strong Customer Authentication exemption handling
  • Fallback to 3-D Secure v1 if the issuing bank is not ready for 3-D Secure v2.
tips

If you are migrating to 3-D Secure v2, please contact your Payment Manager to activate your account with ther 3-D Secure v2 protocol.

Internal 3-D Secure

3-D Secure v2 allows issuing banks to get additional data from each transaction to generate a more accurate risk profile of the payment. New mandatory parameters such as billing or shipping information should be sent in you payment or authorization request. New optional parameters such as cardholder’s previous transaction history may be added to help lower the risk level of the transaction and increase the frictionless authentication rate.

tips

You may minimize cardholder friction by providing additional optional data to your payment request.

Standard parameters

You have to include these parameters regardless of your integration mode.

info

A 3-D Secure authentication is not required for out of scope transactions. Therefore, the 3-D Secure v2 required parameters become optional if 3DSECUREOUTOFSCOPEREASON is sent.

tips

There are no specific 3-D Secure v2 mandatory parameters. However, in order to optimize your integration and maximize your conversation rate, we recommend sending at least the recommended parameters.

warning

For internal 3-D Secure, use the 3DSECUREVERSION field only if you want a 3DS version for the transaction that is different from the one used by default for the account (configured in the setup).

warning

For 3-D Secure operations, the field CARDFULLNAME can only contain the following characters : [a-zA-Z1-9 -].

  • 3DSECUREAUTHENTICATIONAMOUNT integer

    Amount of the authentication in the smallest money decimal (e.g. cents for euro). Example: 10 EUR is submitted as 1000. Shall be used if the authentication amount differs from the transaction amount. By default, Dalenys considers that the authentication amount equals the transaction amount.

    Example: 1000

  • 3DSECUREAUTHENTICATIONDATE datetime(yyyy-MM-dd HH:mm:ss)

    3-D Secure authentication date in UTC. May be used if the authentication date differs from the transaction date. By default, Dalenys considers that the authentication date equals the transaction timestamp in UTC.

    Example: 2020-12-01 11:00:01

  • 3DSECURECHALLENGEWINDOWSIZE 01, 02, 03, 04, 05

    Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window.

    By default, Dalenys will set the challenge window size to full size.

    Related resolutions (width x height):

    01 250 x 400
    02 390 x 400
    03 500 x 600
    04 600 x 400
    05 Full screen

    Example: 04

  • 3DSECUREDISPLAYMODE main,popup,top,raw

    Define the 3-D Secure authentication page display mode:
    main: in the current frame;
    popup: in a browser popup;
    top: in the parent frame (useful in case of iframe integration);
    raw: to handle the redirection by yourself.

    Example: main

  • 3DSECUREOUTOFSCOPEREASON moto

    Shall be used if the transaction type is out of scope of Strong Customer Authentication (SCA).
    moto:Mail Order/Telephone Order

    Example: moto

  • 3DSECUREPREFERENCE sca, frictionless, nopref, scamandate

    3DS Requestor Challenge Indicator. Mandatory for CB.
    Accepted values:
    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;
    nopref default value when absent, the decision will be made by Dalenys;
    scamandate strong authentication required by regulation

    Example: sca

  • ACCOUNTCHANGEDATE date(YYYY-MM-DD)

    The date the cardholder made a change to his/her account on the merchant’s website, including billing or shipping address, new means of payment, or adding new user(s).

    Example: 2018-01-10

  • ACCOUNTCREATIONDATE date(YYYY-MM-DD)

    The date on which the cardholder opened his/her account on the merchant site.

    Example: 2018-01-10

  • BILLINGADDRESS string(1-50)

    The billing address. Be careful not to integrate any line breaks.

    Example: 285 Fulton Street

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2).

    Example: US

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • BILLINGSTATE string(max 3)

    The state or province of the Cardholder billing address. It is different from the country code, and should be the country subdivision code defined in ISO 3166-2 (cf https://www.iso.org/obp/ui/en/#iso:pub:PUB500001:en).
    If you do not provide a value, Dalenys will use a default value for each country.

    Example: IDF

  • CARDENROLLDATE date(YYYY-MM-DD)

    Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

    Example: 2018-01-01

  • CLIENTAUTHMETHOD guest, credentials, federated, issuer, thirdparty, fido

    Mechanism used by the Cardholder to authenticate.
    Accepted values:
    guest: No merchant authentication occurred (i.e. cardholder “logged in” as guest);
    credentials: Login to the cardholder account at the merchant system using merchant’s own credentials;
    federated: Login to the cardholder account at the merchant system using federated ID;
    issuer: Login to the cardholder account at the merchant system using issuer credentials;
    thirdparty: Login to the cardholder account at the merchant system using third-party authentication;
    fido: Login to the cardholder account at the merchant system using FIDO Authenticator;

    Example: credentials

  • DELIVERYEMAIL email(5-255)

    For Electronic delivery, the email address to which the merchandise was delivered.

    Example: john.snow@example.com

  • DELIVERYTIMEFRAME electronic,sameday,overnight,longer,

    Indicates the merchandise delivery timeframe.

    Example: sameday

  • GIFTCARDAMOUNT integer

    For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in minor units (cents).

    Example: 100

  • GIFTCARDCOUNT int(1-2)

    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

    Example: 2

  • GIFTCARDCURRENCY string(3)

    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

    Example: EUR

  • HOMEPHONE string(max 32)

    The home phone number provided by the Cardholder in international (E.164) format.

    Example: +33133333333

  • ITEMAVAILABILITY yes, no

    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

    Example: true

  • LAST12MONTHSTRANSACTIONCOUNT int(1-3)

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

    Example: 4

  • LAST24HOURSADDCARDATTEMPTS int(1-3)

    Number of “Add Card” attempts in the last 24 hours.

    Example: 2

  • LAST24HOURSTRANSACTIONCOUNT int(1-3)

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

    Example: 4

  • LAST6MONTHSPURCHASECOUNT int(1-4)

    Number of purchases with this cardholder account during the previous six months.

    Example: 4

  • MOBILEPHONE string(max 32)

    The mobile phone number provided by the Cardholder in international (E.164) format.

    Example: +33633333333

  • PASSWORDCHANGEDATE date(YYYY-MM-DD)

    The date the cardholder made a password change or account reset on the merchant site.

    Example: 2018-01-10

  • PREORDERDATE date(YYYY-MM-DD)

    For a pre-ordered purchase, the expected date that the merchandise will be available.

    Example: 2018-02-01

  • RECURRINGEXPIRY date(YYYY-MM-DD)

    Date after which no further authorisations shall be performed in a recurring payment workwlow.

    Example: 2020-01-04

  • RECURRINGFREQUENCY int(1-4))

    Indicates the minimum number of days between authorisations.

    Example: 10

  • REORDERINGITEM yes, no

    Indicates whether the cardholder is reordering previously purchased merchandise.

    Example: false

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOADDRESSDATE date(YYYY-MM-DD)

    Date when the shipping address used for this transaction was first used with the 3DS Requestor.

    Example: 2018-04-02

  • SHIPTOADDRESSTYPE billing, verified, new, storepickup, edelivery, travelpickup, other

    Shipping indicator. The parameter DELIVERYEMAIL is mandatory when edelivery mode is set.
    The other ship to address fields are optional when ‘storepickup’, travelpickup or other is set.
    Possible values:
    billing: Ship to cardholder’s billing address
    verified: Ship to another verified address on file with merchant
    new: Ship to address that is different than the cardholder’s billing address
    storepickup: Pick-up at local store (Store address shall be populated in shipping address fields)
    edelivery: Digital goods (includes online services, electronic gift cards and redemption codes)
    travelpickup: Travel and Event tickets, not shipped
    other: Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)

    Example: verified

  • SHIPTOCITY string(1-255)

    The shipping city.

    Example: New York

  • SHIPTOCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2 format)

    Example: US

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • SHIPTOSTATE string(max 3)

    The state or province of the Cardholder shipping address. It is different from the country code, and should be the country subdivision code defined in ISO 3166-2 (cf https://www.iso.org/obp/ui/en/#iso:pub:PUB500001:en).
    If you do not provide a value, Dalenys will use a default value for each country.

    Example: IDF

  • SUSPICIOUSACCOUNTACTIVITY yes, no

    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

    Example: `no`

  • WORKPHONE string(max 32)

    The work phone number provided by the Cardholder in international (E.164) format.

    Example: +33633333333

warning

Depending on the value of the SHIPTOADDRESSTYPE parameter, the mandatory status of some related parameters changes:

SHIPTOADDRESSTYPE values Affected parameters
EDELIVERY DELIVERYEMAIL becomes mandatory
VERIFIED, NEW or BILLING SHIPTOCOUNTRY, SHIPTOADDRESS, SHIPTOCITY and SHIPTOPOSTALCODE become mandatory
STOREPICKUP or TRAVELPICKUP or OTHER DELIVERYEMAIL, SHIPTOCOUNTRY, SHIPTOADDRESS, SHIPTOCITY , SHIPTOPOSTALCODE become optional

Define 3-D Secure authentication page display mode

You may define the 3-D Secure authentication page display mode by sending 3DSECUREDISPLAYMODE in your payment or authorization request regardless of your integration mode. By default, Payplug will display the authentication page in the current frame. You may setup you account with a different default display mode. Please contact you Payment Manager to setup your account.

  • 3DSECUREDISPLAYMODE main,popup,top,raw

    Define the 3-D Secure authentication page display mode:
    main: in the current frame;
    popup: in a browser popup;
    top: in the parent frame (useful in case of iframe integration);
    raw: to handle the redirection by yourself.

    Example: main

Redirect authentication

With 3-D Secure v2, all transactions - except out-of scope transactions such as MIT transactions - must be authenticated by the issuing bank. The transactions can go through either a frictionless or a challenge flow.

If you are using our Hosted-fields or server to server integration, you need to redirect the user to the authentication page.

info

If you are using our hosted form integration, Payplug handles the authentication redirection for both 3-D Secure v1 and 3-D Secure v2.

When an authentication is required, Payplug will return EXECCODE=0001 and either REDIRECTHTML or REDIRECTURL depending on the redirection option you choose in the request response:

  • HTML redirection: the REDIRECTHTML returns a HTML content that is base64 encoded. The string content will have to be base64 decoded before being displayed to the cardholder.
  • URL redirection: if you are using 3DSECUREDISPLAYMODE=raw in your payment or authorization request, you will receive REDIRECTURL and REDIRECTPOSTPARAMS instead of REDIRECTHTML in your request response. To redirect the cardholder, submit a POST request with REDIRECTPOSTPARAMS as POST parameters to REDIRECTURL as destination.
info

REDIRECTPOSTPARAMS is string URL encoded. The content have to be URL decoded before sending the parameters to the REDIRECTURL.

After the authentication is completed, either frictionless or with Strong Customer Authentication, the cardholder will be redirected to your platform using the REDIRECT_URL configured in your account settings and you will be able to retrieve the transaction final result. See details in Redirect specifics section.

  • REDIRECTHTML string(no length limit)

    HTML content to display to the user to continue the processing. The string is base64 encoded.

    Example:

  • REDIRECTPOSTPARAMS string(no length limit)

    The content is string URL encoded and contains the POST parameters to send to the REDIRECTURL.

    Example: p1=v1&p2=v2

  • REDIRECTURL string(no length limit)

    The url to redirect the user to continue the processing.

    Example: http://some_url?p1=v1

Redirection result

In both server to server and hosted form modes, you will only receive the transaction’s final result once the user is redirected to your platform.

You can then display a confirmation message to the user and process the transaction in your application.

security

‘You have to check the received HASH against the one you generate, to confirm the request’s origin and integrity before redirecting the user. See this section for more information. Other parameters relating to the original request as AMOUNT and ORDERID must be verified.’

Additional redirection and notification parameters

3-D Secure transactions can be configured to receive additional parameters. Please contact your Payment Manager to setup your account.

  • 3DSECUREAUTHENTICATIONSTATUS y, n, u, a, c, r, i, empty

    Authentication status:
    y: authentication successful
    n: not authenticated
    u: unavailable
    a: attempted
    c: cardholder challenge required
    r: rejected
    i: Informational Only
    empty: no 3-D Secure

    Example: y

  • 3DSECUREMODE sca, frictionless

    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication

    Example: sca

  • 3DSECURESIGNATURESTATUS y, n

    Signature verification status. Possible values are:
    y: signature is present in PARes message
    n: no signature present in PARes message

    Example: y

  • 3DSECUREVERSION 1, 2

    The version of the 3-D Secure protocol that you want to use for the transaction. It will override the setup of the account.

    Example: 2

  • 3DSGLOBALSTATUS ok, not_enrolled, unavailable, not_required, ko

    Global status.

    Example: ok

  • CARD3DSECUREENROLLED y, n, u

    Card 3-D Secure enrollment status. Possible values are:
    y: Card enrolled
    n: Card not enrolled
    u: Enrollment unavailable

    Example: y

Trigger 3-D Secure v1

You shall add the following parameters to your authorization or payment request to trigger 3-D Secure v1 if you are not ready for 3-D Secure v2:

  • 3DSECUREDISPLAYMODE main,popup,top,raw

    Define the 3-D Secure authentication page display mode:
    main: in the current frame;
    popup: in a browser popup;
    top: in the parent frame (useful in case of iframe integration);
    raw: to handle the redirection by yourself.

    Example: main

  • 3DSECUREPREFERENCE sca, frictionless, nopref, scamandate

    3DS Requestor Challenge Indicator. Mandatory for CB.
    Accepted values:
    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;
    nopref default value when absent, the decision will be made by Dalenys;
    scamandate strong authentication required by regulation

    Example: sca

info

Once your checkout page is ready to handle 3-D Secure v2, please contact your Payment Manager to setup your account.

External 3-D Secure

It’s possible to use your own or a third-party 3-D Secure server, you have to ask the activation of this option to your payment manager and then add the following fields to your 3-D Secure transactions:

warning

For transactions made with french cobranded cards, it is recommended to respect the preferred brand also for the authentication (and make sure your MPI has a connexion with CB’s 3DSv2 network).

3-D Secure v2 request parameters

info

A 3-D Secure authentication is not required for out of scope transactions. Therefore, the 3-D Secure v2 required parameters become optional if 3DSECUREOUTOFSCOPEREASON is sent.

  • 3DSECUREACSTRANSACTIONID uuid(36)

    Universally unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122.

    Example: 4dc406b0-038d-43ef-a96c-c85352c5e2c0

  • 3DSECUREAUTHENTICATIONAMOUNT integer

    Amount of the authentication in the smallest money decimal (e.g. cents for euro). Example: 10 EUR is submitted as 1000. Shall be used if the authentication amount differs from the transaction amount. By default, Dalenys considers that the authentication amount equals the transaction amount.

    Example: 1000

  • 3DSECUREAUTHENTICATIONDATE datetime(yyyy-MM-dd HH:mm:ss)

    3-D Secure authentication date in UTC. May be used if the authentication date differs from the transaction date. By default, Dalenys considers that the authentication date equals the transaction timestamp in UTC.

    Example: 2020-12-01 11:00:01

  • 3DSECURECARDENROLLED u, n, y

    Card’s enrollment status. Possible values:

    u:Card enrolled
    n:Card not enrolled
    y:Enrollment unavailable

    Example: y

  • 3DSECURECAVV hexadecimal string(max 45)

    3-D Secure “Cardholder Authentication Verification Value”.

    Example: 8c47ab90f2b9c3219208115b182f520360000000

  • 3DSECURECAVVALGORITHM int (1)

    3-D Secure “Cardholder Authentication Verification Value” algorithm(0-9).

    Example: 3

  • 3DSECURECHALLENGECANCELATION string(2)

    Challenge Cancellation Indicator. Mandatory for CB transactions.

    Accepted values:

    01 = Cardholder selected “Cancel”
    02 = 3DS Requestor cancelled Authentication
    03 = Transaction Abandoned
    04 = Transaction Timed Out at ACS—other timeouts
    05 = Transaction Timed Out at ACS—First CReq not received by ACS
    06 = Transaction Error
    07 = Unknown
    08-79 = Reserved for future EMVCo use (values invalid until defined by EMVCo)
    80–99 = Reserved for future DS use

    Example: 01

  • 3DSECUREDSTRANSACTIONID uuid(36)

    Universally unique transaction identifier assigned by the DS to identify a single transaction. Canonical format as defined in IETF RFC 4122.

    Example: 4dc406b0-038d-43ef-a96c-c85352c5e2c0

  • 3DSECUREECI string (1)

    Electronic Commerce Indicator.

    Example: 5

  • 3DSECUREEXEMPTIONREASON low_value, transaction_risk_analysis, secure_corporate_payments

    3-D Secure exemption reason.

    low_value = transactions below 30€
    transaction_risk_analysis = applicable if payment provider’s fraud rates for card payments do not exceed the following thresholds:
    0.13% to exempt transactions below €100
    0.06% to exempt transactions below €250
    0.01% to exempt transactions below €500
    secure_corporate_payments = transactions initiated by a legal person (e.g a business). Includes payments made with virtual cards or B2B Cards.

    Example: low_value

  • 3DSECUREMODE sca, frictionless

    Applied authentification mode:
    sca Strong authentication;
    frictionless Frictionless authentication;

    Example: sca

  • 3DSECUREOUTOFSCOPEREASON mit, moto, one_leg_out, anonymous_prepaid_card

    3-D Secure out of scope reason. Shall be used if the transaction type is out of scope of Strong Customer Authentication (SCA). The following transaction types are out of scope of SCA:

    mit Merchant Initiated Transactions
    moto Mail Order/Telephone Order
    one_leg_out
    anonymous_prepaid_card

    Example: mit

  • 3DSECUREPREFERENCE sca, frictionless, nopref, scamandate

    3DS Requestor Challenge Indicator. Mandatory for CB.
    Accepted values:
    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;
    nopref default value when absent, the decision will be made by Dalenys;
    scamandate strong authentication required by regulation

    Example: sca

  • 3DSECURESCORE string(2)

    CB scoring. Mandatory for CB transactions.

    Example: 25

  • 3DSECURESTATUS U, N, A, Y, R, I

    3-D Secure status:

    Y = authentication successful
    N = not authenticated
    U = authentication unavailable
    A = authentication attempted
    R = authentication rejected
    I = Informational Only

    Example: y

  • 3DSECURETRANSACTIONSTATUSREASON string(2)

    Transaction status reason. Mandatory for CB transactions.
    Accepted values:
    01 = Card authentication failed
    02 = Unknown Device
    03 = Unsupported Device
    04 = Exceeds authentication frequency limit
    05 = Expired card
    06 = Invalid card number
    07 = Invalid transaction
    08 = No Card record
    09 = Security failure
    10 = Stolen card
    11 = Suspected fraud
    12 = Transaction not permitted to cardholder
    13 = Cardholder not enrolled in service
    14 = Transaction timed out at the ACS
    15 = Low confidence
    16 = Medium confidence
    17 = High confidence
    18 = Very High confidence
    19 = Exceeds ACS maximum challenges
    20 = Non-Payment transaction not supported
    21 = 3RI transaction not supported
    22–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
    80–99 = Reserved for DS use

    Example: 01

  • 3DSECUREVERSION 1, 2, 2.1.0, 2.2.0

    The version of the 3-D Secure protocol that you want to use for the transaction. It will override the setup of the account.

    Example: 2

3-D Secure v1 request parameters

  • 3DSECURECARDENROLLED u, n, y

    Card’s enrollment status. Possible values:

    u:Card enrolled
    n:Card not enrolled
    y:Enrollment unavailable

    Example: y

  • 3DSECURECAVV hexadecimal string(max 45)

    3-D Secure “Cardholder Authentication Verification Value”.

    Example: 8c47ab90f2b9c3219208115b182f520360000000

  • 3DSECURECAVVALGORITHM int (1)

    3-D Secure “Cardholder Authentication Verification Value” algorithm(0-9).

    Example: 3

  • 3DSECUREECI string (1)

    Electronic Commerce Indicator.

    Example: 5

  • 3DSECURERESULT string

    6 character value composed of 3DSECURESTATUS (PARes result) converted to hexadecimal concatenated with the VRes result converted to hexadecimal

    Example: 590040

  • 3DSECURESTATUS U, N, A, Y, R, I

    3-D Secure status:

    Y = authentication successful
    N = not authenticated
    U = authentication unavailable
    A = authentication attempted
    R = authentication rejected
    I = Informational Only

    Example: y

  • 3DSECUREVERSION 1, 2, 2.1.0, 2.2.0

    The version of the 3-D Secure protocol that you want to use for the transaction. It will override the setup of the account.

    Example: 2

  • 3DSECUREXID string(max 40)

    3-D Secure X id
    For Visa/JCB/American Express/Diners/Discover cards
    The XID shall be a 40-bytes numeric value (ASCII)
    For MasterCard cards
    The XID field is optional for Mastercard / Maestro transactions with an ECI of 01, but should be populated with a 20-bytes alphanumeric transaction identifier\

    Example: 00000000000000000501

Sandbox test cards

You may use specific cards to test the 3-D Secure different scenarios:

  • Frictionless 3-D Secure
  • 3-D Secure authentication required

Please refer to our Sandbox test cards.