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.

The timings of these retries is reccomended as follows:

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:

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
}

📘

Certification

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