Visa Checkout September 2015

(1)

Visa Checkout

(2)

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 1.888.472.0811 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

(5)

Visa Checkout Partner merchant API Flow

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 theGetting Started with Visa Checkoutguide. 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:

l Do not change the functionality of these assets.

l 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.

l 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:

l Place the acceptance mark next to a selector, such as a radio

(8)

l 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.

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 https://sandbox-assets.secure.checkout.visa.com/ checkout-widget/resources/js/integration/v1/sdk.js Live https://assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js Example <body> ... <script type="text/javascript" src="https://sandbox-assets.secure.checkout.visa.com/ 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.

(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: "www.Some_Image_URL.gif", websiteUrl: "www.MegaCorp.com", customerSupportUrl: "www.MegaCorp.support.com", ... dataLevel: "SUMMARY" ... );

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:

l Account is created or accessed. l Customer logs in to Visa Checkout.

l 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)

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 forcard 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 4.1 Card Security Code Usage

(13)

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.

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 beclickjackedwhen 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:

l Ensure that the associated DOM document for the page has no child

pages in which malicious code could reside.

l 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> ...

var antiClickjack = document.getElementById(“anti-Clickjack”); antiClickjack.parentNode.removeChild(anti-Clickjack);

(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:8080.

2. Create a page on your test server that loads the page containing the Visa Checkout button in an iFrame.

<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

(16)

5.1 EXAMPLE SERVER-SIDE CLICKJACKING PREVENTION

IMPLEMENTATION

This example shows how to implement 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.IOEx-ception;

import javax.servlet.Filter; import javax.servlet.FilterChain;

import javax.servlet.FilterConfig; import vlet.ServletException; import

javax.ser-vlet.ServletRequest; import

javax.servlet.ServletResponse; import javax.ser-vlet.http.HttpServletResponse;

public class ClickjackFilter implements Filter {

private String mode = “DENY”;

public void doFilter(ServletRequest request, Ser-vletResponse response, FilterChain chain) throws IOEx-ception, ServletException {

HttpServletResponse res = (HttpServletResponse) response; res.addHeader(“X-FRAME-OPTIONS”, mode ); chain.-doFilter(request, response);

}

public void destroy() { }

public void init(FilterConfig filterConfig) {

(17)

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” xmlns-s=”http://java.sun.com/xml/ns/j2ee” xmlns:x-si=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ 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>

<filter-mapping>

<filter-name>ClickjackFilterDeny</filter-name>

(18)

<url-pattern>/*</url-pattern> </filter-mapping>

<!–-Use SameOrigin to prevent everything, excepting your webapp, from framing the page.-->

</web-app>

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//www.beanstream.com/scripts/process_ transaction.asp

The request is the same as aregular 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 https:/www.beanstream.com/scripts/process_ transaction.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded requestType=STS&visaCheckoutCallID=69760195451706 08991&merchant_ id=987654321&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/1.1 200 OK Content-Type: text/html trnStatus=1&trnId=10000000&trnOrderNumber=ABC1234 567890&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:https://www.beanstream.com/scripts/process_ transaction_info.asp

visaCheckoutCallID String Payment request transaction ID

(21)

POST https:/www.beanstream.com/scripts/process_ transaction_info.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded requestType=STS&visaCheckoutCallID=69760195451706 08991&merchant_id=987654321 First Response

Billing and shipping address. Example

HTTP/1.1 200 OK

Content-Type: text/html

responseType=I&visaCheckoutCallID=697601954517060 8991&cardLastFour=1234&trnCardOwner=John

Doe&ordName=John Doe&ordAddress1=123 Main

St&ordAddress2=&ordCity=Victoria&ordProvince=BC&o rdCountry=CA&ordPostalCode=V9Y7N8&ordPhoneNumber= 2501231234&[email protected] &shipName=John &shipAddress1=123 Main

St&shipAddress2=&shipCity=Victoria&shipProvince=B C&shipCountry=CA&shipPostalCode=V9Y7N8&shipPhoneN umber=2501231234

Step 2

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//www.beanstream.com/scripts/process_ transaction_auth.asp

(22)

Parameter Name Data Type Remarks querystring values Example POST https://www.beanstream.com/scripts/process_ transaction_auth.asp HTTP/1.1 Content-Type: application/x-www-form-urlencoded payFormParams=requestType%3DSTS%26merchant_ id%3D288320000%26trnOrderNumber%3D1234%26trnAmoun t%3D11.00%26username%3DTest1234%26password%3Test1 234%26visaCheckoutCallID%3D6976019545170608991%26 ref1%3DTesting Second Response

A regular approval or declined response message. Example HTTP/1.1 200 OK Content-Type: text/html trnStatus=1&trnId=10000000&trnOrderNumber=ABC1234 567890&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=1111

(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 Description

lastFourDigits Last 4 digits of the payment instrument Format: Numeric (maximum 4 characters) Example: "lastFourDigits" : "4448"

billingAddress Payment instrument Billing address nameOnCard 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"

expirationDate Payment instrument's expiration date Address (shippingAddress)

Property Description

line1 First line of the address

Format: Alphanumeric (maximum 140 characters) Example: "line1" : "1 Main Street"

line2 Second line of the address

Format: Alphanumeric (maximum 140 characters) Example: "line2" : "..."

line3 Third line of the address

Format: Alphanumeric (maximum 140 characters) Example: "line3" : "..."

city 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 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" countryCode Country code associated with the address

Format: An ISO-3166-1 alpha-2 standard code, such as US or CA

Example: "countryCode" : "CA" Expiration Date (expirationDate)

Property Description

month 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"

year Expiration year of the payment instrument Format: The year in YYYY format

Example: "year" : "2015"

(25)

Visa Checkout API keys

(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, clickadministration> account settings> order settings.

2. Scroll down to the Visa Checkoutsection. 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.

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, clickadministration> account settings> order settings.

2. Scroll down to the Visa Checkoutsection. 3. Use one of these Keys:

l Live API Key: Onlyif you are Live, in production, and

processing transactions.

l Sandbox API Key: If you are in testing mode.

For information about the API for Visa Checkout,See JavaScript and Button Reference.

Visa Checkout September 2015

Visa Checkout

TABLE OF CONTENTS

1 INTRODUCTION

RELATED TOPICS

2 ASSET PLACEMENT AND USAGE

RELATED TOPICS

3 JAVASCRIPT AND BUTTON REFERENCE

RELATED TOPICS

4 FRAUD AND RISK

4.1 CARD SECURITY CODE USAGE

RELATED TOPICS

5 CLICKJACKING PREVENTION REQUIREMENTS

5.1 EXAMPLE SERVER-SIDE CLICKJACKING PREVENTION

IMPLEMENTATION

RELATED TOPICS

6 CODE SAMPLES (BEANSTREAM)

7 CONSUMER INFORMATION

8 VISA CHECKOUT KEYS

RELATED TOPICS

9 GET YOUR VISA CHECKOUT API KEYS

RELATED TOPICS