Visa Checkout September 2015

Transcription

1 Visa Checkout September 2015

2 TABLE OF CONTENTS 1 Introduction 1 Integration Flow 1 Visa Checkout Partner merchant API Flow 2 2 Asset placement and Usage 3 Visa Checkout Asset Placement and Usage Requirements 3 Use on Payment Pages 4 3 JavaScript and Button Reference 6 sdk.js JavaScript Library 6 V.init Event Handler 6 4 Fraud and Risk 8 Visa Checkout Fraud Checks 8 Risk Declines 9 AVS & CVV Responses Card Security Code Usage 9 5 Clickjacking Prevention Requirements 11 Checking for Hidden Layers using JavaScript 11 Using the X-Options Header 12 Testing Your Clickjacking Prevention Implementation Measures Example Server-Side Clickjacking Prevention Implementation13 Java Servlet 13 Tomcat Configuration 14 - ii -

3 6 Code Samples (Beanstream) 16 One-step Process (without requesting billing and shipping address) 16 Two-step Process (requesting billing and shipping address) 17 Step 1 17 Step Consumer Information 20 8 Visa checkout Keys 23 9 Get your Visa Checkout API keys 24 - iii -

4 1 INTRODUCTION Note: Visa Checkout is only available for Online Mart Merchants and Beanstream Merchants processing TD transactions. You need a merchant account with the Visa Checkout option enabled. Contact our support team at to activate the service before integrating. You can use Visa Checkout to integrate Visa s digital payment service with Beanstream s payment gateway. Visa Checkout is a digital payment service where consumers can store card information for Visa, MasterCard, Discover, and American Express. Visa Checkout provides quick integration for merchants to accept payments from these card holders. Visa Checkout leverages your existing environment because most websites already exist where Visa Checkout will be used. You add Visa Checkout buttons to existing pages and implement business and event logic using programming languages, tools, and techniques in the same way you currently do. This makes Visa Checkout flexible and imposes only a few requirements. Warning! You cannot have 3-D Secure and Visa Checkout activated at the same time for both Visa and MasterCard. Integration Flow When the lightbox is invoked, the communication is with Visa Checkout

5 Visa Checkout Partner merchant API Flow RELATED TOPICS Asset Placement and Usage JavaScript and Button Reference Fraud and Risk Clickjacking Prevention Code Samples (Beanstream) Consumer Information Visa Checkout API keys - 2 -

6 2 ASSET PLACEMENT AND USAGE You are required to implement the Visa Checkout branding requirements on all pages where the customer is presented with payment method options. You can use Visa Checkout on any page or in any flow on your site or app where a consumer is asked to enter their billing and payment information. For example, the Shopping Cart and Payment Form. However, your implementation depends on your specific flow. You must follow the Visa Checkout user interface guidelines, which are described in the Getting Started with Visa Checkout guide. Regardless of how the consumer arrives at a page with a Visa Checkout button, when a consumer clicks the button, the Visa Checkout lightbox appears and the consumer can either sign up to create an account, or sign in and make a payment. Visa Checkout Asset Placement and Usage Requirements These rules apply to the Visa Checkout button and acceptance mark: Do not change the functionality of these assets. Do not alter the size, shape, orientation, or any other aspect of the images. In the event an image is not sized properly, Visa will provide an alternative variation. Ensure buttons are placed on an equal level with other action items on the page, regardless of the orientation of the page. If the buttons are below the fold, it helps to place an additional button at the top of the page

7 Use on Payment Pages Payment pages are those where you accept a payment with the Visa Checkout button. These rules apply: Place the acceptance mark next to a selector, such as a radio button: - 4 -

8 When Visa Checkout is selected, display the Visa Checkout button and hide input fields for other payment methods, for example, the Next or Continue button. RELATED TOPICS Intro to Visa Checkout JavaScript and Button Reference Fraud and Risk Clickjacking Prevention Code Samples (Beanstream) Consumer Information Visa Checkout API keys - 5 -

