Refund Cover Integration Guide

Reporting the sale: Building an API request

Headers

All requests to the API must include these headers:

Content-Type: application/json
X-CoverPlatform-Vendor-ID: <your vendor ID>
X-CoverPlatform-API-Key: <your api key>
X-CoverPlatform-API-Version: 1.0

Requests take the form of a JSON block in a POST body, like so:

{
    "purchase_reference": "ABC1234",
    "purchaser_name": "Jane Smith",
    "purchase_title": "Family Fun Summer Festival",
    "protection_end_date": "2024-08-18",
    "currency_code": "GBP",
    "sold": true,
    "products": [
        {
            "product_type": "ticket",
            "title": "Adult Weekend",
            "price": 95.00
        }
    ]
}

Sale fields

Field	Required	Format	Description
`purchase_reference`	Yes	Text, max 25 characters	The unique reference for this purchase. This will be required to make a refund request, so should be a booking or order reference that the purchaser will know (and can read and type easily). This will also be used when making a cancel request.
`purchaser_name`	Yes	Text, max 50 characters, excess truncated	The name of the purchaser. This is used to identify a customer making a refund request if they do not know their purchase_reference.
`purchase_title`	Yes*	Text, max 50 characters, excess truncated	The title of the event, name of the venue or the service being purchased. This may be displayed to the purchaser when making a refund request to help identify the purchase to refund.
`protection_end_date`	Yes	ISO 6801 date YYYY-MM-DD	The date of the event, visit, or accommodation booking. If the booking is for more than one day, use the last date. Must be within 15 calendar months of the sale of Refund Cover.
`currency_code`	Yes	ISO 4127 Three character code	The currency used for the purchase. Must be one of our supported currencies.
`sold`	Yes	Boolean (true/false)	If the purchaser accepted the offer. Used to track conversion.
`products`	Yes	A list of products

Product fields

Field	Required	Format	Description
`product_type`	Yes	Text, one of `["ticket", "accommodation"]`	The product type.
`product_title`	Yes*	Text, max 50 characters, excess truncated	The title of the product being purchased. This may be displayed to the purchaser when making a refund request to help identify the product to refund.
`product_price`	Yes	Decimal, max 7 chars	The price of the product.

Fields shown as Yes* above are required, however they are only used to assist in identifying and processing refund requests.

Maximum purchase value

The maximum purchase value (the sum of product_price) must be less than £20,000 GBP or equivalent.

Duplicate products

List each product individually, even if they are the same, as a purchaser may request a refund for just one attendee in their booking.

So for example, if you sold 2 tickets titled “Adult Weekend Pass” which cost 9.99 each:

// This is correct
[
    {
        "product_type": "ticket",
        "product_title": "Adult Weekend",
        "product_price": 9.99
    },
    {
        "product_type": "ticket",
        "product_title": "Adult Weekend",
        "product_price": 9.99
    }
]

// This is incorrect
[
    {
        "product_type": "ticket",
        "product_title": "2x Adult Weekend",
        "product_price": 19.98
    }
]

Validation

We will validate your request and if there is an issue, return a 422 error code with an the affected fields listed and explaining the issues found.

Where format shows “excess truncated”, this will occur silently without any error being shown.

Extra fields in the request will be ignored.

Language

purchase_title and product_title may be displayed to the purchaser when making a refund request to help identify the purchase to refund, therefore they should be reported in the language the purchaser used when making the purchase.

Appendix