Your SlideShare is downloading. ×
  • Like
This is a title
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply
Published

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
50
On SlideShare
0
From Embeds
0
Number of Embeds
3

Actions

Shares
Downloads
0
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 1 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.3D-SecureProgrammers GuideLast Updated: 29-April-2011
  • 2. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 2 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.3D-Secure – Programmers Guide1. Description3-D Secure is a payment authentication system that provides secure processing of creditcard transactions in an eCommerce environment. This technology is branded as Verified byVisa (VbV) and MasterCard SecureCode (MCSC) when used by major card brands.RocketGateServersCardholderMerchantWebsite3-D SecureACSCard Issuer1. Enrollment2. Shared3. Shop/Purchase4. Gateway Request5. Gateway Response6. Redirect to ACS7. Redirect from ACS8. Gateway Resubmit9. Gateway ResponseFigure 1Figure 1 provides an overview of the 3-D Secure process. Use of 3-D Secure requiresthat a cardholder register his or her card with the card issuer. This is referred to asenrollment. Security information gathered by the card issuer during enrollment is sharedwith an external Access Control Server (ACS). This is shown as steps 1 and 2 in theillustration. Enrollment of a card only needs to be performed once.When a cardholder makes a purchase at a merchant website, the merchant performs astandard gateway auth-only or purchase transaction. This is shown in steps 3 and 4. If 3-DSecure authentication is required, the gateway returns an error response that includes a URLand an authentication token. The URL is the location of an ACS through which thecardholder must be authenticated.Using the URL in the gateway response, the cardholder’s browser must be redirected tothe ACS. The redirection presents the authentication token to the ACS. This redirectionfunction is performed and controlled by the merchant’s eCommerce system. This is shownin 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, thisinvolves simply providing a password. At the end of the process, the cardholder’s browser isredirected back to the merchant’s website. The redirection presents authentication data backto the merchant. This is shown in step 7 and is described further in section 5 of thisdocument.
  • 3. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 3 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.Once authentication data has been received from the ACS, the merchant may resubmit anauth-only or purchase request. This request must include the authentication data and areference to the original transaction that prompted the use of the 3-D Secure system. This isshown in steps 8 and 9 of the figure.2. EnrollmentFull use of the 3-D Secure system requires that a cardholder register/enroll his or her cardwith the card issuer. This action is not performed by RocketGate or the merchant. Amerchant’s website can encourage users to enroll their card and can even provide instructionsand links to describe the process. However, there is no API or interface that allows amerchant to perform enrollment. This is an external process conducted solely between thecardholder and card issuer.3. Gateway RequestsThe 3-D Secure system is accessed using the standard RocketGate gateway API, i.e.GatewayService, GatewayRequest, and GatewayResponse classes. Auth-only and purchasetransactions are submitted using standard transaction parameters. There is no differencebetween an auth-only/purchase transaction submitted for standard processing and an auth-only/purchase transaction submitted for 3-D Secure processing. The RocketGate system isconfigured to recognize when the use of 3-D Secure is necessary for a transaction. In thoseinstances, 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 auth-only or purchase gateway transaction. Steps 8 and 9 in the figure show that a transaction islater resubmitted to the gateway after all 3-D Secure authentication has been performed.This resubmission is also performed using the standard RocketGate gateway API. Therequest parameters used and response values received during this resubmission are describedin section 5 of this document.4. Enrollment States & EffectsWhen 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. Thesecategories also determine how liability for transactions is shifted. The four categories aredescribed below.4.1.Enrolled
  • 4. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 4 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.When a cardholder has enrolled his or her card in the 3-D Secure program, theprocess 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 EnrolledWhen a cardholder is eligible to participate in the 3-D Secure program but has notyet enrolled, the process shown in figure 1 cannot be followed. In this instance, themerchant can still perform the desired auth-only/purchase transaction. Similar to enrolledcards, the liability for such transactions shifts from the merchant to the card issuer. Theprocess for completing such transactions is described in section 6 of this document.4.3.IneligibleWhen a cardholder is ineligible to participate in the 3-D Secure program, themerchant can still perform the desired auth-only/purchase transaction. However, liabilityfor the transaction does not shift. The process for completing such transactions isdescribed in section 7 of this document.4.4.Undetermined/RejectedIn some instance, the 3-D Secure system is unable to determine if a cardholderhas enrolled his or her card. The 3-D Secure system may also reject a transaction due totechnical difficulties. In these instances, the merchant can still perform the desired auth-only/purchase transaction. However, liability for the transaction does not shift. Theprocess for completing such transactions is described in section 8 of this document.5. Processing Flow - Enrolled CustomerCardholder use of the 3-D Secure system requires that the cardholder register his or hercard with the card issuer. This process is referred to as enrollment. Once a cardholder hasenrolled his or her card, the authentication sequence shown in figure 1 can be initiated as partof an auth-only or purchase transaction. Interfaces and operations included in this sequenceare described below.5.1.Initial RequestFigure 1 shows that use of the 3-D Secure system is initiated through a standardauth-only or purchase gateway transaction. This transaction is performed in the samemanner as a standard transaction; a GatewayRequest object is created and populated todescribe the transaction, a GatewayResponse object is created to receive the results of thetransaction, and a GatewayService object is created and used to communicate with theRocketGate gateway. Pseudo code for this process is provided below.
  • 5. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 5 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.//// Create base objects.//GatewayRequest reqObj = new GatewayRequest();GatewayResponse resObj = new GatewayResponse();GatewayService servObj = new GatewayService();//// Populate request data.//reqObj.Ste(CARDNO, “4111111111111111);… populate other transaction data …boolean status = servObj.PerformPurchase(reqObj, resObj);5.2.ResponseWhen the RocketGate gateway has determined that a cardholder has registered hisor her card with the 3-D Secure program, the initial transaction described above will failand return an error. The error code returned in the response indicates that 3-D Secureauthentication is required. Additional data returned in the response is used as part of theauthentication process. This data includes a URL for the 3-D Secure ACS, and a securitytoken that must be passed to the ACS as part of the authentication process.5.2.1. RESPONSE_CODE & REASON_CODEAs noted above, a transaction that requires 3-D Secure authentication will fail onthe initial auth-only/purchase transaction. These transactions will return thefollowing response and reason codes.RESPONSE_CODE: 2 (RISK_FAIL)REASON_CODE: 202 (3DSECURE_AUTHENTICATION_REQUIRED)The failure of the transaction and the return of these reason/response codes servesas an indicator that the 3-D Secure sequence shown in figure 1 is required.5.2.2. ACS_URLWhen a transaction fails due to the need for 3-D Secure authentication, the URLof an ACS is returned in the response object. This is the URL to which the
  • 6. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 6 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.cardholder should be redirected to perform authentication. As shown below, theURL can be retrieved from the response object using the ACS_URL element.String theURL = resObj.Get(ACS_URL);5.2.3. PAREQWhen a transaction fails due to the need for 3-D Secure authentication, a securitytoken is returned in the response object. This token must be passed to the ACS (seeACS_URL above) as part of the authentication process. As shown, the token can beretrieved from the response object using the PAREQ element.String theToken = resObj.Get(PAREQ);5.2.4. Pseudo-CodeThe following pseudo code shows the flow of processing for the initial auth-onlyor 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…}
  • 7. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 7 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.… 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-SecureStep 6 in figure 1 shows that the cardholder’s browser must be redirected to anACS in the 3-D Secure system to perform authentication. This is handled by posting arequest to the ACS identified in the response object (ACS_URL). The post must includethe security token returned in the response object (PAREQ). The post must also include aURL on the merchant’s website to which the carholder is returned after authentication.The post can also include custom data that is returned to the merchant when thecardholder is redirected back to the merchant’s website.Figure 2 below shows an example of the HTML used to redirect the cardholder’sbrowser 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"><!--function AutoSubmitForm() { document.downloadForm.submit(); }//--></SCRIPT><input type="submit" name="continue" value="Continue"></center></form>/body><html>Figure 2In 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 merchant’s website to which the user is redirected afterauthentication, and MD contains any custom data the merchant would like returned whenthe cardholder is redirected back to the merchant’s 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 theredirection data.
  • 8. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 8 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.5.4.Response from 3D-SecureWhen the cardholder has successfully authenticated, the 3-D Secure ACS willredirect the carholder’s browser back to the merchant’s website. This redirection isperformed using a POST to the URL specified in the TermURL field of the formdescribed in section 5.3The POST to the merchant’s website includes a PaRes variable. This variablecarries an authentication token generated by the 3-D Secure ACS. The POST to themerchant’s website also includes an MD variable. This variable carries the same datathat was provided in the MD field of the form described in section 5.3.5.5.Resubmit with PARESWhen the ACS has redirected the cardholder back to the merchant’s website andprovided an authentication token (PaRes described above), the merchant may resubmitthe initial auth-only/purchase transaction for completion. This operation is performedusing the standard RocketGate gateway API.To resubmit the transaction, the merchant server must perform a new auth-only orpurchase transaction. The request object for this transaction must include the PaResvalue 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 arerequired. 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 withthe PaRes value returned by the ACS. This value is submitted in the PARES element ofthe GatewayRequest object. The GUID number of the original auth-only or purchasetransaction is submitted in the REFERENCE_GUID element of the request. Thisexample also shows that a CVV2 value can/should be provided with the resubmission.6. Processing Flow – Eligible, but not enrolled
  • 9. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 9 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.Cardholder use of the 3-D Secure system requires that the cardholder register his or hercard with the card issuer. This process is referred to as enrollment. If the card is eligible forenrollment 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 thesetypes of transactions.6.1.Initial RequestAs previously noted, all 3-D Secure transactions are initiated using standardRocketGate gateway APIs. See section 5.1 above for details.6.2.Response CodeWhen the RocketGate gateway has determined that a cardholder is eligible for 3-D Secure but is not yet enrolled, the initial auth-only or purchase transaction will returnan error. Under these circumstances, the following response/reason codes will bereturned.RESPONSE_CODE: 2 (RISK_FAIL)REASON_CODE: 203 (3DSECURE_NOT_ENROLLED)The failure of the transaction and the return of these reason/response codes servesas an indicator that the 3-D Secure sequence shown in figure 1 is not required.6.3.ResubmitWhen a transaction fails due to the fact that the card is eligible but not enrolled in3-D Secure, the merchant has the choice to discontinue or complete the transaction. Ifthe merchant decides to discontinue the transaction, no further action is required. If themerchant chooses to complete the transaction, the merchant’s server must resubmit thetransaction. 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 PARESelement.GatewayRequest newReqObj = new GatewayRequest();GatewayResponse newResObj = new GatewayResponse();//// Populate request data.//newReqObj.Set(TRANSACT_ID, originalGUID);newReqObj.Set(CVV2, “XXXX”);
  • 10. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 10 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.status = servObj.PerformPurchase(newReqObj, newResObj);Similar to the example in section 5.5, this pseudo-code shows that a CVV2 valuecan/should be provided with the resubmission.7. Processing Flow - IneligibleCardholder use of the 3-D Secure system requires that the cardholder register his or hercard with the card issuer. This process is referred to as enrollment. If the card is not eligiblefor enrollment, the sequence shown in figure 1 cannot be followed. The following section ofthis document describes the process and options for handling these types of transactions.7.1.Initial RequestAs previously noted, all 3-D Secure transactions are initiated using standardRocketGate gateway APIs. See section 5.1 above for details.7.2.Response CodeWhen the RocketGate gateway has determined that a cardholder is not eligible toparticipate in the 3-D Secure program, the initial auth-only or purchase transaction willreturn an error. Under these circumstances, the following response/reason codes will bereturned.RESPONSE_CODE: 2 (RISK_FAIL)REASON_CODE: 204 (3DSECURE_INELIGIBLE)The failure of the transaction and the return of these reason/response codes servesas an indicator that the 3-D Secure sequence shown in figure 1 is not required.7.3.ResubmitWhen a transaction fails due to the fact that the card is not eligible to participatein 3-D Secure, the merchant has the choice to discontinue or complete the transaction. Ifthe merchant decides to discontinue the transaction, no further action is required. If themerchant chooses to complete the transaction, the merchant’s server must resubmit thetransaction. Section 6.3 above describes the resubmission step and provides pseudo-codefor the process.
  • 11. © 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 portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.8. Processing Flow - Undetermined/RejectedCardholder use of the 3-D Secure system requires that the cardholder register his or hercard with the card issuer. This process is referred to as enrollment. If the 3-D Secure systemis unable to determine whether or not a card is enrolled, the sequence shown in figure 1cannot be followed. This can occur due to various technical failures. The following sectionof this document describes the process and options for handling these types of transactions.8.1.Initial RequestAs previously noted, all 3-D Secure transactions are initiated using standardRocketGate gateway APIs. See section 5.1 above for details.8.2.Response CodeWhen the RocketGate gateway cannot determine whether or not a card is enrolledin the 3-D Secure program, the initial auth-only or purchase transaction will return anerror. Under these circumstances, the following response/reason codes will be returned.RESPONSE_CODE: 2 (RISK_FAIL)REASON_CODE: 205 (3DSECURE_REJECTED)The failure of the transaction and the return of these reason/response codes servesas an indicator that the 3-D Secure sequence shown in figure 1 is not required.8.3.ResubmitWhen a transaction fails because the enrollment state of the card cannot bedetermined, the merchant has the choice to discontinue or complete the transaction. If themerchant decides to discontinue the transaction, no further action is required. If themerchant chooses to complete the transaction, the merchant’s server must resubmit thetransaction. Section 6.3 above describes the resubmission step and provides pseudo-codefor the process.9. Summary of New 3-D Secure Error CodesThe table below describes new error codes that are specific to the use of 3-D Secure.Error Explanation202 3DSECURE_AUTHENTICATION_REQUIREDThe card is enrolled in 3-D Secure. The sequence show in figure 1 must be performed.
  • 12. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 12 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.Details are provided in section 5 of this document.203 3DSECURE_NOT_ENROLLEDThe card is eligible to participate in 3-D Secure, however, it has not been enrolled. Thetransaction can be discarded or competed as described in section 6 of this document.204 3DSECURE_INELIGIBLEThe card is not eligible to participate in 3-D Secure. The transaction can be discarded orcompeted as described in section 7 of this document.205 3DSECURE_REJECTEDThe system can not determine whether or not the card is enrolled in 3-D Secure. Thetransaction can be discarded or competed as described in section 8 of this document.10. Summary of New 3-D Secure Request ParametersUse of the RocketGate 3-D Secure feature may require the inclusion of a PARESparameter in the GatewayRequest object used to resubmit an auth-only/purchase transactionafter authentication by the 3-D Secure ACS. See section 5.5 above for details.Element Name ExplanationPARES Security token returned by the 3-D Secure ACS. This token must beincluded in the GatewayRequest when an auth-only/purchase transaction isresubmitted 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 orpurchase transaction.This flag overrides the default use of 3-D Secure processing. Normally, 3-D 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 validationon subsequent (2nd, 3rd, 4th, etc.) transactions.This flag element accepts a boolean value, i.e. “TRUE” or “FALSE”.11. Summary of Response FieldsTwo additional response values can be returned in transactions performed as part of the3-D Secure program. These fields are returned in response to the initial auth-only orpurchase transaction. The fields are outlined below and described in section 5.2 above.ElementName ExplanationACS_URL URL of an ACS to which the cardholder’s browser is to be redirected. This URL is
  • 13. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 13 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.used to perform 3-D Secure authentication.PAREQ Security token required for authentication by the ACS specified in ACS_URL.12. Test Cards and ResponsesCard NumberEnrollmentState Explanation51051051051051005000000000000009Eligible, butnot enrolled.Returns 3DSECURE_NOT_ENROLLED error forinitial auth-only/purchase submission.40128888888818815000000000000033Ineligible Returns 3DSECURE_INELIGIBLE error for initialauth-only/purchase submission.55555555555544445000000000111111Rejected/UndeterminedReturns 3DSECURE_REJECTED error for initial auth-only/purchase submission.Any other card Enrolled Returns 3DSECURE_AUTHENTICAION_REQUIREDerror for initial auth-only/purchase submission.
  • 14. © Copyright 2007-2011 RocketGate LLC. All Rights Reserved - 14 -This document contains confidential and proprietary information of RocketGate LLC. No disclosure or duplication of any portionof these materials may be made without the express written consent of RocketGate LLC. These materials must be used solely forthe operation of RocketGate LLC programs and for no other use.13. Revision HistoryVersion Description1.0 Initial version1.1 Corrected PaRes and PaReq variable names associated with ACS messages insection 5.Added USE_3D_SECURE request elements in section 10.1.2 Added table of test cards and their responses.Removed “Automatic Resubmit” explanation until later software versions.1.3 Added Maestro International test cards.