Payflow Buyer Authentication integration guide

The Payflow Buyer Authentication service enables you to accept payments that require buyer authentication from cardholders enrolled in the Verified by Visa and MasterCard SecureCode programs. Buyer Authentication reduces your risk and builds customer confidence. Additionally, card brands make marketing resources available to promote your website and provide logos you can build into your checkout process.

In a buyer authentication transaction, if a buyer is enrolled in one of these programs, the buyer is redirected to the card issuer's page to authenticate before the payment is finalized. With Payflow's Buyer Authentication service, you can use Payflow parameters in your buyer authentication transaction integration which you already use for your payment transactions; thus simplifying your integration. Standard Payflow request parameters and response values are described in further detail in the Payflow Gateway developer’s guide and reference. Buyer Authentication service integration information is discussed below.

Note: The Buyer Authentication service is not available if PayPal is your merchant bank.

Important: If you are using a third-party merchant plug-in (MPI), not the Payflow Buyer Authentication service, you must collect the equivalent data and pass it to the Payflow servers using Payflow parameters. For more information, navigate directly to the section on how to construct the sale or authorization transaction.

More about Buyer Authentication

Payflow's Buyer Authentication service is an implementation of the 3-D Secure protocol for payment transactions. This protocol ties a financial authorization with an online authentication. The authentication is based on the following three-domain (3-D) model:

  1. Issuer Domain (Card Issuers and Cardholders): Card Issuers enroll and activate cardholder accounts to participate in the buyer authentication programs. The Card Issuer is responsible for authenticating the card holder during the checkout process.
     
  2. Acquirer Domain (Acquirers and Merchants): Merchants communicate with Payflow to initiate the authentication process. Once authentication is completed, the authentication data is appended to the financial transaction sent to the gateway or processor.
     
  3. Interoperability Domain (Allows the Issuer Domain to interoperate with the Acquirer Domain): Payflow communicates with the various directory servers to facilitate communication between cardholder and issuer. Once the cardholder is redirected to the card issuer's authentication site, the cardholder is prompted for authentication credentials.

Contents

Enabling Buyer Authentication

To view the Buyer Authentication setup page:

  1. Existing Payflow merchants can log in to PayPal Manager.

  2. Then, click Buyer Authentication in the Service Summary box, or go to Service Settings > Fraud Protection > Buyer Authentication.

  3. On the Buyer Authentication setup page, if both your processor and merchant bank support Buyer Authentication, follow the on-screen instructions to activate this service.

    Note: If you cannot access the Buyer Authentication page from the Service Summary box or from the Fraud Protection tab, please contact Payflow customer service to enroll.

To enable your account so you can test the Buyer Authentication service, contact Payflow customer service.

Buyer Authentication messaging

Review the following information provided by Visa and Mastercard to make sure that your website look-and-feel and messaging follows their requirements and recommendations:

Some of the recommendations include making sure you display the Verified by Visa and MasterCard SecureCode Learn More logos on the home and checkout pages of your website. These logos alert the buyer to your participation in the Buyer Authentication programs.

In addition to including the logos, make the buyer aware that an authentication password may be required to complete the order, and ensure that the website properly notifies the buyer of the various outcomes of transaction authentication. Buyer Authentication messages should be crafted to let users know the program is available and provides additional security for their accounts. Also, see the second integration step for detailed authentication browser window settings.

Buyer Authentication integration details

This section describes the process of performing Buyer Authentication transactions using Payflow. Refer to the Buyer Authentication API reference for details about the Payflow parameters specific to the Buyer Authentication feature. Standard Payflow request parameters and response values are described in further detail in the Payflow Gateway developer’s guide and reference. You can optionally download the Payflow Gateway SDK and use it for your Payflow and Buyer Authentication integration, but it is not required. If you are using XMLPay, the XMLPay client support for Buyer Authentication is described in the XMLPay developer's guide.

A buyer authentication transaction involves the following four calls:

  1. After receiving the cardholder’s account number, verify that the cardholder is enrolled in the Verified by Visa or MasterCard SecureCode buyer authentication program.
  2. If the cardholder is enrolled, send the authentication request and redirect the customer’s browser to the Access Control Server (ACS), which is the issuing bank's buyer authentication page, sometimes hosted by a third party. After the buyer enters a username and password, the issuing bank authenticates the buyer’s identity and returns a buyer authentication response value.
  3. You then validate the PARES authentication data returned by the ACS server.
  4. If the authentication data is valid, submit the standard Sale or Authorization transaction request to the Payflow server and include the buyer authentication data.

