Developer Documentation
Developer Documentation

Merchant API

The Zip NZ merchant API allows for Zip orders to be created and paid for online - typical use for this is e-commerce.


To access this API you will need to obtain a token using the Client Credentials flow - see more in Authentication

Payment Flow

Each of these steps is described in more detail below:

  1. User selects Zip NZ This is typically offered as a payment option for users when they are at the stage of checkout on the merchant site.
  2. Merchant Server POSTs to Zip NZ API The merchant server creates an API call to the Zip NZ Create Order endpoint. This contains:
    • Customer details (email, name, phone number)
    • Order details (what the customer is purchasing from the merchant site)
    • Billing and Shipping addresses
    • Amount (plus optional information regarding discounts / shipping / tax)
    • RedirectUrl - this is a merchant hosted URL, to return the customer to once they have completed the Zip checkout process.
  3. Zip NZ API returns a token and a Redirect URL The Zip NZ API returns a unique token for the order and the URL to redirect the user to.
  4. Redirect User to Zip NZ payment page Redirect the user to the URL returned in step 3 from the API
  5. User Completes Payment Steps at Zip NZ User completes their payment information on Zip NZ site. This will result in a user being able to pay via Zip NZ or not.
  6. User is returned to the Merchant page when complete Once user has completed the Zip NZ process, they are redirected to the Merchant page. When the user is returned back to the merchant page, the URL will have the following parameters appended to the URL:
    • 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 merchant site.
    • orderId used to uniquely identify the order
  7. Merchant Server queries Zip NZ API for order information. This is done via the Get Order endpoint, and this can be used to reconcile any orders that have started, but users have not returned to the merchant site, for whatever reason.
  8. Merchant site reconciles payment On receipt of a payment status (successful or otherwise), it is expected the merchant server will reconcile the order status.