Visa Checkout

Visa Checkout is a safe and easy digital payment service that allows consumers to pay for goods online, on any device, in just a few clicks. Shoppers can enrol their Visa credit and debit cards, as well as cards from other schemes. At purchase time they simply provide their username and password to complete the payment process.

The Visa Checkout button displays on your checkout page and, when clicked, opens the Visa Checkout lightbox over this page. This enables your customers to finalise their payment without leaving your site.

Prerequisites

  • Your payment service provider must enable Visa Checkout service on your merchant profile.
  • You must create and activate your Visa Checkout account for use with the CommWeb payment gateway, using Merchant Administration. The merchant operator must have "May Configure Integration Settings" privilege.
Visa Checkout Flow

The diagram below shows a sample checkout flow for your shop site and Visa Checkout.

  1. A payer browses your shop site, selects one or more products, and clicks Visa Checkout on the checkout page.
  2. In the Visa Checkout Lightbox, displayed over the top of the shop site, the payer:
    • Logs into their Visa Checkout wallet and passes any required secondary validation steps.
    • Selects a card for payment.
    • Selects a shipping address, or adds a new one.
    • Clicks a button to confirm their choices and close the pop-up.
  3. At your shop site the payer finalizes the purchase, and you display the order summary/receipt.

Integrating to Visa Checkout

There are three options for integrating Visa Checkout into your payment flow:

Visa Checkout via Hosted Checkout

If you have an existing Hosted Checkout integration, Visa Checkout will automatically be available once you have successfully enabled it.

Visa Checkout via Hosted Session

If you have your own payment page then you can choose the Hosted Session integration option to have the CommWeb payment gateway manage the details of loading the Visa Checkout SDK, launching the Visa Checkout lightbox, and updating the results into a payment session.

Sample Code to Invoke the Visa Checkout Lightbox
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://paymentgateway.commbank.com.au/form/version/57/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>

<!-- DISPLAY VISA CHECKOUT AS A PAYMENT OPTION ON YOUR PAYMENT PAGE -->

<!-- REPLACE THE action URL with the payment URL on your webserver -->
<form name="myform" method="POST" action="https://my.company.com/pay">
<!-- Other fields can be added to enable you to collect additional data on the payment page -->
Email: <input type="text" name="email">
<!-- The hidden values below can be set in the callback function as they are returned when creating the session -->
<input type="hidden" name="sessionId" id="sessionId">
<img id="visaCheckoutButton" alt="Visa Checkout" role="button" class="v-button" style="display: none;" src="https://sandbox.www.v.me/wallet-services-web/xo/button.png"/>
</form>

<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
    var antiClickjack = document.getElementById("antiClickjack");
    antiClickjack.parentNode.removeChild(antiClickjack);
} else {
    top.location = self.location;
}

PaymentSession.configure({
    frameEmbeddingMitigation: ["javascript", "x-frame-options", "csp"],
    callbacks: {
        initialized: function(response) {
            // HANDLE INITIALIZATION RESPONSE
            if (response.status === "ok") {
                document.getElementById("visaCheckoutButton").style.display = 'block';
            }
        },
        visaCheckout: function(response) {
            // HANDLE VISA CHECKOUT RESPONSE
        }
    },
    order: {
        amount: 10.00,
        currency: "AUD"
    },
    wallets: {
        visaCheckout: {
            enabled: true,
            // Add Visa Checkout API specific attributes here
            countryCode: "AU",
            displayName: "Display name",
            locale: "en_au",
            logoUrl: "http://logo.logo",
            payment: {
                cardBrands: [
                    "VISA"
                ]
            },
            review: {
                buttonAction: "Pay",
                message: "Message"
            },
            shipping: {
                acceptedRegions: [
                    "AU"
                ],
                collectShipping: true
            }
        }
    }
})
</script>
</body>
</html>
  1. Include the session.js client JavaScript library hosted by the gateway in your payment page. The path to this file includes both the api version and the merchant identifier for the session.
  2. Display the payment page to the payer with Visa Checkout as a payment option. Specify class="v-button" button attribute as required by the Visa Checkout integration. This is to facilitate launching of the lightbox when the payer clicks the Visa Checkout button.
  3. Invoke the PaymentSession.configure(configuration) function. You need to provide the following in the configuration object to initiate a Visa Checkout interaction:

    • wallets.visaCheckout.enabled: Set this to true.
    • wallets.visaCheckout.<attributes>: (Optional) Additional configuration parameters for Visa Checkout such as countryCode, locale, etc.
    • order.currency: The currency in which the order is being paid.
    • order.amount: The amount of the order.

    session.js API Reference[JavaScript]

  4. Once the Visa Checkout lightbox is initialized with the required data, the response is returned in the initialized( ) callback defined in the PaymentSession.configure(configuration) function. A successful initialization returns response.status="ok".
  5. When the payer interaction with the lightbox is finished, session.js automatically uses the callId returned by the lightbox to retrieve the payment details from Visa Checkout. The result of the interaction is returned in the visaCheckout( ) callback defined in the PaymentSession.configure(configuration) function — if response.status="ok", then the returned payment session will contain the interaction details from Visa Checkout.
  6. Your payment page should pass the returned payment session to your web server so that it can be used to invoke an operation referencing the session. For more information, see Perform an Operation Using the Session.
