Docs play_arrow Visa Checkout

Visa Checkout Documentation

Ready to start coding?

Things to Know

Visa Checkout is currently available in the following countries: Argentina, Australia, Brazil, Canada, China, Chile, Columbia, France, Hong Kong, India, Ireland, Malaysia, Mexico, New Zealand, Peru, Poland, Singapore, South Africa, United Arab Emirates, United Kingdom and the United States.

Visa Checkout currently supports Visa, MasterCard, American Express and Discover. 

Service Activation Requirements

You can get a test Client ID and test data from the Project Console for testing your integration with Visa Checkout in the sandbox. To use Visa Checkout in production, you must apply and be approved for a Visa Checkout Merchant Services account. (Contact for more information or to begin the production onboarding process.

Working with the Processor or PSP

If you are using an acquirer processor or a payment service provider (PSP) to process your payments, your integration with Visa Checkout will depend on the requirements of your processor. Generally, your processor will want you to provide either the decrypted values from the consumer information payload or will accept the entire encrypted or decrypted payload. You must update Visa Checkout with the transaction processing status provided by your processor unless your processor does it for you.

Creating a Partner Relationship

In addition to working with a processor or PSP,  you can create a relationship with a Visa Checkout partner, granting the partner access to manage Visa Checkout on your behalf. These partners have already integrated with Visa Checkout and, depending on your needs, can provide integration and operational expertise to access and manage your Visa Checkout configuration and/or handle transactions for you. You will want to check the services and capabilities that partner solutions can provide, as offerings vary; for more information, see Visa Checkout Partners. To create a relationship with a Visa Checkout partner, sign into the Visa Developer Center portal and select your project from the Dashboard, then choose Relationships. Note that you can delete a relationship at any time. Partners, likewise, can reject or delete the relationship.

Security and Authentication Requirements

The Visa Checkout APIs require an API Key and a Shared Secret for authentication (sometimes referred to as an “x-pay-token” header). Test credentials can be obtained online in the Project Console for sandbox testing. Production credentials will be supplied to you as part of the production on-boarding process. (See Working with Visa APIs > x-pay-token to get detailed instructions for obtaining and using an x-pay-token.)

These browsers are recommended for use with Visa Checkout:

  • Internet Explorer, version 11 or later. Note: Do not use the compatibility setting; specifically, do not use it to specify a version less than IE 11 (e.g. do not specify x-ua-compatible=IExx where xx is less than 11 in your pages).
  • Firefox, current version through 10 versions prior
  • Chrome, current version through 10 versions prior (except beta versions)
  • Safari, version S6 or later
  • iOS, version 6 or later
  • Android, version 4 or later

Other browsers may be acceptable; however, the HTML pages that contain a Visa Checkout button must support TLS 1.2 and be compatible with HTML 4.01 or higher (including XHTML 1.0 and above). Typically, you specify the HTML version in the DOCTYPE declaration for version 4.x as follows: <!DOCTYPE html …>. HTML 5 does not require explicit version numbers.


The following table lists the regional availability for Visa Checkout. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Visa Checkout
Product Name Availability Notes
Visa Checkout Available in Australia, China, Hong Kong, India, Malaysia, New Zealand, Singapore
Product Name Availability Notes
Visa Checkout Available in France, Ireland, Poland, Spain, United Kingdom
Product Name Availability Notes
Visa Checkout Available in Kuwait, Qatar, Saudi Arabia, South Africa, Ukraine, United Arab Emirates
Product Name Availability Notes
Visa Checkout Available in Argentina, Brazil, Chile, Colombia, Mexico, Peru

Getting Started

Visa Checkout provides a single sign-in service to pay for online shopping purchases. After a simple setup, Visa Checkout users can skip entering their payment and shipping information for their orders. Whether at home or on the go, Visa Checkout works across multiple devices so online shopping stays easy. Visa Checkout enables shoppers to choose their preferred payment method across multiple retailers with a click of a button.

Checking out and paying with Visa Checkout begins when your customer clicks on the Visa Checkout button that has been placed on your shopping cart or payment page. The pages which you place a Visa Checkout button on must load the Visa Checkout JavaScript library so that it can send an initialization event when the page is loaded. Your page will respond to this initialization event by setting characteristics that will define the way you want the lightbox to appear and operate and how you want payment requests handled.

When your customer clicks the Visa Checkout button, the Visa Checkout lightbox appears, allowing the consumer to sign in and make a payment or first create a new account and then make a payment. After signing in to Visa Checkout, the consumer can change the payment method and if enabled, they can change the shipping address. When the consumer finishes and the lightbox closes (or an error occurs), Visa Checkout will send your page a payment event that includes status information and a call ID that you can use to identify the payment request.

Visa Checkout offers several options for handling the consumer payment information returned by the payment event and for updating Visa Checkout with the payment processing results. For example, you can:

  • Take action from your web page or front-end server 
  • Call a Visa Checkout API from either a front-end or back-end server 
  • Pass the call ID to your processor or your payment service provider to handle on your behalf

Getting Started with Visa Checkout in Three Steps

The simplest approach to integrating Visa Checkout takes three steps and can be done entirely from your web page (with the exception of decrypting the consumer information payload on a secure server). The following infographic, illustrates the main steps for getting started with Visa Checkout.

Getting Started

  1. Place a Visa Checkout button on your web page and include the necessary JavaScript to handle events associated with the button.
  2. Handle the payment event returned by Visa Checkout by decrypting the consumer information payload.
  3. Update Visa Checkout with the final payment information after the payment has been processed.

All integration options require that you perform step 1. There are several approaches to performing steps 2 and 3 and each is described in other sections of this page.

How Does it Work?

Online shopping with Visa Checkout takes only five simple steps.

  1. On your shopping cart or payment page, your customer selects Visa Checkout as their payment method. Visa securely serves up the Visa Checkout Payment Widget and loads it over your web page.
  2. Your customer is then prompted to sign in to their Visa Checkout account or create a new Visa Checkout account before proceeding.
  3. Your customer reviews their payment information within the Visa Checkout Payment Widget, makes any changes they want to their payment instrument or shipping information, and clicks the Continue or Pay button to send their information to you.
  4. Control of the order is returned to your website and your customer submits their order.
  5. You confirm the final purchase details to Visa Checkout when you display the Thank You or Order Confirmation page in your check out flow.

Note: To integrate to Visa Checkout, use the JavaScript SDK and Visa Checkout Mobile SDKs. There’s no need to make any API calls to implement the Visa Checkout service. For details on how to get started with Visa Checkout, refer to Getting Started section of this page. If you are interested in Visa Checkout APIs, send an email to

Why Use It?


Visa Checkout uses multiple layers of security, including fraud monitoring systems and encrypted tokens using SHA256 hash algorithms, to help keep payment information safe.


Visa Checkout accepts most major credit or debit cards so customers can checkout easily and securely using the payment method they use today on your site.


Integrating Visa Checkout is easy and requires only a few simple HTML and JavaScript tags. Quickly and easily test your setup in our sandbox environment.


Join a growing community of commerce developers and get the support you need.

Integration Methods

JavaScript SDK

The JavaScript SDK provides functionality to handle events to generate payment buttons and initiate checkout.

Visa Checkout Mobile SDKs

Offer Visa Checkout as a payment method in native iOS and Android applications.

Adding Visa Checkout to Your Web Page

The first piece of any integration effort is placing a Visa Checkout button on your shopping cart or payment pages.

Note: The page you add a Visa Checkout button to must be hosted on a web server for the lightbox and JavaScript library to perform properly.

Step One: Add the onVisaCheckoutReady JavaScript function to the <head> and include the V.init event handler with your API key. The V.init event handler lets you specify initialization values that control the appearance and behavior of the lightbox and the contents of the payment request that will be presented to the consumer. For example:

  <script type="text/javascript">
    function onVisaCheckoutReady (){
    V.init({ apikey: "..."});

You can go back later and specify your logo and other settings to customize the appearance of the Visa Checkout lightbox. (For more details, refer to Visa Checkout Integration Guide.)

Step Two: Inside V.init, you also need to specify the amount and currency of the consumer’s payment request in the paymentRequest properties. For example:

     currencyCode: "USD",
     subtotal: "11.00"

This is the simplest payment request you can implement. Using other paymentRequest properties, you can also specify amounts for tax, discounts and shipping, which will be shown to the consumer in the lightbox or, if you don’t have all that information in advance, you can include these amounts in the payment update after the lightbox closes. (For more details, refer to Visa Checkout Integration Guide.)

Step Three: Add V.on event handlers, one for each of the three possible payment events: payment.success (the consumer agreed to the payment request), payment.cancel (the consumer cancelled the payment request), or payment.error (an error occurred).

V.on("payment.success", function(payment) {alert(JSON.stringify(payment)); });
V.on("payment.cancel", function(payment) {alert(JSON.stringify(payment)); });
V.on("payment.error", function(payment,error) {alert(JSON.stringify(error));});

In addition to the Visa Checkout payment request ID (callId), Visa Checkout optionally returns the encrypted payload. (For more details about handling payment events and an encrypted payload, refer to Visa Checkout Integration Guide.)

Step Four: Place one or more Visa Checkout buttons in the body of the page. For example:

  <img alt="Visa Checkout" class="v-button" role="button"

You can define additional properties to the button (for example, such as size, color or card brands accepted). Note: Some of these additional properties may override those set in the V.init handler. (For more details, refer to Visa Checkout Integration Guide.)

Step Five: At the end of the body, load the Visa Checkout JavaScript library sdk.js. For example:

<script type="text/javascript"

After completing these steps, you should have a web page whose source looks like this:

 <script type="text/javascript">
  function onVisaCheckoutReady(){
  V.init( {
  apikey: "...",
    currencyCode: "USD",
    subtotal: "11.00"
V.on("payment.success", function(payment)
  {alert(JSON.stringify(payment)); });
V.on("payment.cancel", function(payment)
  {alert(JSON.stringify(payment)); });
V.on("payment.error", function(payment, error)
  {alert(JSON.stringify(error)); });

<img alt="Visa Checkout" class="v-button" role="button"
<script type="text/javascript"

When you are ready to begin testing your integration, you will need to create Visa Checkout consumer test accounts in the sandbox and add at least one payment method to them. You can start by creating your own test consumers when the Visa Checkout lightbox is opened. You will be shown an Add a New Payment Method screen in which you must enter a card number.

Note: You can enter any values on this screen which make sense to you, except that you must use one of the following card numbers. The name on card, expiration date and security code are not validated in the sandbox, so you can enter any valid value. Because card numbers are validated by Visa Checkout on entry, you should only use these numbers for sandbox testing.

Visa: 4005520201264821

MasterCard: 5500005555555559

American Express: 340353278080900

Discover: 6011003179988686

Adding Visa Checkout to a Mobile Application

The Visa Checkout Mobile SDKs allow merchants to quickly build and implement a native and hybrid checkout application for iOS or Android-enabled devices. Visa Checkout enabled within a mobile application allows consumers to seamlessly and securely complete purchases on the go when using their iPhones or Android devices.

In addition to offering consumers Visa Checkout within a mobile application, the mobile SDKs have features that take advantage of device functionality, which includes:

  • Platform-optimized, fast user experience tailored to Android and iOS guidelines
  • Location-based and Address Book services to prefill area code, city or country fields for ship-to addresses
  • Merchant-passed contact and address information for returning customers

The Visa Checkout Mobile SDK files and related documentation can be downloaded using the links below. While each SDK provides the same kind of tools, the actual integration methodology depends on the platform. (See the respective SDK for detailed information.) 





Visa Checkout SDK for iOS

Programmer's guide, libraries and sample application for Visa Checkout Mobile SDK for iOS compatible with XCode 9.0 and later

Note: The iOS SDK is light weight and supports both native and hybrid integration.    


October, 2018

Visa Checkout SDK for Android

Visa Checkout Mobile SDK for Android, including programmer's guide, libraries and sample application

Note: The Android SDK is light weight and supports both native and hybrid integration.    


October, 2018

User Interface Guidelines

Your implementation of Visa Checkout must meet the Visa Checkout branding requirements, which address the appearance and placement of the Visa Checkout button, the appearance and placement of the Visa Checkout Acceptance Mark, and the Tell Me More Link. You are required to implement the Visa Checkout branding requirements on all pages where you are displaying Visa Checkout digital assets: either the Visa Checkout Button or the Visa Checkout Acceptance Mark.

Use the Visa Checkout Acceptance Mark to let your consumers know that you accept Visa Checkout. Place it on pages such as your shopping cart page, login page, product page, and/or payment page. Place the Visa Checkout button on any page or in any flow on your web site or mobile application where a consumer is asked to type in their billing and payment information. Common examples include shopping cart pages, payment pages, card-on-file management pages, or immediately before a flow wherein a consumer is prompted for the type of personal information that could be obtained from a Visa Checkout account.

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 (except through the use of the V.init properties).
    Note: In the event that an image is not sized properly, Visa will give you an alternate version.
  • Ensure that the buttons are placed on an equal level with other calls to action on the page, regardless of the page orientation.
    Note: If the buttons are below the fold, it helps to place an additional button at the top of the page.

Visa Checkout Buttons

There are three styles of Visa Checkout buttons that you can choose to add. For instance, refer to the following choices.

  • Standard button without card art
  • Neutral button without card art
  • Standard button with card art

Ways to specify the style can be found in Customizing the Button. Make sure to use the standard button unless the background colors on your site are dark. If this is the case, consider using the neutral button, in order to provide greater contrast.

Checkout Button Standard

Standard button without card art

Checkout Button Neutral

Neutral button without card art

Checkout Button Standard with Card Art

Standard button with card art

You can use either a horizontal or stacked implementation of the Visa Checkout button, placing an "or" in between the payment options to emphasize which choice the consumer can make. Refer to the following example to get a better understanding of how you can visually set this up on your page. 

If you offer guest checkout, a best practice is to prefill any account creation form you may have with the consumer information provided by Visa Checkout after the lightbox closes. If you require the consumer to sign in to your site, another best practice is to link the consumer’s Visa Checkout account to the consumer’s account on your site, so that the consumer does not have to login multiple times to check out. By linking accounts, you can recognize the consumer’s account on your site based on the consumer’s successful sign in to Visa Checkout.

Diagrams of Visa Checkout Acceptance Marks

You are required to implement the Visa Checkout branding requirements on all pages where the consumer is presented payment method options, such as Visa Checkout or another payment method. Common examples include the shopping cart page, login page, product page and payment page. Your actual implementation depends on your specific flow.

General Visa Checkout Button Placement and Flow Requirements

You can use Visa Checkout on any page or in any flow on your site or app where a consumer is asked to type in their billing and payment information. The most common examples include:

  • cart pages (both mini and full) pages 
  • payment pages
  • card-on-file management pages

An exception would be if you needed to add the Visa Checkout information immediately before a flow where a consumer is prompted for specific personal information. This data may be available, at least partially within Visa Checkout.

Because Visa Checkout already has consumer shipping information and payment options, giving consumers the opportunity to specify these kinds of choices at the beginning of the checkout process may enable them to complete the transaction with less effort than might otherwise be required. The following diagram shows how placing Visa Checkout buttons on the shopping cart page and your log in page might work.

Initially, if consumers do not click the Visa Checkout button—they should also have the option to choose a payment method which enables them to use Visa Checkout for payment. For instance, refer to the following kinds of examples.

The implementation shown above shows a radio button with a Visa acceptance mark. When the consumer chooses the Visa Checkout radio button, the Visa Checkout button appears. This gives the consumer the ability to log into Visa Checkout to choose the card and continue to the payment page.

Visa Checkout Acceptance Mark Requirements

Use the Visa Checkout acceptance mark to let consumers know you accept Visa Checkout on your pages, such as on your payment pages and other pages that display a payment method. If you no longer accept Visa Checkout, or temporarily disable Visa Checkout, please use the disabled acceptance marks. Visa Checkout provides 4 sizes of marks, which are identified in the table below. You can choose the size, color and background based on the needs of your site. Make sure to link to the Visa Checkout acceptance mark. The tables below display all of the available acceptance marks with the links hyperlinked to the image.

Note: Click on the image for the corresponding URL. 

Size White on Blue (wht01) Blue (blu01)  Blue on Neutral (blu02) White (wht02)




Size Disabled with Background (01) Disabled without Background (02)

The Visa Checkout acceptance marks are dynamic, meaning the acceptance mark will display an image of the customer's default issuer card art with Visa Checkout. The kinds of acceptance marks that are dynamic are versions blue 01, blue 02, white 01 and white 02 in sizes 40x31, 49x31 and 99x34. To ensure that the acceptance marks on your site are dynamic, work with your Visa representative or integrate your site with the proper URL's from the table above. 

Example of a standard versus dynamic acceptance mark 

Do not create your own acceptance marks. Only use them through the associated URL, which is provided by Visa Checkout. The base URL is It is followed by the .png graphic. For example, acc_99x34_wht01.png. The complete URL is:

Disabled acceptance marks use a different URL schema.

The following rules are specific to applying the Visa Checkout acceptance mark on a page.

  • Add Visa Checkout as the alternative (alt) text for the image.
  • The Visa Checkout acceptance mark is not a substitute for the Visa brand mark.
  • If the pay layout cannot accommodate the acceptance mark, you can use the full Visa Checkout text instead. 
  • The Visa Checkout acceptance mark is not a substitute for the Visa brand mark.

Tell Me More Link

The following example shows how you should include the Tell Me More link along with a Visa Checkout button.

When the consumer clicks the link, a popup window appears which explains the use and benefits of the Visa Checkout button.

 The Tell Me More link does not appear on mobile devices.

PDFs for Merchants Integrating with Visa Checkout

The following table lists the Visa Checkout integration documentation for merchants:

Title Description Current
Visa Checkout Getting Started Provides a Quick Start tutorial and branding requirements 6.7 October 31, 2018
Visa Checkout Integration Guide Provides complete information for web integration using JavaScript and APIs 6.7 October 31, 2018
Visa Checkout Consolidated Release Notes Contains release notes by version in reverse chronological order 6.7 October 31, 2018
Visa Checkout Address Formats by Country Provides complete billing and shipping address information by country 6.5 October 31, 2018

Become a Partner

A partner provides services on behalf of a merchant. Partners typically onboard the merchant and own the relationship with their merchants, although once a partner has been registered with Visa Checkout, merchants can choose the partner directly. A partner must enable a merchant to accept the Visa Checkout Merchant Services Agreement during onboarding; Visa Checkout makes this step easy. Once the partner-merchant-Visa Checkout relationship has been established, direct interactions are between the partner and the merchant, not between Visa Checkout and the merchant.

Partner integrations with Visa Checkout are similar to merchant integrations, with the addition that partners must specify the merchant on whose behalf they are acting. Partners also decide the division of integration effort between themselves and their merchants. Partners can integrate by simply onboarding merchants, in which case the merchant handles the bulk of the integration, to hosting a complete Visa Checkout solution, in which requires virtually no integration effort by the merchant.

If you would like to work with Visa Checkout as a partner, send email to and request further information. You should be prepared to provide company and contact information, a valid business identification ID, such as a tax ID, and an estimate of anticipated transaction volume (monetary value).