Merchant Card Payment Engine

Transcription

1 Merchant Card Payment Engine GATEWAY FREEDOM +IMA 3D SECURE INTEGRATION SUPPLEMENT Copyright PayPoint.net 2010 This document contains the proprietary information of PayPoint.net and may not be reproduced in any form or disclosed to any third party without the expressed written permission of a duly authorised representative of PayPoint.net Limited. Registered in England No: VAT Reg. No:

2 PayPoint.net Gateway Freedom +IMA 3D Secure Supplement 1 st June 2010 Table of Contents 1 Overview Payment Process Integration Testing... 5 Appendix A: Requesting & Setting Up 3D Secure... 6 Appendix B: Alternative 3D Secure Providers... 6 Table of Figures Figure 1: 3D Secure Payment Process Comparison... 3 Figure 2: 3D Secure Card Enrolment Key Request/Response Differences... 4 Figure 3: Additional 3D Secure Response Parameters... 5 Figure 4: 3D Secure Authorisation Resume Parameters... 5 Page 2 of 6

3 1 Overview This document assumes you have read Gateway Freedom +IMA MCPE (Merchant Card Payment Engine) integration guide and are familiar with the purpose of 3D Authentication, summarised at 3D Secure Authentication is offered as part of an extended API for clients using Gateway Freedom +IMA MCPE. It allows you to support the service without requiring a full integration with a dedicated 3D Secure provider and without lengthy testing. Implementing 3D Secure Authentication via Freedom +IMA MCPE requires that your integration with our payment gateway is extended to add support for the PayPoint.net 3D Secure API extensions, a handful of simple additional parameters. Use of this extended API will result in an additional intermediate response/request, during any authorisation in which the cardholder is enrolled in the 3D Secure programme. All other payment requests simply proceed as normal. Currently, chargeback liability shift exists for all 3D Secure requests, even where a card is not enrolled and is processed without 3D Secure. Responsibility is passed to the card issuer, since you as the Merchant are attempting to authenticate all customers. 2 Payment Process For a normal Freedom +IMA MCPE integration, a payment request is received via your website or application, and a request is then submitted to the PayPoint.net secure payment gateway, resulting in an immediate authorisation response. When your account is setup for 3D Secure via Freedom +IMA MCPE (see Appendix A) all authorisation requests are subject to a 3D Secure enrolment check. This verifies if a card has been setup for the service and can be authenticated. In these cases an intermediate API response returns a Visa or MasterCard URL, allowing you to divert the customer to a card scheme authentication form. This form seeks to authenticate all 3D Secure enrolled cardholders before payment. In all other cases where the card is not enrolled or the card issuer does not support 3D secure, the original authorisation request is processed as normal, such that the first response from the payment gateway is simply a transaction outcome. Figure 1: 3D Secure Payment Process Comparison Traditional Integration Integration with 3D Secure* 3D Secure Response Authentication Request Browser Redirect Authentication Response Authorisation Resume From MCPE From Card Scheme *Only occurs with cards enrolled for 3D Secure For supported cardholders, the intermediate response contains a URL for the card-issuers ACS (access control server) and a few values identifying the transaction, which need to be POSTed as part of a redirect to this remote authentication procedure. When the cardholder is re-directed to the card issuer ACS, you also need to POST a URL to which the customer will be returned after authentication. This allows the payment process to continue without interruption after the 3D Secure check. Where you need to persist some information about your customer to enable your systems to recognise them upon return from the ACS, you can include this reference as part of a GET query string on the URL which you provide for the customer return. Page 3 of 6

