Overview

The Zip API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication.

You can use the Zip API in test mode, which does not affect your live data. All you need to do is use the sandbox API endpoint along with your sandbox API credentials.

API Urls

Zip APIs are available through different base URLs, one to access our global platforms and another that is dedicated to interact with the Australian platform only.

To access these APIs, combine the base URL + endpoint, for example to "create a checkout" construct the URL to call like this:

BASE URL for environment + /checkouts/

https://global-api.sand.au.edge.zip.co/merchant/checkouts/

Use the sandbox environment to get familiarized with the API behavior and try out your requests; use the live environments to start real transactions with Zip once your integration has been certified and pushed live.

Production (Live)
Global platform: https://global-api.prod.au.edge.zip.co/merchant
Australian platform only: https://api.zipmoney.com.au/merchant/v1

Sandbox (Testing)
Global platform: https://global-api.sand.au.edge.zip.co/merchant
Australian platform only: https://api.sandbox.zipmoney.com.au/merchant/v1

Authentication

The Zip web API uses a secure API key to identify and authorize the merchant. In order to use the API you will need to first request your merchant credentials.

Once registered an API key will be provided to you. Make sure to keep your API key secret, it is a secure key that should not be placed anywhere publicly available such as open source repositories or client side code.

Your API key must be provided in a HTTP Authorization header for all requests. All requests need to be made over https (TLS 1.2).

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

A breakdown of the full required header info is as below:

Useful Notes

• The Content-Type entity header is used to indicate the media type of the resource.
• The Authorization header is where you will pass your merchant API key. Details on where to find your API key are outlined in the 'Preparing for Integration' section of this documentation.
• 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.

var apiKey = read.from.config('ZipAPIKey');
request.headers.add("Authorization", "Bearer " + apiKey);

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

To perform an idempotent request, provide an additional Idempotency-Key header to the request.

Zip's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

We recommend sending idempotency keys for all transactional requests except the /checkouts endpoint.

curl --request POST \
  --url https://global-api.sand.au.edge.zip.co/merchant/checkouts/co_P9GOgSVE9qMnL0VA6Jy8z6 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 1' \