BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Visa Checkout

Visa Checkout (now Click to Pay in the United States) is a digital wallet that securely stores a shopper's payment and shipping details. It supports all major credit and debit card types, including Visa, MasterCard, American Express, and Discover. Visa Checkout yields conversion rates that far exceed traditional checkout, and enables your customers to make fast and easy payments across all their devices.

📘

Note:

Visa Checkout is supported for both first time transactions and recurring transactions. Review the highlighted sections for detailed information.

BlueSnap supports Visa Checkout in both the Payment API and Extended Payment API.

Supported Markets

Visa Checkout is supported for shoppers and merchants in the following countries as a simple and secure payment method.

  • Argentina (AR)
  • Australia (AU)
  • Brazil (BR)
  • Canada (CA)
  • Chile (CL)
  • China (CN)
  • France (FR)
  • Hong Kong (HK)
  • Ireland (IE)
  • Malaysia (MY)
  • Mexico (MX)
  • New Zealand (NZ)
  • Peru (PE)
  • Poland (PL)
  • Singapore (SG)
  • South Africa (ZA)
  • Spain (ES)
  • United States (US) (as Click to Pay)
  • United Kingdom (GB)
  • United Arab Emirates (AE)

Shopper experience

1280

Visa Checkout and Click to Pay in the United States

Visa Checkout in the United States is changing to Click to Pay. For more information, refer to Click to Pay Checkout.

Implementing Visa Checkout

Step 1: Enable the Visa Checkout payment method

Follow these steps to enable the Visa Checkout payment method in your BlueSnap account:

  1. Log in to your account in the BlueSnap Merchant Portal.
  2. Go to Checkout Page > Payment Methods.
  3. Select Show next to Visa Checkout, and then click Submit.

Step 2: Add the Visa Checkout button and JS function to your checkout page

Add the Visa Checkout button and required JS library to your checkout page as shown below.
Note: As mentioned above, this Visa Checkout button is automatically replaced with the Click to Pay logo.

// Button image
<img alt="Visa Checkout" class="v-button" role="button" src="https://{environment}.secure.checkout.visa.com/wallet-services-web/xo/button.png" />

// Visa Checkout JS library
<script type="text/javascript" src="https://{environment}-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js"></script>

// Visa JS function that invokes the lightbox
<script>
function onVisaCheckoutReady() {
	V.init({
		apikey: ‘${apiKey}’,
    encryptionKey: ‘${encryptionKey}‘,
		settings: {
			locale: ‘${visaCheckoutLocale}’,
			displayName: ‘${displayName}’,	
			logoUrl: ‘${logoUrl}’,
		},
		payment: {
		      cardBrands: ["VISA","MASTERCARD","AMEX","DINERS","DISCOVER"]
		},		
		paymentRequest: {
			currencyCode: ‘${currency}’,
			subtotal: ‘${CheckoutSubtotal}’,
		},
		shipping: {
			collectShipping: ‘${collectShipping}’,
		},
		dataLevel: "NONE"
	});
	V.on("payment.success", function(payment) {
	// TODO: Handle success response from lightbox.
	// you should send “payment.callid” to BlueSnap via CreateWallet.
	});
	V.on("payment.cancel", function(payment) {
	// TODO: Handle cancel response from lightbox.
	});
	V.on("payment.error", function(payment, error) {
	// TODO: Handle error response from lightbox.
	});
}

</script>

Button Image

The image for the Visa Checkout button:
Sandbox: https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png
Production: https://secure.checkout.visa.com/wallet-services-web/xo/button.png

Visa Checkout JS Library

The JS library for Visa Checkout:
Sandbox: https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js
Production: https://assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js

Field Descriptions

The fields in the JS function above should be completed as follows:

  • apikey: (Required) Your Visa Checkout API key. This is a static value - you only need to create a single API key. For instructions, see Create/Retrieve Visa Checkout API Key.
  • encryptionKey: (Required) Your Visa Checkout encryption key. This is a static value - you only need to create a single encryption key. For instructions, see Create/Retrieve Visa Checkout API Key
  • displayName: (Optional) The merchant's name as it appears on the Review panel of the lightbox; typically, it is the name of your company. Format: Maximum 100 characters, either alphabetic, numeric, spaces, or the following characters: ! @ # $ % ^ & * -' ? and period ( . ).
  • logoUrl: (Optional) Secure (HTTPS) URL path to the logo to display in the Visa Checkout lightbox; otherwise, the default Visa Checkout logo appears. Your image must not exceed 174px wide and should be 34px high; oversize logos will be scaled to fit. Format: HTTPS URL; maximum 256 characters.
  • cardBrands: (Required) Card brands that are accepted by BlueSnap (already provided in the example above).
  • currencyCode: (Required) The currency with which to process the transaction. Format: ISO 4217 standard alpha-3.
  • subtotal: (Required) Subtotal of the payment. Format: Numeric; maximum 9 digits before an optional decimal point and 2 decimal digits. Example: "subtotal" : "9.00".
  • collectShipping: (Optional) Determines whether to obtain a shipping address from the consumer. Permitted values:
    • true: Collect shipping address (default)
    • false: Do not collect shipping address
  • dataLevel: (Required) Should be set to “NONE”.

