3D-Secure Configuration

3D-Secure is a protocol designed to be an additional security layer for online credit and debit card transactions. It was first deployed by Visa with the intention of improving the security of Internet payments and is offered to customers under the name Verified by Visa. Services based on the protocol have also been adopted by MasterCard, JCB International, American Express and Discover.

EMV 3DS is the upgraded version of the protocol, also known as 3DS2, 3DS V2 or 3DS 2.0.

Required checkout fields

Below is a list of the fields for using this product:

Data attribute Presence Description Type
[data-paycertify="amount"] Mandatory The amount of the transaction a 2-decimal places number. 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

Test Cards

In order to run test 3D-Secure checks, use the following cards with any expiration date in the future for different outcomes:

Card Number Issuer Prompt[1] Success[2] Eci Status
4111111111111111 Visa N Y 6 Y
4916909992637469 Visa Y ? ? ?
4000111111111115 Visa N N 7 N
5555555555554444 Mastercard N Y 2 Y
2223000048400011 Mastercard Y ? ? ?
5105105105105100 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 means if the 3D-Secure check succeeded or not.

Ruleset configuration

By default we offer the following rulesets:

  • Very strict ruleset If you want to allow solely the transactions where the liability has been shifted to the bank;
  • Strict ruleset If you to let pass transactions that were successfully 3D-Secure’d (not necessarily shifted);
  • Permissive ruleset Just enabling the product will give you a permissive approach to 3D-Secure;
  • Custom ruleset Through our rule operators, you can use the following list of the parameters and example values that you will get from a 3D-Secure response to create your own ruleset:
Property Description Possible Values
xid 3DS Internal Transaction ID. Should be forwarded to the gateway for liability shift. 012312312314323
eci Electronic Commerce Indicator – shows if the Liability of this transaction was shifted or not 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 the liability shift. ICAgICAgICAgICAgICAgICAgICA=
status Request status and liability indicator. Y = Succeeded
A = Attempted, not necessarily completed / succeeded
U = Unknown, potentially unavailability at card brand or issuing bank level
N = Not authenticated

Forwarding data to the Gateway

Whenever your customer submits the form, after the ruleset is applied and you get a positive verdict, the form should be submitted to the form action you have defined. In that moment, you should receive the parameters needed to perform a 3D-Secure transaction on your form action:

Property Type Length Description Possible Values
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
threeds_version number 1 Version of 3DS protocol used. 1, 2
  • If you’re using our gateway direct API integration, refer to this page for more info;
  • If you’re using our Pay Buttons, that process should happen automatically.
  • If you’re using other gateways or payment providers, please reach out to our support for more information on 3D-Secure for your gateway and see how we can help on that.

Learn more about Rulesets