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

1. The customer has browsed through your website, added items to the cart and has proceeded to checkout

2. They continue through the checkout section until they arrive on the final page/section to select their payment method

3. Zip is presented as a payment option alongside your other payment options

4. On selecting the Zip payment method, the Place Order button (or equiv) should be updated in order for the customer to proceed

5. 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

6. Ensure you pass as many parameters as possible for order and customer details (item name, quantities, price, customer name, email etc.)

7. The customer is then redirected from the redirectUrl extracted from the /order API method call (or alternatively, the lightbox/embedded checkout)

8. The customer will be asked to sign in or create a new Zip account

9. 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

10. 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

11. 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

12. 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.

13. 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

14. 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

15. A cancelled order should result in the user being shown the checkout/payment method page

16. 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