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)

Non-Transactional API calls

Some API calls can simply be re-sent without the need to identify that the call is a retry. The GET /purchaserequests API endpoint for example can be repeatedly polled to determine the order status, with no issue.

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 POST /purchaserequests or /refunds endpoints for example will need to use the same 'client-request-id' in the header as the original request to flag this.

The timings of these retries is reccomended as follows:

Timeouts and repeat transactions

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

After this time has elapsed without a valid response, you must send a void for the transaction.

Voids

Connection errors and timeouts can occur for any number of reasons.

In these circumstances – the client cannot be sure whether the request was processed by the server or not, and as such must reverse any transaction that may have occurred.

This will likely need to be undertaken in an asynchronous manner. Ie; in the background as your regular POS/terminal transactions continue.

Reversals voids

After any connection errors, POS failures or timeouts after repeat attempts, you should handle the void by queueing up a background job to void the attempted transaction by calling the relevant void method (for purchase or refund) –

Refer to the API specification section for details on how to make each of these calls.
If you do not get a valid response for the void request then you must repeat the void call for that purchase request or refund at a regular interval that slowly drops off in frequency (perhaps once every minute for first 5 minutes, then once every 5 minutes for next 60 minutes, then once every 60 minutes for remaining day), until successful.

In parallel – the operator would then ask the customer to repeat the purchase or refund.

Cancel voids

In any situation that the POS abandons an order attempt (after polling with a 'Pending' response for a given time), within the Zip 60 second allowance for a customer to Confirm on their device, a VOID must be sent.

This will ensure that if the customer Confirms AFTER the POS abandons the attempt, they will see an error message instead of an order confirmation.

Without sending a void in this scenario, there is a chance orders will go through and they will appear completed on the POS.

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