Edge cases and error handling

Plugin icon

Web checkout API

Edge cases and error handling

Give your shoppers the option to pay with Zip on your web platform with our web checkout solution.

Before going live there are a number of scenarios that must be considered in order to provide a complete integration. Some of these are items within your own codebase that Zip do not revise explicitly and are expected to be completed by the time you provide access for Certification .

Edge cases

Ensure you thoroughly test your integration, including scenarios with:

  • Incomplete data
  • Invalid data
  • Duplicate data (e.g., retry the same request to see what happens)

Timeouts and repeat transactions

There will inevitably be times when no response is received due to connection issues or similar. When this occurs, Zip expects transactions to be re-attempted until a valid response is received or until a timout period expires.

Non-Transactional API calls

Some API calls can simply be re-sent without the need to identify that the call is a retry. The /checkouts endpoint for example can be repeatedly called with the same references and payload info with no issue. The timings of these has little impact as each request is new, and independent of the first failed call.

Transactional API calls

Other API calls require retry attempts to be identified to prevent double charges and also to avoid duplicate reference errors for the order reference being passed.

Any Transactional API calls to the /charges or /refunds endpoints for example will need to use the same 'Idempotency-key' in the header as the original request to flag this.

POST /checkoutsNon-transactional
POST /chargesTransactional
POST /charges/{id}/captureTransactional
POST /charges/{id}/cancelTransactional
POST /refundsTransactional

The timings of these retries is reccomended as follows:

Attempt NumberDelay before attempt (seconds)Timeout period (seconds)Total Time elapsed (seconds)

If this total 60 seconds has elapsed without a valid response, queue asynchronously and present “Order is still being processed, you will receive an email once complete” message if possible.

Otherwise – if outside your overall page timeout set status of Order in your system to “Charge Error” and manually reconcile later.

Review your logging

We recommend that you log all important data on your end. Your own logs will be a extremely valuable if your server has a problem contacting Zip or there's an issue with your API keys—both cases would prevent us from logging your request.

Regularly examine your logs to ensure they're storing all the information you may need and they aren't storing anything of a sensitive nature. Check if you identify any recurrent error which may require some adjustment in your integration.

Change and secure your API keys

Make sure you keep your API credentials private.

Error codes

The API uses consistent error responses and follows REST status code conventions where appropriate.

In order to provide more information or a sub-division of status codes an Error object is returned for all non 2xx status codes. The Error object contains a more specific code and error message.

The status codes that may be returned from the API are detailed below:

Status codeDescription
2xxOK Everything worked correctly.
400Bad Request There is an error in the request object.
401Unauthorized No valid API key provided.
402Request Failed Request could not be processed, see error code for more information.
403Forbidden Operation is not allowed (customer did not authorise action).
404Not Found The resource does not exist.
409Conflict The request is a duplicate of a previous request
429Too Many Requests Requests are rate limited - you are making too many requests.
5xxServer Error An error has occurred on zipMoney's end.

Specific error codes for each endpoint are detailed on the appropriate endpoint page.

For BadRequest responses you can find the specific error detail in the details section of the Error object.

  "code": “xxx_xxxx",
  "message": “Error description",
  "items": null



Once you are confident you have completed your integration, it's time to complete certification