3D-Secure Settings

3D-Secure is an additional security layer protocol for online credit and debit card transactions. It was first introduced by Visa to improve the security of Internet payments. It is now offered to customers under the name Verified by Visa. Mastercard, JCB International, American Express and Discover also provide similar services, based on this protocol. EMV 3DS is the upgraded version of the protocol, also known as 3DS2, 3DS V2 or 3DS 2.0.

Checkout Form Fields

List of the form fields that are necessary to authenticate transaction with 3D-Secure:

Data attribute Presence Description Type
[data-paycertify="amount"] Mandatory The amount of the transaction float, number with 2-decimal places. e.g.: 0.01
[data-paycertify="card-number"] Mandatory The Credit Card number string, 12-19 digits. e.g.: 4111111111111111
[data-paycertify="card-expiry-month"] Mandatory Card expiration month, in two digits string, 2 digits. e.g.: 01
[data-paycertify="card-expiry-year"] Mandatory Card expiration year, in four digits string, 4 digits: e.g.: 2025

The additional fields can be provided to increase authentications with the Issuing banks (only for 3D-Secure 2.0):

Data attribute Presence Description Type
[data-paycertify="email"] Recommended E-mail string
[data-paycertify="cardHolderName"] Recommended First name + Last Name string
[data-paycertify="shippingLine1"] Recommended First line of cardholder street address string
[data-paycertify="shippingLine2"] Recommended Second line of cardholder street address string
[data-paycertify="shippingLine3"] Recommended Third line of cardholder street address string
[data-paycertify="shippingPostCode"] Recommended Zip Code / Postal Code string
[data-paycertify="shippingCity"] Recommended City of cardholder address string
[data-paycertify="shippingState"] Recommended State of cardholder address string
[data-paycertify="shippingCountry"] Recommended Country of cardholder address string
[data-paycertify="billingLine1"] Recommended First line of cardholder street address string
[data-paycertify="billingLine2"] Recommended Second line of cardholder street address string
[data-paycertify="billingLine3"] Recommended Third line of cardholder street address string
[data-paycertify="billingPostCode"] Recommended Zip Code / Postal Code string
[data-paycertify="billingCity"] Recommended City of cardholder address string
[data-paycertify="billingState"] Recommended State of cardholder address string
[data-paycertify="billingCountry"] Recommended Country of cardholder address string

Test Cards

In order to test 3D-Secure, use the following cards with an expiration date in the future for different outcomes.

3D-Secure v.1.0 Test Cards

Card Number Issuer Prompt[1] Success[2] Eci Status
4111111111111111 Visa N Y 6 Y
4916909992637469 Visa Y ?[3] ?[3] ?[3]
4000111111111115 Visa N N 7 N
5555555555554444 Mastercard N Y 2 Y
5339978447172907 Mastercard Y ?[3] ?[3] ?[3]
5105105105105100 Mastercard N N 0 N

3D-Secure v.2.0 Test Cards

Card Number Issuer Prompt[1] Success[2] Eci Status
4539225011794489 Visa N Y 6 Y
4632633008802809 Visa Y ?[3] ?[3] ?[3]
4957587837877027 Visa N N 7 N
5296345017707556 Mastercard N Y 2 Y
5306649221068087 Mastercard Y ?[3] ?[3] ?[3]
5309572686772257 Mastercard N N 0 N

[1] Prompt means that if you were using the strict mode, the user would be shown a pop-up to confirm his information (version 1).
[2] Success confirms whether or not 3D-Secure succeeded.
[3] Depends on the challenge completion.

Authentication Response

After receiving all the data and making a risk assessment, SDK returns the authentication result:

Property Description Possible Values
xid 3DS Internal Transaction ID. Should be forwarded to the gateway for liability shift 012312312314323
eci Electronic Commerce Indicator. Shows whether the liability of the transaction was shifted to the bank 02 or 05 = 3DS authentication succeeded and liability shifted;
01 or 06 = 3DS authentication attempted, but was not or could not be completed;
00 or 07 = 3DS authentication failed or could not be attempted; Card and/or issuing bank are not secured by 3DS, technical errors, or improper configuration.
cavv Cardholder Authentication Verification Value (Base64 string). Should be forwarded to the gateway for liability shift ICAgICAgICAgICAgICAgICAgICA=
protocolVersion 3D-Secure protocol version that was selected for authentication[1] 1.0.2, 2.1.0
acsTransId ACS/Issuing Banks ID[1] ca5f9649-b865-47ce-be6f-54422a0fce47
status Request status and liability indicator Y, A, N, R, U (see below)

[1] Available only for 3D-Secure 2.0

Ruleset Configuration

Rulesets based on Challenge Authentication Statuses:

Transaction Status Authentication Value Description
Y Present Authentication Successful
A Present Attempts Processing Performed
N None Authentication Failed; Not Authenticated; Transaction Denied
R None Authentication Rejected
U None Authentication Could Not Be Performed; Technical or Other Problem

If you’re using our Pay Buttons, by default to Gateway passed transactions only with status Y. In Publishable Key settings it’s possible also allow pass to Gateway transactions with statuses A and/or U.

Forwarding Data to the Gateway

Whenever your customer submits the form, after the ruleset is applied and you get a positive verdict, submit the form to the form action you defined. You should then receive the parameters needed to perform a 3D-Secure transaction on your form action:

Property Type Length Description Possible Values
threeds_enabled boolean 1 Should be set to true in case of challenge authentication was done true, false
threeds_xid string 1-255 Base-64 encoded Transaction ID MDAwMDAwMDAwMDEyMzQ2Njc4OTA=
threeds_eci string 2 Electronic commerce indicator 05
threeds_cavv string 1-255 Cardholder authentication verification value jI3JBkkaQ1p8CBAAABy0CHUAAAA=
threeds_status string 1 Result of 3DS request Y, N, A, U, R
threeds_version number 1 3D-Secure protocol version that was selected for authentication 1, 2
threeds_acstransid string 1-255 ACS/Issuing Banks ID[1] ca5f9649-b865-47ce-be6f-54422a0fce47

[1] Available only for 3D-Secure 2.0

  • If you are using our direct gateway API integration, refer to this page for more information.
  • If you are using our Pay Buttons, then 3D-Secure happens automatically.
  • If you are using other gateways or payment providers, please reach out to our support team for more information on integrating 3D-Secure into your gateway.