API Flow

This section describes how we support 3DS Pre-Authentication by third parties and how to pass along the information when creating the Order.

Flow overview

Examples

Pre-authentication 3DS1

HTTP Request
[show]

Pre-authentication 3DS2

HTTP Request
[show]

Data for 3DS

SecurePaymentAlert.PayerAuth

Field Eligibility Required Description Example

PARes

3DS1

Yes

This is the PARes value from 3D Secure.

Y,A,N,U.

See Issuer Authentication-Results Values.

SecurePaymentAlert.EnrollmentStatus

This is the VERes value from 3D Secure.

Eligibility: 3DS1

Required: Yes

See Verify Enrollment Response Values.

SecurePaymentAlert.Reference

Field Eligibilty Required Description Example

ACS_TxnReference

3DS2

Yes

Unique 3D Secure transaction reference number assigned by Access Control System (ACS)

Example: 13c701a3-5a88-4c45-89e9-ef65e50a8bf9.

OriginalTransactionID

3DS1 and 3DS2

Yes

This is the transaction ID from the 3D Secure provider.

For 3DS1, this field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.

For 3DS2, this field corresponds to the identifier assigned by the scheme directory server. This is commonly a string in UUID format.

Example 3DS1: ZGUzNzgwYzQxM2ZlMWM0MzVkMjc=

Example 3DS2: f38e6948-5388-41a6-bca4-b49723c19437

TxnDescription

3DS1 and 3DS2

Yes

Indicates the version of 3D Secure used for authentication. Defaults to 1 if not provided.

Example 1 or 2.1.0

SecurePaymentAlert.ProcessingInfos.ProcessingInfo

Field Eligibility Required Description Example

ECI

3DS1 and 3DS2

Yes

The ECI (E-Commerce Indicator) security level associated with the transaction.

Only returned if the card is enrolled and authenticated.

01,02,05,06,07.

See Visa Electronic Commerce Indicator (ECI) and MasterCard E-Commerce Commerce Indicator (ECI).

CAAV

3DS1 and 3DS2

Yes

The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer.

Only returned if the card is enrolled and authenticated.

Base64 encoded data.

Example: Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=

CustomerAuthStatus

3DS1 and 3DS2

Yes

3DS Program ACS Customer Authentication value.

Y,N,R,A,U,C.

See 3-D Secure authentication Result.

Tables

Table 1. Visa Electronic Commerce Indicator (ECI)
Name ECI Description

Cardholder was authenticated

05

This value means that the cardholder was authenticated by the issuer by verifying the cardholder’s password or identity information. The value is returned by the ACS in the Payer Authentication Response message when the cardholder successfully passed 3-D Secure payment authentication.

Merchant attempted to authenticate the cardholder

06

This value means that the merchant attempted to authenticate the cardholder, but either the cardholder or issuer was not participating. The value should be returned by the ACS in the Authentication Response message for an Attempt Response. Additionally, merchants may use an ECI 6 in the authorization request when a Verify Enrollment of N is received from the Visa Directory Server.

Payment authentication was not performed

07

This value is set by the merchant when the payment transaction was conducted over a secure channel (for example, SSL/TLS), but payment authentication was not performed, or when the issuer responded that authentication could not be performed. An ECI 7 applies when either the Verify Enrollment or the Payer Authentication Response contains a U for Unable to Authenticate.
Table 2. MasterCard E-Commerce Commerce Indicator (ECI)
Name ECI Description

Merchant attempted to authenticate the cardholder

01

Authentication could not be completed but a proof of authentication attempt was provided

Cardholder was authenticated

02

Cardholder was successfully authenticated
Table 3. Issuer Authentication-Results Values
Authentication Result Authentication Result Determined by Issuer ACS PARes Status

Authentication Successful

The issuer has authenticated the cardholder by verifying the password or other identifying information.

Y

Authentication Failed

The cardholder’s password (or other authentication information) failed validation, thus, the issuer is not able to authenticate the cardholder. The following are reasons to fail an authentication:

Cardholder fails to correctly enter the authentication information within the issuer-defined number of entries (possible indication of fraudulent user). Cardholder “cancels” authentication page (possible indication of a fraudulent user). Merchants are not permitted to submit these transactions for authorization processing.

N

Attempts Processing Performed

Authentication was not available, but functionality was available (through the issuer, the Visa Attempts Service, or a third party) to generate a proof the merchant attempted VbV authentication.

A

Authentication Could Not Be Performed

The issuer ACS is not able to complete the authentication request – possible reasons include:

* Card type is excluded from attempts (such as a Commercial Card or an anonymous Prepaid Card)

* ACS not able to handle authentication request message

* ACS is not able to establish an SSL session with cardholder browser

* System failure that prevents proper processing of the authentication request

Merchants may proceed with the above purchases as non-authenticated and retain liability if the cardholder later disputes making the purchase. These are non-Verified by Visa electronic commerce transactions.

When the PARes has a U and an Invalid Request Code of 55, this indicates that the Account Identifier in the PAReq did not match the value returned by the ACS in the VERes. Merchants must view this as an invalid transaction.

U
Table 4. Verify Enrollment Response Values
Enrollment Response Description VERes Status

Authentication Available

The cardholder is enrolled, Activation During Shopping is supported, or proof of attempted authentication available. The merchant uses the URL of issuer ACS included in VERes to create the Payer Authentication Request.

Y

Cardholder Not Participating

Cardholder Not Participating – Cardholder is not enrolled.

N

Unable to Authenticate or Card Not Eligible for Attempts

Unable to Authenticate or Card Not Eligible for Attempts (such as a Commercial or anonymous Prepaid card).

U
Table 5. 3-D Secure authentication Result
Name ACS

Successful authentication

Y

Failed authentication

N

Rejected authentication

R

An authentication attempt occurred but could not be completed.

A

Unable to complete authentication

U

Challenge required for authentication

C

Alternative: Pre-authentication included

HTTP Request
[show]
HTTP Response
[show]

Alternative: Pre-authentication not included

HTTP Request
[show]
HTTP Response
[show]
HTTP Request
[show]
HTTP Response
[show]