Visa Checkout via Direct Payment for DirectAPI version 31 and above

If you want full control over the Visa Checkout lightbox interaction on your payment page, you can choose this option to invoke the lightbox yourself. To launch the lightbox, include the Visa Checkout SDK directly and listen for events. You must then pass the callId returned by the Visa Checkout lightbox to the CommWeb payment gateway, using the Update Session From Wallet operation. This identifier enables the CommWeb payment gateway to retrieve the details of the interaction from Visa Checkout and store them in a payment session. You can choose to view the contents of the payment session or perform a payment or a storage operation using the standard operations that reference payment sessions.

Do not invoke any DirectAPI operation directly from the browser.

The integration steps are as follows:

On your Web Server: Create a Session
  1. Perform a Create Session operation to obtain a session ID.

    Create Session API Reference[REST][NVP]

In your Payment Page: Initialize and Invoke the Visa Checkout Lightbox
Use the following steps as a guideline, for more details, read the Visa Checkout Web Integration/JavaScript SDK integration guide.
  1. Reference the Visa Checkout JavaScript client library in your payment page.
  2. When the payer clicks Visa Checkout, launch the Visa Checkout lightbox. You should include a way to identify Visa Checkout as the checkout option selected by the payer.
  3. Add a callback handler for the payment.success event generated by the lightbox. Retrieve the callId(returned only if the Visa Checkout interaction was successful) and pass it to your web server.
On your Web Server: Collect Payment Details into a Session
  1. Perform an Update Session From Wallet operation to get the payer's payment and shipping details from Visa Checkout. You need to provide the following parameters in this operation.

    • Session ID: The identifier for the payment session as returned by the Create Session operation.
    • order.walletProvider: Set to VISA_CHECKOUT
    • wallet.visaCheckout.callId: The callId as returned by the Visa Checkout lightbox.
    • order.amount: The amount of the order.
    • order.currency: The currency in which the order is being paid.

    If successful, the returned session will contain the payer's payment details from the Visa Checkout interaction.

    Update Session From Wallet API Reference [REST][NVP]

  2. Use the returned session to present an order confirmation page or to submit a payment to the CommWeb payment gateway. See Perform an Operation Using the Session.
If using DirectAPI version 22-30, use the Open Wallet operation in place of Update Session From Wallet operation.

Clickjacking Prevention Requirement

If your website displays the Visa Checkout button, you must provide code on each page that hosts the button including 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 more information, see Clickjacking Prevention Requirement for Visa Checkout.

The Hosted Checkout integration by default complies with the clickjacking prevention requirement.

User Interface Requirements

When presenting Visa Checkout as a payment option on your website, you must comply with the user interface branding requirements from Visa. For guidelines on how to present the user interface elements, see Visa Checkout Branding Requirements.

Testing Your Visa Checkout Integration

You have two options to test your Visa Checkout integration:

  1. Visa Checkout Emulator provided by the CommWeb payment gateway.
  2. Visa Checkout Sandbox provided by Visa.

These allow you to trigger different responses for Visa Checkout interactions.

Using the Visa Checkout Emulator
The Visa Checkout Emulator may be used to test Visa Checkout integrations via Hosted Checkout and Hosted Payment Session with JavaScript (HPF.js) only.

