3D-Secure Programmers Guide

Copyright 2007-2011 RocketGate LLC.
All Rights Reserved
Jan. 15, 2013_28_2
This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portion of these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely for the operation of RocketGate LLC programs and for no other2013. This manuscript is for Khurram Virani's eyes only. Copyright use.
k in sp
3D-Secure
Programmers Guide Last Updated: 29-April-2011
an d
-1-
Do not distribute.
3D-Secure Programmers Guide

1. Description
3-D Secure is a payment authentication system that provides secure processing of credit card transactions in an eCommerce environment. This technology is branded as Verified by Visa (VbV) and MasterCard SecureCode (MCSC) when used by major card brands.
Figure 1 provides an overview of the 3-D Secure process. Use of 3-D Secure requires that a cardholder register his or her card with the card issuer. This is referred to as enrollment. Security information gathered by the card issuer during enrollment is shared with an external Access Control Server (ACS). This is shown as steps 1 and 2 in the illustration. Enrollment of a card only needs to be performed once. When a cardholder makes a purchase at a merchant website, the merchant performs a standard gateway auth-only or purchase transaction. This is shown in steps 3 and 4. If 3-D Secure authentication is required, the gateway returns an error response that includes a URL and an authentication token. The URL is the location of an ACS through which the cardholder must be authenticated. Using the URL in the gateway response, the cardholders browser must be redirected to the ACS. The redirection presents the authentication token to the ACS. This redirection function is performed and controlled by the merchants eCommerce system. This is shown in step 6. The process is described further in section 5 of this document. Once at the ACS, the user is guided through the authentication process. Typically, this involves simply providing a password. At the end of the process, the cardholders browser is redirected back to the merchants website. The redirection presents authentication data back to the merchant. This is shown in step 7 and is described further in section 5 of this document. Copyright 2007-2011 RocketGate LLC. All Rights Reserved -2Jan. 15, 2013_28_2
k in
1. Enrollment Card Issuer 2. Shared
3. Shop/Purchase 6. Redirect to ACS 7. Redirect from ACS 4. Gateway Request 5. Gateway Response 8. Gateway Resubmit 9. Gateway Response Merchant Website
Cardholder
sp
3-D Secure ACS
an
Figure 1
RocketGate Servers
Do not distribute.
Once authentication data has been received from the ACS, the merchant may resubmit an auth-only or purchase request. This request must include the authentication data and a reference to the original transaction that prompted the use of the 3-D Secure system. This is shown in steps 8 and 9 of the figure.
2. Enrollment
Full use of the 3-D Secure system requires that a cardholder register/enroll his or her card with the card issuer. This action is not performed by RocketGate or the merchant. A merchants website can encourage users to enroll their card and can even provide instructions and links to describe the process. However, there is no API or interface that allows a merchant to perform enrollment. This is an external process conducted solely between the cardholder and card issuer.
3. Gateway Requests
The 3-D Secure system is accessed using the standard RocketGate gateway API, i.e. GatewayService, GatewayRequest, and GatewayResponse classes. Auth-only and purchase transactions are submitted using standard transaction parameters. There is no difference between an auth-only/purchase transaction submitted for standard processing and an authonly/purchase transaction submitted for 3-D Secure processing. The RocketGate system is configured to recognize when the use of 3-D Secure is necessary for a transaction. In those instances, the gateway will automatically initiate the sequence of events shown in figure 1. Figure 1 shows that use of the 3-D Secure system is initiated through a standard authonly or purchase gateway transaction. Steps 8 and 9 in the figure show that a transaction is later resubmitted to the gateway after all 3-D Secure authentication has been performed. This resubmission is also performed using the standard RocketGate gateway API. The request parameters used and response values received during this resubmission are described in section 5 of this document.
4. Enrollment States & Effects

When a card is used in 3-D Secure processing, it is placed in one of four categories. These categories determine the transaction flow within the 3-D Secure system. These categories also determine how liability for transactions is shifted. The four categories are described below.
4.1. Enrolled
Copyright 2007-2011 RocketGate LLC. All Rights Reserved
Jan. 15, 2013_28_2
k in
sp
an
-3-
Do not distribute.
When a cardholder has enrolled his or her card in the 3-D Secure program, the process shown in figure 1 can be followed to complete a transaction. In this instance, liability for the transaction shifts from the merchant to the card issuer.
4.2. Eligible Not Enrolled

