(Script tags will be stripped)


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

KEYVALUEREQUIRED
AuthorizationBearer {Token}Yes
Content-Typeapplication/jsonYes
Idempotency-KeystringWhere applicable
  • The Authorization header is where you will pass your token. Details on how to generate a token are outlined in this [Authentication section ](https://developers.zip.co/v2/docs/authentication-2)

    • 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:

DESCRIPTIONMETHODENDPOINT
Create an orderPOST/pos/order
Cancel an orderPOST/pos/order/id/cancel
Commit a charge (auth flow only)POST/pos/order/{orderId}/commit
Rollback a charge (auth flow only)POST/pos/order/{orderId}/rollback
Query an orderGET/v2.0/pos/order/{orderId}

Postman Collection

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

Download the Postman Collection [here](🔗)