## 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.
KEY | VALUE | REQUIRED |
Authorization | Bearer {Token} | Yes |
Content-Type | application/json | Yes |
Idempotency-Key | string | Where 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:
DESCRIPTION | METHOD | ENDPOINT |
Create an order | POST | /pos/order |
Cancel an order | POST | /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 order | GET | /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](🔗)