Home

Callback Events

Suggest Edits
Plugin icon

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

PropertiesTypeOptional/RequiredDescription
customerCustomer objectRequiredThis 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.
cardholderCardholder objectRequiredThe 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.
cardCard objectRequiredDetails about the issued virtual card for your transaction.
clientTokenstringOptionalUsed 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.
shippingAddressAddress objectOptionalUsed in express flows, the customer's shipping address is returned on the result object.
merchantFeeForPaymentPlannumberOptionalA customer contribution model that includes an incremental order amount called “Merchant Fee for Payment Plan” (MFPP).
orderIdstringOptionalSets 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 or if 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 in the below tables.

Checkout Flow Functions

openCheckout (with custom DOM element)

This method is required when a custom DOM element is used and will launch the virtual checkout in a popup window (or iframe depending on provided parameters). The method requires 3 parameters with an optional 4th parameter.

Attribute NameTypeOptional/RequiredDescription
amountnumberRequiredThe maximum amount that can be authorized on the issued virtual card. It should include all fees, taxes, shipping, and discount codes calculated in its value.
orderJsonOptionalThe order information in json format. See below for a complete example.
checkoutFlowenumRequiredIndicates if it’s the standard or express flow. Either “standard” or “express”.
forceIFrameboolRequiredIndicates if the Zip checkout flow will open in an iframe or a modal (popup).
hideOverlayboolOptionalDefault functionality will present a dark gray overlay behind the pop-up window, unless hideOverlay is set to 'true.'

Code Example:

var customButton= document.getElementById("customButton");
customButton.addEventListener("click", () => {
                window.quadpay.virtualCheckout.openCheckout("44444444-4444-4444-4444-444444444444", order, “standard”, false);
 });

focusCheckout

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

Code Example: 

window.quadpay.virtualCheckout.focusCheckout();

closeCheckout

This method force-closes the Zip checkout window and ends the user's Zip session.

Code Example: 

window.quadpay.virtualCheckout.closeCheckout();

Updated over 1 year ago