To configure your merchant profile, so you can use the Visa Checkout Emulator:

  1. Log in to Merchant Administration using your TEST merchant profile (your Merchant ID prefixed with "TEST").
  2. Under Admin > Visa Checkout Configuration:

    1. Select the option to route requests to the Visa Checkout Emulator.
    2. Activate Visa Checkout as a payment option.

You can now start using the Visa Checkout Emulator.

Using the Visa Checkout Sandbox
The Visa Checkout Sandbox may be used to test Visa Checkout integrations via Hosted Checkout, Hosted Payment Session with JavaScript (HPF.js), and Direct Payment.

To configure your merchant profile, so you can use the Visa Checkout Sandbox:

  1. Log in to Merchant Administration using your TEST merchant profile (your Merchant ID prefixed with "TEST").
  2. Under Admin > Visa Checkout Configuration:

    1. Provide your merchant details and create the Visa Checkout Sandbox account.
    2. Select the option to route requests to the Visa Checkout Sandbox.
    3. Activate Visa Checkout as a payment option.

You can now start using your Sandbox account. If you have built a Direct Payment Visa Checkout Integration, use the API Key associated with your Sandbox account to perform test transactions.

Testing a Direct Payment Visa Checkout Integration

Submit an Open Wallet request for a Visa Checkout interaction with

callId=Success <RandomString>-<CardNumber>-<CardExpiryMonth>-<CardExpiryYear>.

Test Cards Card Number
Visa 4005520201264821
Visa 4242424242424242
Mastercard 5500005555555559
American Express 340353278080900
Discover 6011003179988686

This will trigger a successful Open Wallet response with:

  • sourceOfFunds.provided.card.number=<CardNumber>
  • sourceOfFunds.provided.card.scheme=<CardType> (depending on <CardNumber>)
  • sourceOfFunds.provided.card.brand=<CardBrand> (depending on <CardNumber>)
  • sourceOfFunds.provided.card.expiry.month=<CardExpiryMonth>
  • sourceOfFunds.provided.card.expiry.year=<CardExpiryMonth>
  • sourceOfFunds.provided.nameOnCard=John Smith
  • billingAddress.line1=300 Adelaide Street
  • billingAddress.line2=Floor 21
  • billingAddress.city=Brisbane
  • billingAddress.stateProvinceCode=QLD
  • billingAddress.postalCode=4000
  • billingAddress.countryCode=AU
  • billingAddress.phone=07-0000-0000

Going Live

To go live you must create a Visa Checkout production account for use with the gateway:

  1. Log in to Merchant Administration using your production merchant profile (your Merchant ID without the "TEST" prefix).
  2. Under Admin > Visa Checkout Configuration, provide your merchant details and create the Visa Checkout production account.
    The account status will be PENDING until Visa Checkout completes its sign-up process. After that, the account status will be set to ACTIVE.
  3. Once the Visa Checkout production account status is ACTIVE, activate Visa Checkout as a payment option.

You can now start using your production account.

If you have built a Direct Payment Visa Checkout Integration, use the API Key associated with your production account to perform live transactions.

FAQs

How do I identify a Visa Checkout interaction?

callId uniquely identifies a Visa Checkout interaction and is stored against the associated Visa Checkout transaction. A Visa Checkout transaction is a transaction where Visa Checkout was used to collect the payer's payment details via a Visa Checkout interaction.

You can search for a Visa Checkout transaction in Merchant Administration using the callId or any of the following search strings:

  • "Visa Checkout"
  • "Wallet Provider":"Visa Checkout"
  • VISA_CHECKOUT
  • @walletProvider:VISA_CHECKOUT

This may be useful for troubleshooting any issues with the Visa Checkout interaction.

Why can't I see the customer's email retrieved from Visa Checkout against the transaction?

The CommWeb payment gateway stores the customer's email address retrieved from the Visa Checkout interaction in a payment session and against the transaction in the field customer.email. However, if you directly provide customer.email and also provide the payment session (containing the payment details collected from Visa Checkout) on a Pay or an Authorize transaction then customer.email that was provided directly overrides the customer's email retrieved from Visa Checkout.

Copyright © 2020 Commonwealth Bank of Australia