When a cardholder is eligible to participate in the 3-D Secure program but has not yet enrolled, the process shown in figure 1 cannot be followed. In this instance, the merchant can still perform the desired auth-only/purchase transaction. Similar to enrolled cards, the liability for such transactions shifts from the merchant to the card issuer. The process for completing such transactions is described in section 6 of this document.
4.3. Ineligible
When a cardholder is ineligible to participate in the 3-D Secure program, the merchant can still perform the desired auth-only/purchase transaction. However, liability for the transaction does not shift. The process for completing such transactions is described in section 7 of this document.
4.4. Undetermined/Rejected
In some instance, the 3-D Secure system is unable to determine if a cardholder has enrolled his or her card. The 3-D Secure system may also reject a transaction due to technical difficulties. In these instances, the merchant can still perform the desired authonly/purchase transaction. However, liability for the transaction does not shift. The process for completing such transactions is described in section 8 of this document.
5. Processing Flow - Enrolled Customer

Cardholder use of the 3-D Secure system requires that the cardholder register his or her card with the card issuer. This process is referred to as enrollment. Once a cardholder has enrolled his or her card, the authentication sequence shown in figure 1 can be initiated as part of an auth-only or purchase transaction. Interfaces and operations included in this sequence are described below.
5.1. Initial Request