4 Upon performing the POST re-direct to the ACS, your customer is transferred in their web browser to either a Verified by Visa (VbV) or MasterCard SecureCode (McSC) authentication form, provided by Visa, MasterCard of the card issuer. If the cardholder is enrolled but not yet registered for 3D Secure, they are invited to do so, but are also given the option to skip the procedure altogether. If the cardholder is already registered, they must complete authentication in order to proceed. When the customer is returned to your domain, the POST re-direct will include an authentication response. You simply supply this value as part of a second request to the MCPE payment gateway which effectively resumes payment authorisation. With the intermediate request/response mechanism completed, normal transaction processing with 3D Secure can then proceed and results in a traditional card authorisation response from our payment gateway, backed by 3D authentication. 3 Integration Your extended integration must support the possibility of an alternate authorisation response for intermediate 3D Secure authentication. This will occur for any card enrolled for the service. All other requests will be processed as normal. Please note that 3D Secure will only operate on those Freedom +IMA MCPE integrations supplying a fltapiversion of 1.4 or higher. Please check your existing integration and review latest Freedom +IMA MCPE documentation. Can I select which transactions to perform 3D Secure on? Yes! Although PayPoint.net recommends you perform 3D Secure on all payment transactions, the integration parameter fltapiversion, which is submitted with each Freedom +IMA MCPE transaction, can be used to specify whether 3D Secure should be supported or not. By supplying a value of fltapiversion=1.4, 3D Secure will be used and an enrolment check will take place. Supply a lower value typically 1.3 and the transaction will be sent direct for bank authorisation without 3D Secure. This allows you to limit its use on specific transactions. For enrolled cards we do not immediately proceed to payment: instead MCPE will respond to your request with the inttransid and strsecuritytoken transaction references (traditionally supplied after authorisation) and a series of 3D Secure values: strtranstype (the transaction type, in this case S3DVALIDATE) strs3dtransid (a 20-digit 3D Secure transaction ID, not the same as the inttransid transaction ID) strs3durl (a URL from the card issuer, where cardholder needs to be re-directed to for authentication) strs3drequest (the payer authentication request, used by the card issuer to conduct authentication) strs3dmerchantdata (some merchant data from our systems which is transmitted through the process) Figure 2: 3D Secure Card Enrolment Key Request/Response Differences 3D Secure Card Not Enrolled *Equivalent to non-3d request/response intstatus=0 or intstatus=1 3D Secure Card Enrolled 3D Secure Response strtranstype=s3dvalidate intstatus= s=2 From MCPE From Card Scheme Authentication Request Authorisation Resume strtranstype=s3dauth Browser Redirect Authentication Response intstatus=0 or intstatus=1 Page 4 of 6

5 The easiest way for your handler to recognise this alternative intermediate 3D Secure response is by checking for an intstatus of 2 (rather than 0 or 1 used in authorisation responses). In such cases a strtranstype of S3DVALIDATE is also returned. Figure 3: Additional 3D Secure Response Parameters Field Type(Size) Notes inttransid int(11) The MCPE unique identifier for this in-progress transaction. strsecuritytoken char(32) A secure identifier required in order to resume the transaction authorisation. strtranstype char(30) For an intermediate 3D Secure response, this field is always S3DVALIDATE. intstatus int(1) For an intermediate 3D Secure response, this is always 2 (card is enrolled) strs3durl blob (>1000) The authentication URL, to which the cardholder should be re-directed. strs3dtransid char(20) The MCPE unique identifier for this 3D Secure authentication. strs3drequest blob (>1000) The authentication request, passed to the issuer in the re-direct. strs3dmerchantdata blob (>1000) Aggregated merchant data which is passed through the authentication. These last three fields listed above are URL encoded base64 data in our response. Your handler would therefore need to decode them, and then POST the cardholder in the browser to the strs3durl, the authentication re-direct. The re-direct should send the contents of strs3drequest as a variable PaReq and contents of strs3dmerchantdata as a variable called MD. You should also send your own URL in TermUrl to which the customer should be returned. <form action="strs3durl" method="post"> <input type="hidden" name="pareq" value="strs3drequest"> <input type="hidden" name="md" value="strs3dmerchantdata"> <input type="hidden" name="termurl" value=" </form> When the cardholder completes (or exits) authentication with their card issuer (they have the option to skip it) they will be POSTed back to the TermUrl with a new value PaRes Res which contains the authentication response, and the MD MD value. Your integration simply needs to resume card authorisation via Freedom +IMA MCPE using references provided in the previous gateway response, along with a new transaction type and an encoded card scheme authentication response. strtranstype (the transaction type, in this case S3DAUTH) strs3dresponse (the response from the card issuer, returned to you as the value PaRes, left encoded) This second request to the PayPoint.net payment gateway will resume the original card authorisation request, with added 3D Secure protection as appropriate. Only cards failing 3D authentication will not be entitled to chargeback liability shift. Figure 4: 3D Secure Authorisation Resume Parameters Field Type(Size) Required? Notes intinstid int(6) Yes The MCPE unique identifier for the installation performing this transaction. fltapiversion float(2,1) Yes The version of MCPE you are using. Must be 1.4 or higher. inttransid int(11) Yes The MCPE unique identifier for the transaction that is to be resumed. strsecuritytoken char(32) Yes The value sent in the strsecuritytoken field of the Secure 3D response. strtranstype char(30) Yes To resume authorisation after 3D Secure, this field is always S3DAUTH. strs3dtransid char(20) Yes The MCPE unique identifier for the completed 3D Secure authentication. strs3dresponse blob (>1000) Yes The authentication response, returned with the cardholder to your domain. strs3dmerchantdata blob (>1000) Yes Aggregated merchant data which is passed through the authentication. When card authorisation is complete, the traditional payment response will be returned from the MCPE payment gateway, as detailed in Freedom +IMA MCPE integration guide. You use this response to provide confirmation & fulfillment. You can optionally receive a parameter str3dsresult in the authorisation response containing the decoded outcome of the 3D Secure check based on the your supplied strs3dresponse. See the Payment Request Response section of the MCPE guide. For your reference, the Merchant Extranet will also show clearly where transactions have been either completed with 3D Secure or where an attempt has been made to authenticate the customer or check if their card is enrolled. 4 Testing You may test extended 3D Secure integration via our traditional Freedom +IMA MCPE test mode. This is achieved by supplying inttestmode=1 and using a Visa with card number in your original authorisation request. Page 5 of 6

