User Journey

This section details the user experience of a customer performing a standard checkout from the payment method section of your website

User Journey

The customer has browsed through your website, added items to the cart and has proceeded to checkout
They continue through the checkout section until they arrive on the final page/section to select their payment method
Zip is presented as a payment option alongside your other payment options
On selecting the Zip payment method, the Place Order button (or equiv) should be updated in order for the customer to proceed
When this button is clicked, this should trigger a request to the Zip APIs (either for the redirect or via the lightbox/embed). This server-side handler will need to make a call to the /order API method
Ensure you pass as many parameters as possible for order and customer details (item name, quantities, price, customer name, email etc.)
The customer is then redirected from the redirectUrl extracted from the /order API method call (or alternatively, the lightbox/embedded checkout)
The customer will be asked to sign in or create a new Zip account
After logging in or successfully signing up, the customer will be presented with the order review screen where they are shown a list of instalments along with the total amount they are to pay today
Once the customer clicks "Complete", a "Payment Approved" screen stays visble for a few seconds then returns the customer to the redirectConfirmUrl that was specified in the /order API call
The redirectConfirmUrl & redirectCancelUrl is intended to be an intermediate handler page and does not in itself need to display content, but can rather action the remaining steps and then redirect the customer to the appropriate page.

Depending on your architecture you may want to build it in to another page
When the user is returned back to your website, the URL will have the following parameters appended to the URL:

orderId: Used to uniquely identify the Zip order paymentStatus: Indicates the status of the payment - Possible values are:

success: Payment via Zip NZ completed
failure: Payment not taken - Zip NZ service not offered, or payment declined
cancelled: User cancelled out of Zip NZ process and returned to your website

📘
Important Security Note: Always use the status from the /order/{orderId} API before fulfilling an order. The paymentStatus parameter is convenient for user flow but is open to tampering.

A successful order should result in the order that was created being updated to "Paid" or similar, and a checkout success page should be shown on your website
A failed order should result in the user being shown a payment declined page and the order being updated to cancelled. If possible, rollback the order to a cart and restore to the user's session
A cancelled order should result in the user being shown the checkout/payment method page
Your server queries Zip NZ API for order information. This is done via the GET /order/{orderId} API method, and this can be used to reconcile any orders that have started, but users have not returned to your website (e.g. Network issues, premature exit).

🚧
orderStatus: Indicates the status of the order - Possible values are:

Created: Order has been created but has yet to be completed or abandoned

Abandoned: User cancelled out of Zip NZ process and returned to your website

Approved: Payment has been taken successfully and order has been confirmed

Authorised: Funds are being held and is awaiting capture of funds from the merchant

Expired: The held funds were not captured in time and has expired - cancelling the order