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 .
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)
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.
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.
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:
|Delay 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.
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.
Make sure you keep your API credentials private.
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:
|OK Everything worked correctly.
|Bad Request There is an error in the request object.
|Unauthorized No valid API key provided.
|Request Failed Request could not be processed, see error code for more information.
|Forbidden Operation is not allowed (customer did not authorise action).
|Not Found The resource does not exist.
|Conflict The request is a duplicate of a previous request
|Too Many Requests Requests are rate limited - you are making too many requests.
|Server 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.
"message": “Error description",
Once you are confident you have completed your integration, it's time to complete certification
Updated 9 months ago