6 No enrolment check is performed (enrolment is assumed in order to test an ACS integration) and an S3DVALIDATE response is provided, containing an authentication redirect URL which passes the user to a simple PayPoint.net test page. Upon re-directing the test customer to the PayPoint.net ACS, you will be confronted by a form which rather than seeking to authenticate the test user, will invite you to select whether to simulate a successful or failed 3D authentication. In both cases the customer is returned to your server as part of a POST re-direct containing the return values required by your integration in order to resume authorisation via MCPE and complete the test transaction. This second request to the PayPoint.net payment gateway should also include inttestmode=1 once again (in addition to the authentication response and Merchant Data) in order that a full 3D Secure test transaction is simulated by our systems. Since the real 3D Secure service requires interaction directly with the card schemes, using valid cards, testing of live 3D Secure transactions is only possible once this service has been enabled by your acquirer (see Appendix A). Appendix A: Requesting & Setting Up 3D Secure To have 3D Secure enabled on an existing PayPoint.net account, simply contact either your dedicated Account Manager or the PayPoint.net Merchant Support team via the Support tab of your Merchant Extranet login, requesting this service. A request will be made to your acquirer to enable 3D Secure on all your existing Merchant Account(s) (unless otherwise specified). This process may take up to a week or more for the acquirer to complete, but often much less. For new Merchants, if applicable, the service can be enabled as part of the compliance process in obtaining your Merchant Account(s). Please select 3D Secure from product options during signup process for our Freedom +IMA service. Appendix B: Alternative 3D Secure Providers PayPoint.net strongly recommends our integrated 3D Secure service as it dramatically reduces time otherwise spent on a more complex integration with a third party, and removes the need for lengthy card-scheme Product Integration Testing. The PayPoint.net 3D Secure service has passed Visa and MasterCard testing and is approved by both. It is also already certified for use through our acquirers. Any other solution would require several months testing before an acquirer would accept it. However, for your reference the following alternative service providers exist: GPayments ( Cardinal Commerce ( Modirum ( Trintech ( MPIware ( More providers can be found via: PayPoint.net cannot offer any support for integration involving third party 3D Secure solutions, but it is possible to request authorisation using the outcome of a 3D Secure authentication received from a third party service. Assuming the existence of arbitrary values returned from the third party following authentication, in this example format: ID (the 3D Secure Transaction ID) AVV (the Cardholder Authentication Verification Value (CAVV / AVV) generated for successful authentication) ECI (the Electronic Commerce Indicator; whether a card is registered for 3D, whether it was authenticated) The following additional values can be added to a Freedom +IMA MCPE authorisation request to complete payment based on a 3D Secure authentication attempt (whether occurred or not) carried out using a third party service. <input type="hidden" name="strs3dtransid" value="id"> <input type="hidden" name="strs3dauthvalue" value="avv"> <input type="hidden" name="ints3dindicator" value="eci"> Page 6 of 6