Callback Events

onComplete

The onComplete Callback accepts a function as a parameter that will be invoked when a customer successfully completes the Zip checkout. It accepts card and cardholder information and fills in credit card payment details. In the Standard flow, this contains - card, cardholder, customer, order id, and optionally, merchantFeeForPaymentPlan. In the Express flow, the result also includes shippingAddress. This callback may be invoked asynchronously.

❗️
Billing Address
Zip provides a single billing address for all Zip-issued virtual cards. This is the address Zip requires be provided when processing the cards. Please do not hardcode this billing address. While the Zip billing address does not change often, we do periodically update it. If you hardcode the billing address, it will break the integration if we ever update the billing address.

🚧
User Experience Gotchas

Don't save the card details with the customer for future purchases as cards are issued on a per-transaction basis.

Code Example:

//On complete callback event
const onCompleteCallback = function (result)
{
    // Fill in your existing credit card form with the details from
    // the dynamically generated Zip single-use card
    document.getElementById("creditCardNumber").value = result.card.number;
    document.getElementById("creditCardCvc").value = result.card.cvc;
    document.getElementById("creditCardExpiryMm").value = result. card.expirationMonth;
    document.getElementById("creditCardExpiryyy").value = result.card.expirationYear;
    document.getElementById("cardholderName").value = result.cardholder.name;

    // Fill in your existing billing address form with details from
    // the card holder.  If your billing address contains first/last name
    // fields, you can leave those as the actual customer values.
    document.getElementById("name").value = result.cardholder.name;
    document.getElementById("addressLine1").value = result.cardholder.address1;
    document.getElementById("addressLine2").value = result.cardholder.address2;
    document.getElementById("city").value = result.cardholder.city;
    document.getElementById("state").value = result.cardholder.state;
    document.getElementById("zipCode").value = result.cardholder.postalCode;
    document.getElementById("country").value = result.cardholder.country;

    //For express version only
    //result.shippingAddress;
    document.getElementById("addressLine1").value = result.shippingAddress.address1;
    document.getElementById("addressLine2").value = result.shippingAddress.address2;
    document.getElementById("city").value = result.shippingAddress.city;
    document.getElementById("state").value = result.shippingAddress.state;
    document.getElementById("zipCode").value = result.shippingAddress.postalCode;
    document.getElementById("country").value = result.shippingAddress.country;
  
   // Fill in customer contact & billing information
    document.getElementById("cust_name").value = result.customer.firstName;
    document.getElementById("cust_name").value = result.customer.lastName;
    document.getElementById("cust_addressLine1").value = result.customer.address1;
    document.getElementById("cust_addressLine2").value = result.customer.address2;
    document.getElementById("cust_city").value = result.customer.city;
    document.getElementById("cust_state").value = result.customer.state;
    document.getElementById("cust_zipCode").value = result.customer.postalCode;
    document.getElementById("cust_country").value = result.customer.country;

    document.getElementById("cust_email").value = result.customer.email;
    document.getElementById("cust_phoneNumber").value = result.customer.phoneNumber;
  
   //Sets the unique ID to use for order creation
   //result.orderId;
  
};

window.quadpay.virtualCheckout.onComplete(onCompleteCallback);

If you are using the custom DOM element, the openCheckout function needs to be called to open the Zip checkout flow. See below for more specific details.

OnComplete Result Object

Properties	Type	Optional/Required	Description
customer	Customer object	Required	This contains information the customer enters in the Zip checkout. Merchants sometimes collect this data to store in their systems since the billing information needs to be overridden with the cardholder details.
cardholder	Cardholder object	Required	The cardholder includes the billing information attached to the issued virtual card. This will be different from customer information. If you require email or phone number as part of the billing information, you can use the customer's information for those fields.
card	Card object	Required	Details about the issued virtual card for your transaction.
clientToken	string	Optional	Used in tokenization. When Zip tokenizes the card details, the card object in the onComplete callback response will be null — the card number, expiration date, and CVV will not be provided. Instead, a root element clientToken will be populated with a gateway token id.
shippingAddress	Address object	Optional	Used in express flows, the customer's shipping address is returned on the result object.
merchantFeeForPaymentPlan	number	Optional	A customer contribution model that includes an incremental order amount called “Merchant Fee for Payment Plan” (MFPP).
orderId	string	Optional	Sets the unique ID to use for order creation.

onClose

The onClose callback is invoked whenever the user closes the Zip checkout. This optional callback may happen if the customer closes the window, clicks back to cart, is not approved, or their session times out. The callback may be asynchronous as it is awaited. The callback will accept one parameter:

message (string): Message about why the checkout was closed.

Code Example

///On close callback event
const onCloseCallback = function (result) {

};

window.quadpay.virtualCheckout.onClose(onCloseCallback);

onError

The onError callback handler will be invoked if the parameters supplied to the openCheckout method are invalid or missing. This optional callback handles technical errors during loading of the Zip checkout flow. The callback may be asynchronous as it is awaited. The callback will return error messages in the format of an array of strings representing error messages about what validation failed.

Code Example:

// On error callback event
const onErrorCallback = function (result) {
};

//Attaching the on error callback event
window.quadpay.virtualCheckout.onError(onErrorCallback);

More details on all Quadpay.virtualCheckout methods can be found here.

Callback Events

onComplete

❗️
Billing Address

🚧
User Experience Gotchas

onClose

onError

onComplete

❗️Billing Address

🚧User Experience Gotchas

onClose

onError

❗️
Billing Address

🚧
User Experience Gotchas