Zip virtual checkout API
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.
Updated over 1 year ago