Australian web virtual checkout

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

Once the zip.js library has loaded, all of the virtual checkout functionality will be available on the window.zip.vcnCheckout object.

On Success Callback handler

window.zip.vcnCheckout.onSuccess(callback)

• This method accepts a function as a parameter that will be invoked when a customer successfully completes the Zip checkout.
• This method can be asynchronous as it is awaited on the Zip side. It is responsible for taking the card and cardholder information to fill in the credit card payment details, hide those payment details, and then submit the checkout.
• The best user experience comes from hiding the credit card information and auto-submitting the order within this callback.
• This function should accept 1 parameter: card

Example - On Success

const callback = function(card) {
  
  // Fill in your existing credit card form with the details from
  // the dynamically generated Zip multi-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();
};
  
window.zip.vcnCheckout.onSuccess(callback);

Open Checkout (Required)

window.zip.vcnCheckout.openCheckout(merchantId, checkout)

• This method will launch a virtual checkout in a popup window (or iframe, depending on browser).
• The method requires 2 parameters with an optional third:
  - merchantId (string): Your unique merchant ID for your integration and the environment you're using virtual checkout
  - checkout (Checkout): Checkout details including amount, currency, your reference ID, and customer information.
• This method will return a promise that completes once the checkout has been opened. As part of this process, it will invoke validate as well to ensure the data provided is valid.

Example - Open Checkout

const merchantId = '44444444-4444-4444-4444-444444444444';
const checkout = {
  order: {
    currency: "AUD",
    amount: 400,
    reference: "your-unique-order-id"
  }
}
  
// This will launch the checkout in the new window.  When the checkout session is  successful, your previous onSuccess callback handler will be invoked.
await window.zip.vcnCheckout.openCheckout(merchantId, checkout);

On Error Callback Handler

window.zip.vcnCheckout.onError(callback)

• The on error callback handler will be invoked if the parameters supplied to open checkout are invalid or missing.
• This is an optional callback as a no-op is provided by default. The callback may be asynchronous as it is awaited.
• The callback will accept one parameter:
  - errorMessages (string[]): Array of error messages about what validation failed.

Example - On Error

const callback = function(errorMessages) {
    console.log('Received error messages', errorMessages); 
}
window.zip.vcnCheckout.onError(callback);

On Close Callback Handler

window.zip.vcnCheckout.onClose(callback)

• The on close callback is invoked whenever the user closes the Zip checkout.
• This may happen if they close the window, click back to cart, are not approved, or their session times out.
• This is an optional callback as a no-op is provided by default. The callback may be asynchronous as it is awaited.
• The callback will accept one parameter:
  - message (string): Message about why the checkout was closed.

Example - On Close

const callback = function(message) {
    console.log(`Virtual checkout was closed: ${message}`); 
  enableOtherPaymentMethods();
}
window.zip.vcnCheckout.onClose(callback);

Validate

window.zip.vcnCheckout.validate(merchantId, order, checkoutFlow)

• Validates the supplied merchant ID, order parameters, and checkout flow (same as what's passed to open checkout).
• Returns a promise. If data is invalid, it will invoke (and await) the
  (onError callback) and return a string array of error messages;

Example - Validate

const merchantId = '44444444-4444-4444-4444-444444444444';
const checkout = {
  order: {
    currency: "AUD",
    amount: 400,
    reference: "your-unique-order-id"
  }
}

const errorMessages = await window.zip.vcnCheckout.validate(merchantId, checkout);
if (errorMessages && errorMessages.length > 0) {
  console.log('Data is invalid!', errorMessages);
}

Focus Checkout

window.zip.vcnCheckout.focusCheckout()

• This allows you to programmatically bring focus to the pop-up window once the virtual checkout has been opened.

Close Checkout

window.zip.vcnCheckout.closeCheckout()

• Force closes the Zip checkout window and ends the user's Zip session.