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.
- The customer requests a pre-approval code via their phone.
- 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
- The customer is presented an option to confirm or cancel the transaction on their device.
- 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.
- Obtain Activation Code From Merchant Portal
- 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.
Enter in required fields
- Terminal Name (A human readable)
- Secret (min 5 characters)
[Add]link. This will create a short, time-limited code like
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
By default, when orders are approved by the customer, a payment is taken from the customers card, and the order is marked as
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.
In this scenario, you will need to create an order with the
paymentFlow property marked as
The below diagram shows the state changes an order can go through in an auth flow. Red signifies the terminal statuses.