Home
Guides

Zip virtual checkout button

Suggest Edits
Plugin icon

Australian web virtual checkout

Give your shoppers the option to with Zip seamlessly without a full integration.

The Zip button uses a custom web component to manage the virtual checkout. It is built on top of the Virtual Checkout API. This gives you an easy way to add a 'Checkout with Zip' on your site that will launch the virtual checkout on click!

Add the Zip Button

Insert the following HTML to initialize the zip-button element (make sure you also import the zip.js script as a script tag):

<zip-button merchantId="742a2f20-8005-49d6-8dd2-bef3157a49c9" merchantReference="your_reference" amount="100" currency="AUD"></zip-button>

Attributes

merchantId Required

The merchant ID will be a UUID. This is your public publishable key. The key will look something like this: 742a2f20-8005-49d6-8dd2-bef3157a49c9. This key will be supplied by Zip.

merchantReference Required

Your unique order reference.

amount Required

Total amount of order. This is the amount that is charged to the customer’s zip account to generate the VCN.

currency Required

The transaction currency. Accepted value: AUD

customerFirstName Optional

The customer's first name.

customerLastName Optional

The customer's last name.

customerEmail Optional

The customer's email address.

CustomerPhoneNumber Optional

The customer's phone number.

customerPostalCode Optional

The customer's first name.

customerCountry Optional

The customer's country. Accepted value: AU

customerAddressLine1 Optional

The customer's Address

CustomerCity Optional

The customer's city

CustomerState Optional

The customer's state.

📘

Internet Explorer 11 Support

Because the zip-button utilises webcomponents, you have to take extra care when initialising it within IE11.

In modern browsers, you can start working with the zip-button as soon as the zip.js script executes. However, in IE11, you'll want to configure an event listener on the document for the WebComponentsReady event and then execute your setup code. This is only required if you expect to support IE11.

Here's a sample Internet Explorer 11 script:

if (isIe11()) {
    document.addEventListener('WebComponentsReady', function (e) {
        setupZip();
    });
} else {
    setupZip();
}

function isIe11() {
    return !!window.MSInputMethodContext && !!document.documentMode;
}

Using the Zip virtual card in existing checkout

When a customer completes the Zip checkout, we generate a single-use Visa credit card that can be captured by your existing credit card form.
Register callbacks for onSuccess, and onClose and use them to interact with your form.

onSuccess

The onSuccess handler is the callback that is invoked after a successful virtual card checkout. Within this handler, you'll need to set the card data. The onSuccess handler may be asynchronous as it is awaited.

See the example below:

// Triggered when the customer completes the Zip checkout
zipButton.onSuccess(function(card) {

  // Fill in your existing credit card form with the details from
  // the dynamically generated Zip single-use card
  document.getElementById('creditCardNumber').value = card.cardNumber;
  document.getElementById('creditCardCvv').value = card.cvv;
  document.getElementById('creditCardExpiryMm').value = card.expiry.slice(0,2);
  document.getElementById('creditCardExpiryYyyy').value = card.expiry.slice(2,6);
  document.getElementById('cardholderName').value = card.cardHolder;

  // Auto-submit the form for the customer
  document.getElementById('creditCardForm').submit();
});

The onSuccess callback will pass Card and Cardholder objects that you can use to fill in your existing form.

onClose

You can also trigger an action when a customer exits the Zip checkout.

See the example below:

// Triggered when the customer abandons the Zip checkout process
zipButton.onClose(function() {
  console.log('Zip checkout canceled by customer');
  enableOtherPaymentMethods();
});

onError

You can trigger an action to be invoked whenever the order data supplied as attributes on the zip-button is invalid and the user clicks it to initiate a checkout. Instead of launching the checkout, this onError callback will be invoked instead.

See the example below:

zipButton.onError(function(errorMessages) {
  console.log('Received error messages', errorMessages);
});

Example Full implementation

<head>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, minimal-ui">
    <script src="https://zip.co/static/lib/js/checkouts-zip-sdk-checkout-vcn-js-sand/zip-vcn-checkout.js"></script>
</head>
<body>
    <zip-button 
        merchantId="ec83c756-7b70-4bbd-be8b-48c41d2b871c" 
        merchantReference="test_reference_1" 
        amount="100" 
        currency="AUD" 
        id="zip-button">
  	</zip-button>
    <form style = "margin-top: 50px;">
        <input id="creditCardNumber"></input>
        <input id="creditCardCvv"></input>
        <input id="creditCardExpiryMm"></input>
        <input id="creditCardExpiryYyyy"></input>
        <input id="cardholderName"></input>
    </form>
</body>
<script type="text/javascript">
  	// Required to support Internet explorer
    if (isIe11()) {
        document.addEventListener('WebComponentsReady', function (e) {
        setupZipButton();
        });
    } else {
        setupZipButton();
    }

    function isIe11() {
        return !!window.MSInputMethodContext && !!document.documentMode;
    }

    function setupZipButton() {
        var zipButton = document.getElementsByTagName('zip-button')[0];

        zipButton.addEventListener('click',
        function (e) {
            zipButton.setAttribute('customerFirstName', document.getElementById('firstName').value);
			zipButton.setAttribute('customerLastName', document.getElementById('lastName').value);
            zipButton.setAttribute('customerEmail', document.getElementById('email').value);
            zipButton.setAttribute('customerPhoneNumber', document.getElementById('phoneNumber').value);
            zipButton.setAttribute('customerPostalCode', document.getElementById('postalCode').value);
            zipButton.setAttribute('customerCountry', document.getElementById('country').value);
            zipButton.setAttribute('customerAddressLine1', document.getElementById('addressLine1').value);
            zipButton.setAttribute('customerAddressLine2', null);
            zipButton.setAttribute('customerCity', document.getElementById('city').value);
            zipButton.setAttribute('customerState', document.getElementById('state').value);

            const orderItems = [
            {
                name: 'Item Name',
                amount: 100.00,
                description: 'Item description',
                quantity: 1,
                type: 'sku',
            },
            ];
            zipButton.setAttribute('orderItems', JSON.stringify(orderItems));

        }, true);

        zipButton.onSuccess(function (card) {

            document.getElementById('cardholderName').value = card.cardHolder;
            document.getElementById('creditCardNumber').value = card.cardNumber;
            document.getElementById('creditCardCvv').value = card.cvv;
            document.getElementById('creditCardExpiryMm').value = card.expiry.slice(0,2);
            document.getElementById('creditCardExpiryYyyy').value = card.expiry.slice(2,6);

        });
        zipButton.onDecline(function (message) {
            console.log("User Declined Message:" + message);
        });
        zipButton.onClose(function (message) {
            console.log("User Closed Message:" + message);
        });
        zipButton.onError(function (message) {
            console.log("JS Error: " + message);
        });
    }
</script>

Updated over 1 year ago