Figure 1 shows that use of the 3-D Secure system is initiated through a standard auth-only or purchase gateway transaction. This transaction is performed in the same manner as a standard transaction; a GatewayRequest object is created and populated to describe the transaction, a GatewayResponse object is created to receive the results of the transaction, and a GatewayService object is created and used to communicate with the RocketGate gateway. Pseudo code for this process is provided below.
Copyright 2007-2011 RocketGate LLC. All Rights Reserved -4-
Jan. 15, 2013_28_2
k in
sp
an
Do not distribute.
// // Create base objects. // GatewayRequest reqObj = new GatewayRequest(); GatewayResponse resObj = new GatewayResponse(); GatewayService servObj = new GatewayService();
5.2. Response
When the RocketGate gateway has determined that a cardholder has registered his or her card with the 3-D Secure program, the initial transaction described above will fail and return an error. The error code returned in the response indicates that 3-D Secure authentication is required. Additional data returned in the response is used as part of the authentication process. This data includes a URL for the 3-D Secure ACS, and a security token that must be passed to the ACS as part of the authentication process.
5.2.1. RESPONSE_CODE & REASON_CODE
5.2.2. ACS_URL When a transaction fails due to the need for 3-D Secure authentication, the URL of an ACS is returned in the response object. This is the URL to which the
Copyright 2007-2011 RocketGate LLC. All Rights Reserved -5-
Jan. 15, 2013_28_2
k in
RESPONSE_CODE: REASON_CODE:
// // Populate request data. // reqObj.Ste(CARDNO, 4111111111111111); populate other transaction data
boolean status = servObj.PerformPurchase(reqObj, resObj);
As noted above, a transaction that requires 3-D Secure authentication will fail on the initial auth-only/purchase transaction. These transactions will return the following response and reason codes. 2 202 (RISK_FAIL) (3DSECURE_AUTHENTICATION_REQUIRED)
The failure of the transaction and the return of these reason/response codes serves as an indicator that the 3-D Secure sequence shown in figure 1 is required.
sp
an
Do not distribute.
cardholder should be redirected to perform authentication. As shown below, the URL can be retrieved from the response object using the ACS_URL element. String theURL = resObj.Get(ACS_URL); 5.2.3. PAREQ
5.2.4. Pseudo-Code
Jan. 15, 2013_28_2
k in
} }
When a transaction fails due to the need for 3-D Secure authentication, a security token is returned in the response object. This token must be passed to the ACS (see ACS_URL above) as part of the authentication process. As shown, the token can be retrieved from the response object using the PAREQ element. String theToken = resObj.Get(PAREQ);
The following pseudo code shows the flow of processing for the initial auth-only or purchase transaction using 3-D Secure. // // Create base objects. // GatewayRequest reqObj = new GatewayRequest(); GatewayResponse resObj = new GatewayResponse(); GatewayService servObj = new GatewayService(); // // Populate request data. // reqObj.Set(CARDNO, 4111111111111111); populate other transaction data status = servObj.PerformPurchase(reqObj, resObj); if (status) { // Succeed? Purchase is complete Done
responseCode = resObj.Get(RESPONSE_CODE); reasonCode = resObj.Get(REASON_CODE); if ((responseCode != 2) || (reasonCode != 203)) { Purchase failed Done
sp
an
-6-
Do not distribute.
Secure 3-D required Get response values theURL = resObj.Get(ACS_URL); theToken = resObj.Get(PAREQ); originalGUID = resObjh.Get(TRANSACT_ID);
// Will need this later
5.3. Post to 3D-Secure
Step 6 in figure 1 shows that the cardholders browser must be redirected to an ACS in the 3-D Secure system to perform authentication. This is handled by posting a request to the ACS identified in the response object (ACS_URL). The post must include the security token returned in the response object (PAREQ). The post must also include a URL on the merchants website to which the carholder is returned after authentication. The post can also include custom data that is returned to the merchant when the cardholder is redirected back to the merchants website. Figure 2 below shows an example of the HTML used to redirect the cardholders browser to the ACS.
<html> <head> <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8"> <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache"> <meta HTTP-EQUIV="Pragma" CONTENT="no cache"> <meta HTTP-EQUIV="Expires" CONTENT="0"> </head> <body OnLoad="AutoSubmitForm();"> <form name="downloadForm" action="<AcsUrl>" method="POST"> <input type="hidden" name="PaReq" value="<PaReq>"> <input type="hidden" name="TermUrl" value="<TermUrl>"> <input type="hidden" name="MD" value="<optionalValue>"> <SCRIPT LANGUAGE="Javascript">  </SCRIPT> <input type="submit" name="continue" value="Continue"></center> </form> /body> <html>
In this example, AcsUrl contains the URL returned in the response object (ACS_URL), PaReq contains the token returned in the response object (PAREQ), TermUrl contains the URL on the merchants website to which the user is redirected after authentication, and MD contains any custom data the merchant would like returned when the cardholder is redirected back to the merchants website. Please note that these fields and their names are not defined by RocketGate. These items are defined by the 3-D Secure infrastructure and are expected/required in the redirection data.
Copyright 2007-2011 RocketGate LLC. All Rights Reserved -7This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portion of these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely for the operation of RocketGate LLC programs and for no other2013. This manuscript is for Khurram Virani's eyes only. Copyright use.
k in
sp
Figure 2
an
Jan. 15, 2013_28_2
Do not distribute.
5.4. Response from 3D-Secure

When the cardholder has successfully authenticated, the 3-D Secure ACS will redirect the carholders browser back to the merchants website. This redirection is performed using a POST to the URL specified in the TermURL field of the form described in section 5.3 The POST to the merchants website includes a PaRes variable. This variable carries an authentication token generated by the 3-D Secure ACS. The POST to the merchants website also includes an MD variable. This variable carries the same data that was provided in the MD field of the form described in section 5.3.
5.5. Resubmit with PARES
When the ACS has redirected the cardholder back to the merchants website and provided an authentication token (PaRes described above), the merchant may resubmit the initial auth-only/purchase transaction for completion. This operation is performed using the standard RocketGate gateway API. To resubmit the transaction, the merchant server must perform a new auth-only or purchase transaction. The request object for this transaction must include the PaRes value provided by the ACS and the GUID_NO of the original auth-only/purchase request. Optionally, a CVV2 value can be included in the transaction request. No other fields are required. Following is pseudo code that illustrates this process. GatewayRequest newReqObj = new GatewayRequest(); GatewayResponse newResObj = new GatewayResponse(); // // Populate request data. // newReqObj.Set(TRANSACT_ID, originalGUID); newReqObj.Set(PARES, theACSToken); newReqObj.Set(CVV2, XXXX); status = servObj.PerformPurchase(newReqObj, newResObj); This pseudo code shows that a new request object is created and populated with the PaRes value returned by the ACS. This value is submitted in the PARES element of the GatewayRequest object. The GUID number of the original auth-only or purchase transaction is submitted in the REFERENCE_GUID element of the request. This example also shows that a CVV2 value can/should be provided with the resubmission.
6. Processing Flow Eligible, but not enrolled

k in
sp
an
Jan. 15, 2013_28_2
Do not distribute.
Cardholder use of the 3-D Secure system requires that the cardholder register his or her card with the card issuer. This process is referred to as enrollment. If the card is eligible for enrollment but has not been enrolled, the sequence shown in figure 1 cannot be followed. The following section of this document describes the process and options for handling these types of transactions.
As previously noted, all 3-D Secure transactions are initiated using standard RocketGate gateway APIs. See section 5.1 above for details.
6.2. Response Code
When the RocketGate gateway has determined that a cardholder is eligible for 3D Secure but is not yet enrolled, the initial auth-only or purchase transaction will return an error. Under these circumstances, the following response/reason codes will be returned.
6.3. Resubmit
When a transaction fails due to the fact that the card is eligible but not enrolled in 3-D Secure, the merchant has the choice to discontinue or complete the transaction. If the merchant decides to discontinue the transaction, no further action is required. If the merchant chooses to complete the transaction, the merchants server must resubmit the transaction. This is similar to the resubmission process described in section 5.2 above. However, no PARES element is required in the GatewayRequest object. Following is pseudo-code for the resubmission process without the PARES element. GatewayRequest newReqObj = new GatewayRequest(); GatewayResponse newResObj = new GatewayResponse(); // // Populate request data. // newReqObj.Set(TRANSACT_ID, originalGUID); newReqObj.Set(CVV2, XXXX);
k in
The failure of the transaction and the return of these reason/response codes serves as an indicator that the 3-D Secure sequence shown in figure 1 is not required.
sp
2 203
an
(RISK_FAIL) (3DSECURE_NOT_ENROLLED)
Jan. 15, 2013_28_2
Do not distribute.
status = servObj.PerformPurchase(newReqObj, newResObj); Similar to the example in section 5.5, this pseudo-code shows that a CVV2 value can/should be provided with the resubmission.
7. Processing Flow - Ineligible

Cardholder use of the 3-D Secure system requires that the cardholder register his or her card with the card issuer. This process is referred to as enrollment. If the card is not eligible for enrollment, the sequence shown in figure 1 cannot be followed. The following section of this document describes the process and options for handling these types of transactions.
7.2. Response Code
When the RocketGate gateway has determined that a cardholder is not eligible to participate in the 3-D Secure program, the initial auth-only or purchase transaction will return an error. Under these circumstances, the following response/reason codes will be returned.
7.3. Resubmit
When a transaction fails due to the fact that the card is not eligible to participate in 3-D Secure, the merchant has the choice to discontinue or complete the transaction. If the merchant decides to discontinue the transaction, no further action is required. If the merchant chooses to complete the transaction, the merchants server must resubmit the transaction. Section 6.3 above describes the resubmission step and provides pseudo-code for the process.
Jan. 15, 2013_28_2
k in
sp
2 204
an
(RISK_FAIL) (3DSECURE_INELIGIBLE)
- 10 -
Do not distribute.
8. Processing Flow - Undetermined/Rejected

Cardholder use of the 3-D Secure system requires that the cardholder register his or her card with the card issuer. This process is referred to as enrollment. If the 3-D Secure system is unable to determine whether or not a card is enrolled, the sequence shown in figure 1 cannot be followed. This can occur due to various technical failures. The following section of this document describes the process and options for handling these types of transactions.
8.2. Response Code
When the RocketGate gateway cannot determine whether or not a card is enrolled in the 3-D Secure program, the initial auth-only or purchase transaction will return an error. Under these circumstances, the following response/reason codes will be returned.
8.3. Resubmit
When a transaction fails because the enrollment state of the card cannot be determined, the merchant has the choice to discontinue or complete the transaction. If the merchant decides to discontinue the transaction, no further action is required. If the merchant chooses to complete the transaction, the merchants server must resubmit the transaction. Section 6.3 above describes the resubmission step and provides pseudo-code for the process.
9. Summary of New 3-D Secure Error Codes

The table below describes new error codes that are specific to the use of 3-D Secure. Error Explanation 202 3DSECURE_AUTHENTICATION_REQUIRED The card is enrolled in 3-D Secure. The sequence show in figure 1 must be performed.
Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 11 This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portion of these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely for the operation of RocketGate LLC programs and for no other2013. This manuscript is for Khurram Virani's eyes only. Copyright use.
k in
sp
2 205
an
(RISK_FAIL) (3DSECURE_REJECTED)
Jan. 15, 2013_28_2
Do not distribute.
203
Details are provided in section 5 of this document. 3DSECURE_NOT_ENROLLED The card is eligible to participate in 3-D Secure, however, it has not been enrolled. The transaction can be discarded or competed as described in section 6 of this document. 3DSECURE_INELIGIBLE The card is not eligible to participate in 3-D Secure. The transaction can be discarded or competed as described in section 7 of this document. 3DSECURE_REJECTED The system can not determine whether or not the card is enrolled in 3-D Secure. The transaction can be discarded or competed as described in section 8 of this document.
204
k in
205
10. Summary of New 3-D Secure Request Parameters

Use of the RocketGate 3-D Secure feature may require the inclusion of a PARES parameter in the GatewayRequest object used to resubmit an auth-only/purchase transaction after authentication by the 3-D Secure ACS. See section 5.5 above for details.
sp
an
Element Name PARES
Explanation Security token returned by the 3-D Secure ACS. This token must be included in the GatewayRequest when an auth-only/purchase transaction is resubmitted after authentication by the 3-D Secure ACS.
See section 5.5 above for details. USE_3D_SECURE Flag value requesting 3-D Secure authentication for an auth-only or purchase transaction. This flag overrides the default use of 3-D Secure processing. Normally, 3D Secure authtentication is only performed the first time a card is used. The USE_3D_SECURE flag can be used to request 3-D Secure validation on subsequent (2nd, 3rd, 4th, etc.) transactions. This flag element accepts a boolean value, i.e. TRUE or FALSE.
11. Summary of Response Fields

Two additional response values can be returned in transactions performed as part of the 3-D Secure program. These fields are returned in response to the initial auth-only or purchase transaction. The fields are outlined below and described in section 5.2 above. Element Name Explanation ACS_URL URL of an ACS to which the cardholders browser is to be redirected. This URL is Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 12 Jan. 15, 2013_28_2
Do not distribute.
PAREQ
used to perform 3-D Secure authentication. Security token required for authentication by the ACS specified in ACS_URL.
12. Test Cards and Responses

Card Number 5105105105105100 5000000000000009 4012888888881881 5000000000000033 5555555555554444 5000000000111111 Any other card Enrollment State Explanation Eligible, but Returns 3DSECURE_NOT_ENROLLED error for not enrolled. initial auth-only/purchase submission. Ineligible Returns 3DSECURE_INELIGIBLE error for initial auth-only/purchase submission. Rejected/ Returns 3DSECURE_REJECTED error for initial authUndetermined only/purchase submission. Enrolled Returns 3DSECURE_AUTHENTICAION_REQUIRED error for initial auth-only/purchase submission.
Jan. 15, 2013_28_2
k in
sp
an d
- 13 -
Do not distribute.
13. Revision History

Version 1.0 1.1 Description Initial version Corrected PaRes and PaReq variable names associated with ACS messages in section 5. Added USE_3D_SECURE request elements in section 10. Added table of test cards and their responses. Removed Automatic Resubmit explanation until later software versions. Added Maestro International test cards.
1.2 1.3
Jan. 15, 2013_28_2
k in
sp an d
- 14 -
Do not distribute.

3D-Secure Programmers Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

3D-Secure Programmers Guide

Încărcat de

Drepturi de autor:

Formate disponibile

Copyright 2007-2011 RocketGate LLC.

All Rights Reserved

Jan. 15, 2013_28_2