Environment

Below are a list of endpoints for API in both Sandbox and Production environments:

📘

Sandbox: https://sandbox.zip.co/nz/api

Production: https://zip.co/nz/api

Authentication

The Zip Merchant API uses a secure token to identify and authorise merchants In order to use the API, you will first need to register as a Zip partner.

Once registered, a set of client credentials will be provided.

Using the client credentials, use the token endpoint to generate a secure token - this must be provided in the Authorization header for all requests.

• The Authorization header is where you will pass your token. Details on how to generate a token are outlined in this Authentication section
  

  • The Content-Type entity header is used to indicate the media type of the resource

  • The Idempotency-Key is a unique random string for each request. If a request times out or provides invalid response you can attempt to repeat exact same request with same idempotency key to avoid any duplication

Scopes

Merchant Level

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.

Store Level

We can also setup an auth client per-store, which means each store has a seperate auth client. This is useful for cases where 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.

📘

Separate Settlement

Please note that at this time, we equate a merchant as the payment relationship, meaning if each of your stores have a separate settlement bank account, the store level scope cannot be utilised. In this case, separate merchant clients/credentials will need to be allocated for each store.

Method Overview

The following list of API methods are those that are part of the standard transaction flow:

📘

Postman Collection

You can test each of the API calls using the Postman Collection below:

Download the Postman Collection here