Developer Documentation
Developer Documentation

Instore API

Zip NZ offers an in-store process, whereby customers are able to pre-request credit, and complete the payment of the order at the point of sale, in a seamless manner.


A typical in-store order flow with Zip is a 2-step process.

  1. The customer requests a pre-approval code via their phone.
  2. At the point of sale, the pre-approval code is entered when Zip is selected as a payment method. The merchant terminal then creates the order (with some order metadata), along with a uniquely identifiable token, which the customer will present at the time of checkout. See more in Create Order
  3. The customer is presented an option to confirm or cancel the transaction on their device.
  4. The merchant terminal will poll Zip to enquire if this order has been confirmed by the customer. See more in Order Status The below diagram shows the typical 2-step flow for a POS integration with Zip.

Instore Code Redemption

You have 2 options for redeeming instore codes (and creating orders). The customer is presented both a 6-digit code, and a QR code on their native app. See example below:

For retailers who have QR scanning capabilities, you are able to scan the image and submit the decoded value into the customerApprovalCode value in the create order endpoint.

Alternatively, you are able to manually input the value into the customerApprovalCode if your POS does not support QR scanning.


Authentication is one by the obtaining of a bearer token, by posting a client_id and a client_secret to the token endpoint. Given these values are particularly long and cumbersome to input to a POS terminal, we offer the ability to have an interactive enrolment process whereby a retailer is able to enrol their terminal from the Merchant Portal.

To obtain a token, see authentication.


For our instore solution we offer a number of different ways of authenticating into Zip.


For larger retailers who wish to use an integration/middleware layer, we can setup your environment so there is only one Auth client. This means all auth-related concerns can be handled within your middleware layer and originating store/terminal details are pass through the subsequent API calls.

In these cases, you will need to stipulate the StoreId in the relevant API calls via a header. These are described in the API documentation


We can also setup an auth client per-store, which means each store has a seperate auth client. This is useful for the case when a retailer does not run a middleware layer. We suggest scoping the auth credentials to the individual stores in this case, as any compromised keys are easier to invalidate & re-issue and do not risk the whole retail group.

Status Flow v1 (deprecated)

The below diagram shows the state changes an order can go through in the default flow. Red signifies the terminal statuses.

NB this status flow is deprecated for version 2 (below)

Status Flow v2

The below diagram shows the state changes an order can go through in the default flow. Version 2 of the get order status endpoint supports these statuses. Red & Green signifies the terminal statuses.


Enrolment allows easy enrolment of terminal devices, which is helpful when considering long/sensitive client ID’s & secrets.


Enrolment is an optional process. The end-result of enrolment is that the POS terminal will have the client_id and client_secret values

Once the merchant has signed up for the In-Store api, the Point of Sale terminal can download client credentials using the enrol endpoint.

Enrollment is a 2-step process initiated via the Merchant Portal.

  1. Obtain Activation Code From Merchant Portal
  2. Enrol the device and receive credentials

Enrolment Step 1 - Obtain Activation Code From Merchant Portal

Before attempting authorization, please ensure you are logged into the Merchant Portal.

Go to the Terminal Enrolment section in the Merchant portal ie. /instore/terminal-enrollment Enter in required fields

  • Terminal Name (A human readable)
  • Secret (min 5 characters) Click the [Add] link. This will create a short, time-limited code like A5B1D2.

Any number of POS Terminals can be enrolled depending on your POS Software. Zip can also provide you with the required client credentials should you want to deploy them in an alternate manner.

Enrolment Step 2 - Enrol your POS Terminal

The enrol endpoint is primarily a way to use a one-time code to easily download the client credentials for your Point of Sale terminal to enable it to use the In-Store Api. This has been designed for Point of Sale terminals that have limited configuration abilities.

See more detail @ the complete terminal enrolment endpoint

Auth-Capture Flow

By default, when orders are approved by the customer, a payment is taken from the customers card, and the order is marked as complete.

In certain scenarios, merchants may wish to have a commit/rollback solution. In this scenario, an payment authorisation is taken from the customer’s card when they approve an order. The merchant is then required to send Zip a subsequent request to either commit or rollback the transaction.

If no call to the commit after an hour, the payment authorisation on the card is committed and the order is marked as complete.

Create Order

In this scenario, you will need to create an order with the paymentFlow property marked as auth.

Status Flow

The below diagram shows the state changes an order can go through in an auth flow. Red signifies the terminal statuses.