9 3 JAVASCRIPT AND BUTTON REFERENCE sdk.js JavaScript Library Use the sdk.js JavaScript library to control the operation of Visa Checkout on your site. There is one version for sandbox testing and one for live: Platform URL Sandbox Live Example checkout-widget/resources/js/integration/v1/sdk.js <body>... <script type="text/javascript" src=" checkout-widget/resources/js/integration/v1/sdk.js"> </script> </body> V.init Event Handler Use the V.init event handler to specify a JSON object that contains initialization values for the Visa Checkout JavaScript library. Specify this Property: datalevel The level of consumer and payment information that the payment.success event response should include. If you request information, permission to receive full information must be configured in Visa Checkout; otherwise, you will always receive only summary information, regardless of the data level you specify. SUMMARY - Summary information (default) - 6 -

10 Lightbox Panel Configuration Example You can customize the appearance of lightbox panels, including the language, whether the confirmation button is Continue or Pay, and various messages and ornaments: V.init({... settings: { locale: "en_us", countrycode: "US", displayname: "MegaCorp", logourl: " websiteurl: " customersupporturl: " datalevel: "SUMMARY"... ); RELATED TOPICS Asset Placement and Usage Fraud and Risk Clickjacking Prevention Code Samples (Beanstream) Consumer Information Visa Checkout API keys Intro to Visa Checkout - 7 -

11 4 FRAUD AND RISK Visa Checkout uses a combination of proprietary and third-party technologies to implement fraud checks while processing transactions on your behalf. These checks provide account validations on all Visa Checkout accounts when the: Account is created or accessed. Customer logs in to Visa Checkout. Card is associated with the account, updated, or used in a transaction. Visa Checkout Fraud Checks Examples of fraud checks include device and IP data checks, velocity, address verification (AVS), and card number verification (CVN or CVV) results from the card issuer, enrollment attributes, Visa Checkout transaction history, and Visa internal fraud checks. Specifically, for every card added to a Visa Checkout account, regardless of card brand, Visa Checkout performs a validation procedure before passing the card information to a merchant. This validation procedure includes an AVS check (Address Verification) and a verification of the CVN or CVV number. A full or partial match is required for Address Verification and a match or unsupported response is required for CVN. Note: Although Visa Checkout performs many proprietary fraud checks while interacting with consumers, Visa Checkout never declines a transaction request based on risk concerns. Your own control models, processes, and procedures should provide the best protection against fraud, because you know your customers and their behaviour, and can assess the risk tolerance for a given transaction. Visa Checkout fraud checks should supplement your existing controls not replace them

12 4.1 Card Security Code Usage Risk Declines Risk declines are the responsibility of the card issuer and the merchant. Visa Checkout does not decline transactions at a transaction level, except in extreme circumstances. For example, when an account has been disabled due to suspicious activity or a government sanctions list match. AVS & CVV Responses Visa Checkout does not use the AVS or CVV code, however, if the merchant requires it, Visa Checkout will still process the transaction. 4.1 CARD SECURITY CODE USAGE Visa Checkout performs a verification of the Card Security Code for each card used for a Visa Checkout transaction or passed to a merchant for processing. Similar to a "card on file" scenario, the validation can be performed once, without re-verifying the Card Security Code during each use of the card. Note: Never collect a consumer's Card Security Code (CVV2, CVN, CVC2, CID), or other security feature for card not present transactions (separate from Visa s collection of the same with the Visa Checkout Services), unless you have Visa s express written consent to do so or the collection of the Card Security code is specifically required by Visa's Rules. You must never store Card Security Codes. You are encouraged to implement risk management best practices for Visa Checkout transactions as you would for any other e-commerce transaction. Because the Card Security Code has been validated for the Visa Checkout payment method being used, a historical match response should be assumed. Currently, card brands supported by Visa Checkout do not downgrade interchange based on the absence of a Card Security Code for "card not present" transactions. You should check with your acquirer or processor to determine whether they have any policies or fees specific to your contract, related to authorizations that do not contain a Card Security Code

13 4.1 Card Security Code Usage Typically, the Card Security Code in a response is optional information that can be included in a re-presentment. However, whether a Card Security Code is required to reverse a particular chargeback may depend on the card brand. Merchants are encouraged to speak directly with their acquirer to understand the chargeback re-presentment rules and reversal criteria for a specific card brand. RELATED TOPICS JavaScript and Button Reference Asset Placement and Usage Clickjacking Prevention Code Samples (Beanstream) Consumer Information Visa Checkout API keys Intro to Visa Checkout

14 5 CLICKJACKING PREVENTION REQUIREMENTS You must provide code on each page that hosts a Visa Checkout button (light box) and headers on your server to prevent clickjacking. This can occur if malicious code is hidden beneath legitimate buttons or other clickable content on your web page. For example, malicious code might monitor keystrokes and steal confidential information. Customers could be clickjacked when clicking a legitimate link on an infected page where there are buttons on a transparent layer they cannot see. Visa Checkout periodically reviews each page where a Visa Checkout button is clicked, to determine if there are adequate anti-clickjacking preventions. To prevent clickjacking, you must ensure that pages cannot be loaded as an iframe of some other page. Specifically, you must: Ensure that the associated DOM document for the page has no child pages in which malicious code could reside. Implement X-FRAME-OPTIONS DENY or X-FRAME-OPTIONS SAMEORIGIN filtering for headers. Checking for Hidden Layers using JavaScript Pages must contain JavaScript to verify there are no transparent layers where malicious code could reside. <head>... <style id= anticlickjack >body{display:none;}</style> <script type= text/javascript > if (self === top) { var anticlickjack = document.getelementbyid( anti- Clickjack ); anticlickjack.parentnode.removechild(anti- Clickjack); } else { top.location = self.location; } </script>... </head>

15 Using the X-Options Header Messages directed at your pages must include an X-FRAME-OPTIONS header to verify the response is known to be from your web application: X-FRAME-OPTIONS DENY Prevents anything from framing your page. SAMEORIGIN Prevents anything except your application from framing your page. Testing Your Clickjacking Prevention Implementation Measures As a best practice, to test your clickjacking prevention measures, you should automate these steps so the script is run whenever you change or add a page to your site. Note: These steps assume your site is not already in an iframe. 1. Install or use a test server that is not being used for your production or sandbox site and does not contain the pages you want to test. For example, you can test using Tomcat on localhost: Create a page on your test server that loads the page containing the Visa Checkout button in an iframe. <html> <body> <iframe src=" width=100% height=100%> <p>your browser does not support iframes.</p> </iframe> </body> </html> 3. Test the page you created to load your actual page in an iframe. Your test page should either be blank or display a message, such as The content cannot be displayed in a frame. If you can see the page that contains the Visa Checkout button, your prevention measures are not sufficient

16 5.1 Example Server-Side Clickjacking Prevention Implementation 5.1 EXAMPLE SERVER-SIDE CLICKJACKING PREVENTION IMPLEMENTATION This example shows how to implement X-FRAME-OPTIONS DENY or X- FRAME-OPTIONS SAMEORIGIN headers as a filter, in a Java servlet for pages served by Tomcat: Java Servlet package com.your_package.filters; import java.io.ioexception; import javax.servlet.filter; import javax.servlet.filterchain; import javax.servlet.filterconfig; import javax.servlet.servletexception; import javax.servlet.servletrequest; import javax.servlet.servletresponse; import javax.servlet.http.httpservletresponse; public class ClickjackFilter implements Filter { private String mode = DENY ; public void dofilter(servletrequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletResponse res = (HttpServletResponse) response; res.addheader( X-FRAME-OPTIONS, mode ); chain.- dofilter(request, response); } public void destroy() { } public void init(filterconfig filterconfig) { String configmode = filterconfig.getinitparameter ( mode ); if ( configmode!= null ) { mode = configmode; } } }

17 5.1 Example Server-Side Clickjacking Prevention Implementation Tomcat Configuration Add the filter definition and mapping to your web application's web.xmlfile. Set up the mapping so that it applies to any page that hosts the Visa Checkout button: <?xml version= 1.0 encoding= UTF-8?> <web-app id= WebApp_ID version= 2.4 xmlnss= xmlns:xsi= xsi:schemalocation= web-app_2_4.xsd > <display-name>clickjackfilter</display-name> <filter> <filter-name>clickjackfilterdeny</filter-name> <filter-class>com.merchant.filters.clickjackfilter</filter-class> <init-param> <param-name>mode</param-name> <param-value>deny</param-value> </init-param> </filter> <filter> <filter-name>clickjackfiltersameorigin</filter-name> <filter-class>com.merchant.filters.clickjackfilter</filter-class> <init-param> <param-name>mode</param-name> <param-value>sameorigin</param-value> </init-param> </filter> <!--Use either the Deny or SameOrigin version. Do not use both versions at the same time.--> <!--Use the Deny version to prevent everything, including your webapp, from framing the page.--> <filter-mapping> <filter-name>clickjackfilterdeny</filter-name>

18 5.1 Example Server-Side Clickjacking Prevention Implementation <url-pattern>/*</url-pattern> </filter-mapping> <! -Use SameOrigin to prevent everything, excepting your webapp, from framing the page.--> <!-- <filter-mapping> <filter-name>clickjackfiltersameorigin</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> --> </web-app> RELATED TOPICS Fraud and Risk JavaScript and Button Reference Asset Placement and Usage Code Samples (Beanstream) Consumer Information Visa Checkout API keys Intro to Visa Checkout

19 6 CODE SAMPLES (BEANSTREAM) One-step Process (without requesting billing and shipping address) The customer browses the merchant's website and navigates to an order payment page where they click the Visa Checkout button. First Request URL: https// transaction.asp The request is the same as a regular transaction request, except these two parameters are required: Parameter Name Data Type Remarks visacheckoutcallid String Payment request transaction ID Format: Alphanumeric (max 48 characters) Example: "callid":"..." merchant_id Integer Beanstream merchant ID Example POST transaction.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded requesttype=sts&visacheckoutcallid= &merchant_ id= &trnamount=100&trnordernumber123456&r ef1=test

20 First Response A regular approval or declined response message. Beanstream verifies the card is Visa Checkout-enabled and then responds with a JavaScript redirection response message. Example HTTP/ OK Content-Type: text/html trnstatus=1&trnid= &trnordernumber=abc &trnAuthCode=XyzWde&rspId=1&rspMessage=Appr oved&avsprocessed=0&avsid=0&avsresult=0&avsaddrma tch=0&avspostalmatch=0&avsmessage=address+verific ation+not+performed+for+this+transaction%2e&ref1= &ref2=&ref3=&ref4=&ref5=&trntype=p&paymentmethod= CC&trnDate=5%2F2%2F2014+5%3A10%3A28+PM&httpStatus Code=200&errorCategory=1&cardType=VI&cardLastFour =1111 Two-step Process (requesting billing and shipping address) Step 1 First Request Retrieve billing and shipping address for the customer. URL: transaction_info.asp Parameter Name Data Type Remarks visacheckoutcallid String Payment request transaction ID Format: Alphanumeric (max 48 characters) Example: "callid":"..." merchant_id Integer Beanstream merchant ID Example

21 POST transaction_info.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded requesttype=sts&visacheckoutcallid= &merchant_id= First Response Billing and shipping address. Example HTTP/ OK Content-Type: text/html Step 2 responsetype=i&visacheckoutcallid= &cardLastFour=1234&trnCardOwner=John Doe&ordName=John Doe&ordAddress1=123 Main St&ordAddress2=&ordCity=Victoria&ordProvince=BC&o rdcountry=ca&ordpostalcode=v9y7n8&ordphonenumber= &ord Address=johndoe@beanstream.com &shipname=john &shipaddress1=123 Main St&shipAddress2=&shipCity=Victoria&shipProvince=B C&shipCountry=CA&shipPostalCode=V9Y7N8&shipPhoneN umber= Second Request Process the transaction. The user's Visa Checkout address information is used since we do not allow the user to update their address on the payment form. URL: https// transaction_auth.asp Parameter Name Data Type Remarks payformparams String URL Encoded form

22 Parameter Name Example Data Type Remarks querystring values POST transaction_auth.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded payformparams=requesttype%3dsts%26merchant_ id%3d %26trnordernumber%3d1234%26trnamoun t%3d11.00%26username%3dtest1234%26password%3test1 234%26visaCheckoutCallID%3D %26 ref1%3dtesting Second Response A regular approval or declined response message. Example HTTP/ OK Content-Type: text/html trnstatus=1&trnid= &trnordernumber=abc &trnAuthCode=XyzWde&rspId=1&rspMessage=Appr oved&avsprocessed=0&avsid=0&avsresult=0&avsaddrma tch=0&avspostalmatch=0&avsmessage=address+verific ation+not+performed+for+this+ transaction%2e&ref1=&ref2=&ref3=&ref4=&ref5=&trnt ype=p&paymentmethod=cc&trndate=5%2f2%2f2014+5%3a1 0%3A28+PM&httpStatusCode=200&errorCategory=1&card Type=VI&cardLastFour=

23 7 CONSUMER INFORMATION Consumer information is returned in JSON format. Consider using standard libraries to parse JSON objects. Don't rely on the position of structures or fields as fixed, as they may not be returned. In these tables, consumer information is available, either encrypted in a payload, or as summary information from Get Payment Data: Payment Instrument Properties (paymentinstrument) Property lastfourdigits billingaddress nameoncard expirationdate Description Last 4 digits of the payment instrument Format: Numeric (maximum 4 characters) Example: "lastfourdigits" : "4448" Payment instrument Billing address Name of the consumer on the card Format: Alpha or these special characters: spaces, ' (single quote), ` (backtick), ~ (tilde), " (double quote),. (period), - (hyphen) (max 256 characters) Example: "nameoncard" : "John Tester" Payment instrument's expiration date Address (shippingaddress) Property line1 line2 line3 city Description First line of the address Format: Alphanumeric (maximum 140 characters) Example: "line1" : "1 Main Street" Second line of the address Format: Alphanumeric (maximum 140 characters) Example: "line2" : "..." Third line of the address Format: Alphanumeric (maximum 140 characters) Example: "line3" : "..." City associated with the address Format: Alphanumeric (maximum 100 characters) Example: "city" : "Victoria"

24 stateprovincecode State or province code associated with the address. Must be a valid 2-character code for US and CA and a valid 3-character code for AU Format: Alphanumeric (maximum 100 characters) Example: "stateprovincecode" : "BC" postalcode countrycode Expiration Date (expirationdate) Postal or zip code associated with the address Format: Depends on stateprovincecode (maximum 100 characters) US 5 digits CA 6 characters separated by a space or a hyphen, e.g. A0A 0A0 AU 4 digits NZ 4 digits Other postal codes must be valid for their countries, if a code exists. Example: "postalcode" : "V5G 8H8" Country code associated with the address Format: An ISO alpha-2 standard code, such as US or CA Example: "countrycode" : "CA" Property month year Description Expiration month of the payment instrument Format: The month in MM format, including leading 0 if necessary; from 01 to 12, inclusive Example: "month" : "09" Expiration year of the payment instrument Format: The year in YYYY format Example: "year" : "2015" RELATED TOPICS Clickjacking Prevention Fraud and Risk JavaScript and Button Reference Asset Placement and Usage Visa Checkout info

25 Visa Checkout API keys Code Samples (Beanstream)

26 8 VISA CHECKOUT KEYS If you want to use Visa Checkout functionality in the Process Trans API, you need to obtain Visa Checkout API keys. There are two keys, one for Live Production and the other is a Sandbox API Key used for testing. Make sure you are using the correct key for the type of processing you are doing. To obtain your Visa Checkout API keys: 1. On the menu, click administration> account settings> order settings. 2. Scroll down to the Visa Checkout section. 3. Use one of these Keys: Live API Key: Use this key only if you are Live, in production, and processing transactions. Sandbox API Key: Use this key if you are in testing mode. RELATED TOPICS Hosted Payment Solutions Intro to Visa Checkout

27 9 GET YOUR VISA CHECKOUT API KEYS If you want to use Visa Checkout functionality in the Process Trans API, you need to obtain Visa Checkout API keys. Warning! There are two keys, one for Live Production and the other is a Sandbox key for testing. Make sure you change the API key when you go from test mode to live mode, or from live mode to test mode. 1. On the menu, click administration> account settings> order settings. 2. Scroll down to the Visa Checkout section. 3. Use one of these Keys: Live API Key: Only if you are Live, in production, and processing transactions. Sandbox API Key: If you are in testing mode. For information about the API for Visa Checkout, See JavaScript and Button Reference. RELATED TOPICS Visa Checkout info Asset Placement and Usage JavaScript and Button Reference Fraud and Risk Consumer Information Clickjacking Prevention Code Samples (Beanstream)