Reporting the sale: Using our API
All sales of Refund Cover need to be reported to us in order to be eligible. Sales should be reported as soon as possible after being made.
Before you begin
You will require an account with Refund Cover and credentials (vendor ID and API key) for our UAT environment. Please contact your account manager if you do not have them.
We will also provide a login for the client dashboard, where you will be able to view the results of your API requests.
API format
Our API is a RESTful web service over HTTPS. All requests take the form of JSON data in a POST body, combined with HTTP headers. Responses are JSON data. The character set is UTF-8.
When to make the request
We strongly recommend that calls to our API occur as a background task after you have completed the purchase flow. This not only prevents any delay from affecting your checkout performance, but also allows you to retry failed requests. In essence, the API call should be treated like a webhook.
Rate limits
While our API is designed to handle a high volume of requests, each account is rate limited and if you experience high sales volume, you may hit a rate limit and receive an HTTP 429 error. Please contact your account manager if you encounter this and we can explore a higher rate limit or switching to a batch approach.
Failed requests and retries
We recommend that you record successful completion of API calls against each purchase so that you can identify and re-send any failed calls.
If the purchase_reference exists in your account already, we will return an error, so you may safely retry if you are in doubt that a purchase was recorded.
Note that you cannot cancel or change a sold:false to sold:true status, nor undo a cancel request.
Timeout
If no response is received after 10 seconds, timeout and try again later.
UAT endpoints
- Report a sale
- https://uat-api.coverplatform.net/sale
- Cancel a sale
- https://uat-api.coverplatform.net/cancel
Production endpoints
- Report a sale
- https://api.coverplatform.net/sale
- Cancel a sale
- https://api.coverplatform.net/cancel
Note that you will need a separate API key for production.
API versions
All requests should include a version header. If the major number changes, that indicates a breaking change.
| API version | Date | Notes |
|---|---|---|
| 1.0 | April 2024 | Initial release |
Security
All connections should be via HTTPS on port 443. We do not redirect HTTP requests or respond on any other port.
Do not embed your API key inside client-side code – always call our API server-side.
Your production API credentials should be stored in a suitable secret store and not in your code.
If you believe your API key has been exposed, contact your account manager to obtain a new key. We will allow a brief overlap of the old and new keys to maintain access.