Important: Buyer Authentication supports only sale and authorization payment transaction types.

Note: Response parameter names in Buyer Authentication transactions include length tags. For example, RESPMSG[2]=OK, where the length tag [2] specifies the exact number of characters and spaces that appear in the value returned, OK.

1. Verify that the cardholder is enrolled

To determine whether the cardholder is enrolled in the Verified by Visa or MasterCard SecureCode buyer authentication program, send a request to Payflow as follows.

Verify enrollment request

Use the verify enrollment transaction type (TRXTYPE=E) in this Payflow request.

Note: If you're using XMLPay, use the VerifyEnrollment transaction.

Name Description Max. Length
VENDOR Your app credentials — vendor name
PARTNER Your app credentials — partner name
USER Your app credentials — user name
PWD Your app credentials — vendor’s password
TRXTYPE E — To verify buyer enrollment 1
ACCT Card number
EXPDATE Card expiry date in the format mmyy 4
AMT Transaction amount including two decimal places and without a comma separator
CURRENCY (Required) ISO 4217 3-number currency code. The code for US dollars is 840. 3

Sample request

VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDIfAvailOrSameAsVendor&PWD=Pwd4Payflow&TRXTYPE=E&ACCT=5105105105105100&EXPDATE=1216&AMT=19.25&CURRENCY=840

Verify enrollment response