📘

Visa Checkout Requirements

Visa Checkout Asset Placement and Usage Requirements

On all pages where the shopper is presented with the Visa Checkout payment method (for example, the shopping cart page or payment page), you are required to implement the Visa Checkout branding requirements.

Clickjacking Prevention Requirement

You must provide code on each page that hosts a Visa Checkout button and headers on your server to prevent clickjacking, which could 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 in which there are actually buttons on a transparent layer they cannot see. Visa Checkout periodically reviews each page from which a Visa Checkout button is clicked to determine if adequate anticlickjacking preventions have been taken. 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 on your server to prevent your page from being loaded from another domain.

Flow Description

  1. Shopper clicks on Visa Checkout button, which invokes the lightbox.
  2. Inside the lightbox, the shopper can choose their preferred payment option and shipping address.
  3. After the shopper completes the lightbox step, the response status will be “success”, “cancel” or “error”.
  4. You should handle each of those event types, as indicated in the onVisaCheckoutReady() function in the example above.
  5. On a “success” event, you should get a payment object populated with a callId, which is a unique value that points to the corresponding Visa Checkout resource. Extract this call ID and use it to complete Step 3, described below.

Back to Top

Step 3: Send the Create Wallet request to receive checkout information

After extracting the call ID from the payment object (see the Flow Description above), perform a Create Wallet request with the call ID.
This request should be sent to: services/2/wallets

Sample Create Wallet requests:

{
    "callId": 5549711876630985101,
    "walletType": "VISA_CHECKOUT"
}

<wallet xmlns="http://ws.plimus.com">
   <wallet-type>VISA_CHECKOUT</wallet-type>
   <store-id>16500</store-id>
   <call-id>5549711876630985101</call-id>
</wallet>

Upon success, you will receive a response similar to the following, with all checkout information. Note: you cannot perform two requests with the same call ID.

Sample Create Wallet response:

{
    "country": "us",
    "walletId": 2203,
    "firstName": "First",
    "lastName": "Last",
    "billingContactInfo": {
        "zip": 12324,
        "country": "us",
        "firstName": "First",
        "lastName": "Last",
        "city": "Santa Barbara",
        "address1": "BlueSnap Street",
        "state": "CA"
    },
    "phone": 5032541004,
    "shippingContactInfo": {
        "zip": 12324,
        "country": "us",
        "firstName": "First",
        "lastName": "Last",
        "city": "Santa Barbara",
        "phone": 5032541004,
        "address1": "BlueSnap Street",
        "state": "CA"
    },
    "creditCard": {
        "expirationYear": 2020,
        "cardLastFourDigits": 4821,
        "cardType": "VISA",
        "expirationMonth": 8
    },
    "email": "person&#x40;bluesnap.com"
}

Back to Top

Step 4: Process the transaction with the wallet information

Once you have the shopper's final approval, you are ready to process the transaction. Follow the steps below for the Payment API or the Extended Payment API.

In the Payment API

There are two different ways to do this:

Option 1. Create or update a Vaulted Shopper with the wallet info, and then use the vaulted shopper ID in the Auth Capture or Auth Only request

You can save the shopper's information from the wallet by including it in a Create Vaulted Shopper or Update Vaulted Shopper request.

Then just send a standard Auth Capture or Auth Only request with the vaulted shopper ID.

Option 2. Add the wallet ID directly in your Auth Capture or Auth Only request

You can instead include the wallet ID directly in an Auth Capture or Auth Only request. For example:

{
    "walletId": 21,
    "amount": 35,
    "currency": "USD",
    "cardTransactionType": "AUTH_CAPTURE"
}

In the Extended Payment API

There are two different ways to do this:

Option 1. Create or update a Shopper with the wallet info, and then use the shopper ID in the Create Order with Existing Shopper or Create Shopping Context request

You can save the shopper's information from the wallet by including it in a Create Shopper or Update Shopper request. For example:

<shopper xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
  </web-info>
  <shopper-info>
    <store-id>11580</store-id>
    <shopper-currency>USD</shopper-currency>
  </shopper-info>
  <wallet-id>21</wallet-id>
</shopper>

Then just send a standard Create Order with Existing Shopper or Create Shopping Context request with the shopper ID.

Option 2. Add the wallet ID directly in Create Order and New Shopper request

You can instead include the wallet ID directly in a Create Order and New Shopper request. For example:

<batch-order xmlns="http://ws.plimus.com">
  <shopper xmlns="http://ws.plimus.com">
    <web-info>
     <ip>62.219.121.253</ip>
    </web-info>
    <shopper-info>
      <store-id>11580</store-id>
      <shopper-currency>USD</shopper-currency>
    </shopper-info>
    <wallet-id>21</wallet-id>
  </shopper>
  <order>
    <ordering-shopper>
        <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
        <sku-id>2183716</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>10</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>

Sandbox testing

To test the Visa Checkout flow, you'll need a test Visa Checkout account with a test card added. You may use the following card:

ccn: 4622943127023613
cvv: 770
exp: 12/22

Back to Top