Name Description Max. Length
RESULT 0 indicates a successful transaction. Any other value indicates an error. See Buyer Authentication error codes below, or, for a complete list, refer to RESULT Values and RESPMSG Text in the Payflow integration guide. 1
RESPMSG Error description if RESULT is not 0; otherwise, OK. See Buyer Authentication error codes below, or, for a complete list, refer to RESULT Values and RESPMSG Text in the Payflow integration guide. Possible values include alphanumeric and the special characters (/,=,+,:,%). 256
AUTHENTICATION_ID Unique identifier for this enrollment verification. 64
AUTHENTICATION_STATUS E: Card enrolled
O: Card not enrolled
X: Cannot be verified
I: An error occurred or request failed
1
ECI E-Commerce Indicator. The ECI value indicates the level of security supported by the merchant when the cardholder provides payment card data for an online purchase. ECI defaults to 7, which means authentication unsuccessful (in this case, because authentication hasn't been attempted yet). See the ECI parameter values for details. 1
ACSURL The URL of the card issuer’s ACS (access control server) page to which you redirect buyers to provide their authentication password. Returned only if the buyer is enrolled (AUTHENTICATION_STATUS=E). 256
PAREQ The Payer authentication request message you send to the card issuing bank’s buyer authentication page (ACSURL). Returned only if the buyer is enrolled (AUTHENTICATION_STATUS=E). 1024

Sample response 1 — Cardholder is not enrolled

If the cardholder is not enrolled in any buyer authentication programs, the returned value of the AUTHENTICATION_STATUS parameter is O. Other possible values for this field are X, cannot be verified, or I, an error occurred. In any of these cases, you can skip the buyer authentication calls and proceed to the final call, submitting a standard Payflow authorization or sale transaction, but be sure to include the returned AUTHENTICATION_ID, AUTHENTICATION_STATUS and ECI parameters and their values in the Payflow authorization or sale transaction request.

RESULT[1]=0&RESPMSG[2]=OK&AUTHENTICATION_ID[20]=48c92770755039d6bb3d&AUTHENTICATION_STATUS[1]=O&ECI[1]=1

Sample response 2 — Cardholder is enrolled

If the cardholder is enrolled, the returned value of the AUTHENTICATION_STATUS parameter is E, enrolled. The parameters AUTHENTICATION_ID and ECI are also returned.

Additionally, the response message includes a PAREQ (payer authentication request) value and the ACSURL, or the URL of the card issuer’s ACS (access control server) page at which buyers provide their password to authenticate themselves. Both of these parameters are used in the next call to authenticate the cardholder.

RESULT[1]=0&RESPMSG[2]=OK&AUTHENTICATION_ID[20]=f43669e4921cf8b504c4&AUTHENTICATION_STATUS[1]=E&PAREQ[428]=eJxVku1ugjAUhm+FeAH0A3Bozpr48WP+2GK23UA9HJVECpYy9e7XCkzXkPS8fcvD6Vvg+2iJ1l+EnSUF79S2+kBRWbxO9mkync4onUmB+3yX8RTTiYLt4pPOCn7ItmVtlIh5LIGN0hMsHrVxCjSel5sPJcMANiioyG7WSgwDWK/B6IrUkloXrfTpVJqDn20Rreqq0eYG7O4D1p1x9qbylAMbBXT2pI7ONXPGLpdLvPMU7CHoGTHWFbCwB9ijuW0XqtYzr2Whpi+5FEWOlGOWU06U7f0HggOFdqQk5wmXIokEn3M5T1Jg93XQVWhCiVksM3/GXkET4IvRCs7zCvioLRkcjzEqoGtTG/I7fFx/NRTUom99mB59r95CxOh8epngzw8Pad+NgLSKJ6InWg8Ir7HhDtlw3b769xv8AhQarWM=&ACSURL[66]=http://pilot-payflowpro.paypal.com/DDDSecure/Acs3DSecureSim/start

2. Send the authentication request and redirect the buyer to the authentication page

If the response from the previous call confirms that the cardholder is enrolled in buyer authentication, place the following response values in an HTTP form and then HTTP POST the values to the ACSURL which was also returned in the previous response.

  • PAREQ — The payer authentication request value which was returned in the enrollment verification response.
  • TermUrl — Your server URL to which you would like the authentication response sent.
  • MD(Required) Any data that you want echoed to the TermUrl by the ACS server. Typically, this contains state information.

Then redirect the customer’s browser to the ACSURL.

Displaying the ACS page

Integrate the buyer authentication window into your checkout flow to allow for consistent site branding during the authentication process. This window must occur within the same browser session as your e-commerce transaction. See the Visa and MasterCard user interface requirements mentioned in the Buyer Authentication messaging section above.

The Visa / MasterCard UI requirements may include the following:

  • The HTML page for displaying the ACS form must be presented in-line (within the same browser session as the e-commerce transaction), preferably as an inline frame.

  • The ACS form should be displayed in a frame set.

    Note: You should not employ pop-up windows. They will be blocked by pop-up blocking software.

  • The window should have the following browser-independent attributes:

    • width=390 (at minimum)
    • height=400 (at minimum)
    • resizable=no
    • scrollbars=yes
    • toolbar=no
    • location=no
    • directories=no
    • status=yes
    • menubar=no

Example

The following example HTML page redirects a customer to the ACSURL and passes a PAREQ as well as the TermURL (your URL for receiving the authentication response).

 <html>
  <head>
   <title>buyer authentication</title>
    <script language="javascript">
     function OnLoadEvent() {
      document.downloadForm.submit();
     }
    </script>
  </head>
  <bodyYour-Background-Color>" background="<Your-Background-Image>" onload="OnLoadEvent()">
   <form name="downloadForm" action="<ACS-URL>" method="POST">
    <noscript>
     <br/>
     <center>
     <h1>Processing your 3-D Secure transaction</h1>
     <h3>JavaScript is currently disabled or is not supported by your browser.<br/></h3>
     <h3>Click <b>Submit</b> to continue processing your 3-D Secure transaction.</h3>
     <input type="submit" value="Submit"/>
     </center>
    </noscript>
    <input type="hidden" name="TermUrl" value="<Your-Server-URL>"/>
    <input type="hidden" name="MD" value="<Your-State-Info>"/>
    <input type="hidden" name="PAREQ" value="<PAREQ>"/>
   </form>
  </body>
</html>

3. Validate the payer authentication data returned by the ACS server

Next, your application, at the TermUrl you specified in the previous step, sends a Payflow request to validate the Payer authentication response message (PARES) returned from the previous call. This Payflow request validates the card issuer’s digital signature on the PARES and the content of the PARES; it also parses the PARES.

Note: Ensure that the PARES value you pass to Payflow does not include any stray carriage returns, especially at the end of the string.

Validate authentication request

Use the validate authentication transaction type TRXTYPE=Z in this Payflow request.

Note: If you're using XMLPay, use the ValidateAuthentication transaction.

Name Description Max. Length
VENDOR Your app credentials — vendor name
PARTNER Your app credentials — partner name
USER Your app credentials — user name
PWD Your app credentials — vendor’s password
TRXTYPE Z — To validate buyer authentication 1
PARES The Payer authentication response message, generated by the ACS and digitally signed by the card issuing bank.

Sample request

VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDIfAvailOrSameAsVendor&PWD=Pwd4Payflow&TRXTYPE=Z&PARES[3648]=eJzdWFmTokoW/isdPW9T0c3iUnLDNiKTXQUrWYU3NllEUUBAfv0kWl1l91TPXebhTowRBpmHkyfPfr5gbiRlFHF6FFzKaDFXoqry4uhTGn77PAvH4SQKp1MvmEbTnYcf4efF/AVoUXVj2HD7XjWCzskU0slkGrG33TzqTsUxwhz0nHhbz4l35U7ecfHPh9/dnIE6N7aLeZ0ePlTqRp9XtVdfqoZbuHePyp/FUqxyFTXlgV5I/+jMqjde/12HNLjbqW/Qqgfe7Qw9GjcKgt2OdvtTspJPI2eyuRw0nbr9JKdp6eVP1u3xUyaKN1qYzVksB9vKCe6kqRlV4qfUJP1jvSWl9OKuSbn5zpK0ouzXl9mNfoARhDv30qIt+8n719Wbh9fb5+Eh++Fj5+K/wWCuWQ

Validate authentication response

Name Value Max. Length
RESULT 0 indicates a successful transaction. Any other value indicates an error. See Buyer Authentication error codes below, or, for a complete list, refer to RESULT Values and RESPMSG Text in the Payflow integration guide. 1
RESPMSG Error description if RESULT is not 0; otherwise, OK. See Buyer Authentication error codes below, or, for a complete list, refer to RESULT Values and RESPMSG Text in the Payflow integration guide. 256
AUTHENTICATION_ID Unique identifier for this authentication validation. Possible values include alphanumeric and the special characters (/,=,+,:,%). 64
AUTHENTICATION_STATUS Y: Authentication Successful — the password was correct
A: Authentication Attempted — the issuing bank does not support buyer authentication
N: Authentication Failed — bad password
U: Unable to authenticate — network error
F: Validate authentication transaction error
1
CAVV Cardholder authentication verification value, also known as AAV. The value generated by the card issuing bank proving the cardholder has been authenticated with a particular transaction. Returned if the AUTHENTICATION_STATUS is Y or A. Possible values include alphanumeric and the special characters (/,=,+,:,%). 64
ECI E-Commerce Indicator. The ECI value indicates the level of security supported by the merchant when the cardholder provides payment card data for an online purchase. It is one of the following:
1 – Cardholder not authenticated (MasterCard)
2 – Cardholder authenticated (MasterCard)
5 – Authentication successful (Visa)
6 – Authentication attempted (Visa)
7 – Authentication unsuccessful (Visa)
1
XID Buyer Authentication transaction ID. Returned if AUTHENTICATION_STATUS is Y or A. Possible values include alphanumeric and the special characters (/,=,+,:,%). 64

Sample response

RESULT[1]=0&RESPMSG[2]=OK&AUTHENTICATION_ID[20]=8d4d5ed66ac6e6faac6d&AUTHENTICATION_STATUS[1]=Y&CAVV[28]=OTJlMzViODhiOTllMjBhYmVkMGU=&ECI[1]=5&XID[28]=YjM0YTkwNGFkZTI5YmZmZWE1ZmY

Payflow uses the card issuer’s digital certificate to validate the PARES digital signature. The response parameter AUTHENTICATION_STATUS=Y means the PARES is valid. Payflow also returns the parsed authentication information from the PARES, which includes AUTHENTICATION_ID, CAVV (cardholder authentication verification value), XID, and ECI.

4. Submit the intended payment transaction to Payflow

The Buyer Authentication service supports only authorization and sale transaction types. Submit the intended sale (TRXTYPE=S) or authorization (TRXTYPE=A) payment transaction to the Payflow server. In addition to the standard sale or authorization transaction data, include buyer authentication data.

Modify your order management system to ensure all authorization transactions to the gateway or processor include the authentication data elements (CAVV, XID, ECI). Without these data elements, the merchant will not receive the benefits of the authentication programs.

Note: Even if you are using a third party merchant plug-in (MPI), not the Payflow Buyer Authentication service, you must collect the equivalent data and pass it to the Payflow servers using Payflow parameters.

Buyer authentication parameters included in the Payflow payment request

Which buyer authentication parameters you include with the Payflow transaction depends upon whether the cardholder is enrolled. Refer to the following table for details:

Cardholder is enrolled Cardholder is not enrolled
AUTHENTICATION_ID AUTHENTICATION_ID
AUTHENTICATION_STATUS AUTHENTICATION_STATUS
CAVV  
ECI ECI
XID  

Note: If using XMLPay, pass the buyer authentication parameters in the ExtData element, as follows:

 <ExtData Name='AUTHENTICATION_ID' Value='Auth-ID'></ExtData>
 <ExtData Name='AUTHENTICATION_STATUS' Value='Status'></ExtData>
 ...

Sample request 1 — cardholder is not enrolled

Submit the intended transaction using the standard Payflow parameters plus the AUTHENTICATION_ID, AUTHENTICATION_STATUS, and ECI buyer authentication parameters returned in the first call, which verified cardholder enrollment.

VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDIfAvailOrSameAsVendor&PWD=Pwd4Payflow&TENDER=C&TRXTYPE=S&ACCT=5555555555554444&EXPDATE=0308&AMT=123.00&AUTHENTICATION_ID[20]=8d4d5ed66ac6e6faac6d&AUTHENTICATION_STATUS[1]=O&ECI[1]=7

Sample request 2 — cardholder is enrolled

Submit the intended transaction using the standard Payflow parameters plus the AUTHENTICATION_ID, AUTHENTICATION_STATUS, CAVV, ECI and XID buyer authentication parameters returned returned in the third call, which validated the PARES.

VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDIfAvailOrSameAsVendor&PWD=Pwd4Payflow&TENDER=C&TRXTYPE=S&TENDER=C&ACCT=5555555555554444&EXPDATE=0308&AMT=123.00&AUTHENTICATION_ID[20]=8d4d5ed66ac6e6faac6d&CAVV[28]=OTJlMzViODhiOTllMjBhYmVkMGU=&AUTHENTICATION_STATUS[1]=1&ECI[1]=5&XID[28]=YjM0YTkwNGFkZTI5YmZmZWE1ZmY

Sample response

For Visa transactions, the response also includes CARDSECURE=Y which confirms that the CAVV is valid. See Visa CARDSECURE parameter values for other possible values for this parameter.

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZIP=
N&IAVS=Y&CVV2MATCH=Y&CARDSECURE=Y

Logging transaction information

A record is maintained of all transactions executed on your account. Use PayPal Manager to view the record and use the information to help reconcile your accounting records.

Note: This record is not the official bank statement. The activity on your account is the official record.

In addition, you should log all Payflow transaction results (except for check information) on your own system. At a minimum, log the following data:

  • PNREF — the Payflow and PayPal Manager transaction ID
  • Transaction date and time
  • Transaction amount

If you have any questions regarding a transaction, use the PNREF to identify the transaction.

Payflow logs buyer authentication enrollment verification transactions, PAREQ values and PARES values. Enrollment verification transactions are logged when the server connects to Visa or MasterCard and gets a meaningful response (card enrollment AUTHENTICATION_STATUS=E, U, or X).

If AUTHENTICATION_STATUS=Y, then the PAREQ value is logged along with the enrollment verification transaction data. Otherwise, the transaction is not logged.

For authentication validation transactions, Payflow logs the PARES value only under the following conditions:

  • There is a matching PAREQ (by Message ID, not by content) in the database.
  • There is no other PARES with the same Message ID in the database. This means that if a duplicate PARES is submitted, it is logged only once.

For information on how to view Buyer Authentication reports, see PayPal Manager online help.

Buyer Authentication API reference

Payflow server URL addresses

Use the following host addresses for sending test and live transactions. These are the same endpoints you use for your Payflow calls.

  • For live transactions, use https://payflowpro.paypal.com
  • For testing purposes, use https://pilot-payflowpro.paypal.com

Buyer Authentication parameter reference

Detailed information about Payflow's Buyer Authentication parameters is included in this section. For standard Payflow parameters, refer to the Payflow Gateway Developer’s Guide and Reference.

For Buyer Authentication enrollment verification parameters, see Step 1 of the Buyer Authentication integration details.

For Buyer Authentication authentication validation parameters, see Step 3 of the Buyer Authentication integration details.

Visa CARDSECURE parameter values

For Visa transactions only, the CARDSECURE response parameter is returned in the final sale or authorization transaction response. This field will return one of the following values.

Name Value
Y Card issuer judges CAVV to be valid
N Card issuer judges CAVV to be invalid
X Cannot determine validity

ECI parameter values

ECI (Electronic Commerce Indicator) is the value returned from Visa and Mastercard to show the result of buyer authentication for a credit card payment.

Description of Scenario Merchant Region TRXTYPE=E AUTHENTICATION_STATUS TRXTYPE=Z AUTHENTICATION_STATUS ECI Merchant calculates ECI?
Visa - Not Enrolled USA O N/A 6 Yes
Visa - Unable to determine enrollment USA X N/A 7 Yes
Visa - Verify Enrollment transaction error USA I N/A 7 Yes
Visa - Card Enrolled - Successful Authentication USA E Y 5 No
Visa - Card Enrolled - Authentication Attempted USA E A 6 No
Visa - Card Enrolled - Authentication Failed USA E N 7 Yes
Visa - Card Enrolled - Unable to Authenticate USA E U 7 Yes
Visa - Card Enrolled - Error in transaction USA E F 7 Yes
MasterCard - Not Enrolled World O N/A 1 Yes
MasterCard - Unable to determine enrollment World X N/A 1 Yes
MasterCard - Verify enrollment transaction error World I N/A 1 Yes
MasterCard - Card Enrolled - Successful Authentication World E Y 2 Yes
MasterCard - Card Enrolled - Authentication Attempted World E A 1 Yes
MasterCard - Card Enrolled - Authentication Failed World E N 1 Yes
MasterCard - Card Enrolled - Unable to Authenticate World E U 1 Yes
MasterCard - Card Enrolled - Validation Failed World E F 1 Yes

Buyer Authentication error codes

Buyer authentication transaction declines and errors are returned in the standard Payflow response parameters. A RESULT value greater than zero indicates a decline or error, which also returns a RESPMSG parameter. The exact wording of the RESPMSG may vary. Sometimes a colon appears after the initial RESPMSG followed by more detailed information.

For a complete list of error codes and messages, refer to RESULT Values and RESPMSG Text in the Payflow integration guide.

RESULT RESPMSG
1001 Buyer Authentication Service unavailable
1002 Buyer Authentication Service — Transaction timeout
1003 Buyer Authentication Service — Invalid client version
1004 Buyer Authentication Service — Invalid timeout value
1011 Buyer Authentication Service unavailable
1012 Buyer Authentication Service unavailable
1013 Buyer Authentication Service unavailable
1014 Buyer Authentication Service — Merchant is not enrolled for Buyer Authentication Service (3-D Secure). To enroll, log in to PayPal Manager, click Security, and then click the Buyer Authentication Service banner on the page.
1021 Buyer Authentication Service — Invalid card type
1022 Buyer Authentication Service — Invalid or missing currency code
1023 Buyer Authentication Service — Merchant status for 3D secure is invalid
1041 Validate Authentication failed: missing or invalid PARES
1042 Validate Authentication failed: PARES format invalid
1043 Validate Authentication failed: Cannot find successful Verify Enrollment
1044 Validate Authentication failed: Signature validation failed for PARES
1045 Validate Authentication failed: Mismatched or invalid amount in PARES
1046 Validate Authentication failed: Mismatched or invalid acquirer in PARES
1047 Validate Authentication failed: Mismatched or invalid Merchant ID in PARES
1048 Validate Authentication failed: Mismatched or invalid card number in PARES
1049 Validate Authentication failed: Mismatched or invalid currency code in PARES
1050 Validate Authentication failed: Mismatched or invalid XID in PARES
1051 Validate Authentication failed: Mismatched or invalid order date in PARES
1052 Validate Authentication failed: This PARES was already validated for a previous Validate Authentication transaction

Test cases

Once you have completed your integration, you can execute the following test cases listed in this section to verify a successful Buyer Authentication integration. Each test case includes the required request parameters that you should pass to generate a unique response that your integration should handle properly.

Refer to Buyer Authentication error codes if you would like to learn more about any errors you encounter while running these tests.

Verified by Visa test cases

The following test cases show the test values to pass to produce various Verified by Visa buyer authentication transaction scenarios.

Visa test case 1 — Cardholder enrolled, successful authentication and successful signature verification

Test values:

ACCT=4000000000000002
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=Y&ECI=5&CAVV=CAVV&XID=XID

Merchant should append the CAVV and ECI flag values to the authorization message.

Liability shift available.

Visa test case 2 — Cardholder enrolled, successful authentication but unsuccessful signature verification

Test values:

ACCT=4000000000000010
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=1044&RESPMSG=Signature verification fails for the PARes&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=Y&ECI=5&CAVV=CAVV&XID=XID

Merchant should not continue authorization, due to the failed signature verification. Merchant should prompt for another form of payment or attempt to authenticate the buyer.

No liability shift.

Visa test case 3 — Cardholder enrolled, unsuccessful authentication but successful signature verification

Test values:

ACCT=4000000000000028
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=N&ECI=7

Merchant should not continue with authorization. Merchant should prompt for another form of payment and is not permitted to submit this transaction for authorization.

No liability shift.

Visa test case 4 — Cardholder enrolled and authentication attempted

Test values:

ACCT=4000000000000101
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=A&ECI=6&CAVV=CAVV&XID=XID

Merchant should append the CAVV and ECI flag values to the authorization message.

Liability shift available.

Visa test case 5 — Timeout encountered while processing enrollment verification call

Test values:

ACCT=4000000000000044
EXPDATE=01/2020

Enrollment verification response:

RESULT=104&RESPMSG=Timeout waiting for Processor response: Host Timeout (30000 seconds) for 'Your-Credential', trxID=Transaction-ID&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=I&ECI=7

Validate authentication response:

Does not apply in this case.

The lookup transaction will simulate a timeout scenario and the required 20 seconds to complete the transaction processing. Merchant integration should handle timeout processing after 10-12 seconds and proceed with the authorization message.

No liability shift.

Visa test case 6 — Cardholder not enrolled; issuing bank not participating

Test values:

ACCT=4000000000000051
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=O&ECI=6

Validate authentication response:

Does not apply in this case.

Merchant should submit the authorization with an ECI=06.

Liability shift available.

Visa test case 7 — Authentication unavailable

Test values:

ACCT=4000000000000069
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=X&ECI=7

Validate authentication response:

Does not apply in this case.

Merchant should proceed with the authorization message.

No liability shift.

Visa test case 8 — Merchant not able to execute transactions (merchant not active)

Test values:

ACCT=4000000000000077
EXPDATE=01/2020

Enrollment verification response:

RESULT=1013&RESPMSG=Can not process the transaction due to internal problem: Error Processing Message Request&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=I&ECI=7

Validate authentication response:

Does not apply in this case.

Merchant should continue with the authorization and contact technical support to investigate and resolve the issue.

No liability shift.

Visa test case 9 — Error response to the enrollment verification call

Test values:

ACCT=4000000000000085
EXPDATE=01/2020

Enrollment verification response:

RESULT=1013&RESPMSG=Can not process the transaction due to internal problem: Error Processing Message Request&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=I&ECI=7

Validate authentication response:

Does not apply in this case.

Merchant should continue with the authorization and contact technical support to investigate and resolve the issue.

No liability shift.

Visa test case 10 — Cardholder enrolled but error response to authentication call

Test values:

ACCT=4000000000000093
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=1013&RESPMSG=can not process the transaction due to internal problem: Error Processing PARes&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=F

Merchants have the option of retaining the liability and submitting the transaction as non-authenticated. An alternative action would be to prompt for another form of payment.

No liability shift.

Visa test case 11 — Cardholder enrolled but authentication unavailable

Test values:

ACCT=4000000000000036
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=7&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=U&ECI=7

Merchant can retry authentication or process the authorization as a merchant liability.

No liability shift.

MasterCard SecureCode test cases

The following test cases show the test values to pass to produce various MasterCard SecureCode buyer authentication transaction scenarios.

MasterCard test case 1 — Cardholder enrolled, successful authentication and successful signature verification

Test values:

ACCT=5200000000000007
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=Y&ECI=2&CAVV=CAVV&XID=XID

Merchant should append the CAVV and ECI flag values to the authorization message.

Liability shift available.

MasterCard test case 2 — Cardholder enrolled, successful authentication but unsuccessful signature verification

Test values:

ACCT=5200000000000015
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=1044&RESPMSG=Signature verification fails for the PARes&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=Y&ECI=2&XID=XID

Merchant should not continue authorization, due to the failed signature verification. Merchant should prompt for another form of payment or attempt to authenticate the cardholder.

No liability shift.

MasterCard test case 3 — Cardholder enrolled, unsuccessful authentication but successful signature verification

Test values:

ACCT=5200000000000023
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=N&ECI=1

Merchant should not continue with authorization. Merchant should prompt for another form of payment and is not permitted to submit this transaction for authorization.

No liability shift.

MasterCard test case 4 — Activation during shopping

Test values:

ACCT=5200000000000106
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&CAVV=CAVV&XID=XID

Merchant should append the ECI flag value to the authorization message.

Liability shift available.

MasterCard test case 5 — Timeout encountered while processing enrollment verification call

Test values:

ACCT=5200000000000049
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=X&ECI=1

Validate authentication response:

Does not apply in this case.

The enrollment transaction will simulate a timeout scenario and the required 20 seconds to complete the transaction processing. Merchant integration should handle timeout processing after 10-12 seconds and proceed with the authorization message.

No liability shift.

MasterCard test case 6 — Cardholder not enrolled because issuing bank not participating

Test values:

ACCT=5200000000000056
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=O&ECI=1

Validate authentication response:

Does not apply in this case.

Merchant should submit the authorization with ECI=1.

Liability shift available.

MasterCard test case 7 — Authentication unavailable

Test values:

ACCT=5200000000000064
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=X&ECI=1

Validate authentication response:

Does not apply in this case.

Merchant should proceed with the authorization message.

No liability shift.

MasterCard test case 8 — Merchant not able to execute transactions (merchant not active)

Test values:

ACCT=5200000000000072
EXPDATE=01/2020

Enrollment verification response:

RESULT=1013&RESPMSG=Can not process the transaction due to internal problem: Error Processing Message Request&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=I&ECI=1

Validate authentication response:

Does not apply in this case.

Merchant should continue with the authorization and contact technical support to investigate and resolve the issue.

No liability shift.

MasterCard test case 9 — Error response to the enrollment verification call

Test values:

ACCT=5200000000000080
EXPDATE=01/2020

Enrollment verification response:

RESULT=1013&RESPMSG=Can not process the transaction due to internal problem: Error Processing Message Request&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=I&ECI=1

Validate authentication response:

Does not apply in this case.

Merchant should continue with the authorization and contact technical support to investigate and resolve the issue.

No liability shift.

MasterCard test case 10 — Cardholder enrolled but error response to authentication call

Test values:

ACCT=5200000000000098
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=1013&RESPMSG=Can not process the transaction due to internal problem: Error Processing PARes&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=F

Merchants have the option to retain the liability and submit the transaction as non-authenticated. An alternate option would be to prompt the buyer for another form of payment.

No liability shift.

MasterCard test case 11 — Cardholder enrolled but authentication unavailable

Test values:

ACCT=5200000000000031
EXPDATE=01/2020

Enrollment verification response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=E&ECI=1&PAREQ=PAREQ&ACSURL=ACSURL

Validate authentication response:

RESULT=0&RESPMSG=OK&AUTHENTICATION_ID=Auth-ID&AUTHENTICATION_STATUS=U&ECI=1

Merchant can retry authentication, or process the authorization as a merchant liability.

No liability shift.