API Specification

Cancellation Workflow

Cancel a specific policy booking

Cancelling a policy booking is used where a user no longer requires coverage, and has contacted the partner directly to cancel this policy.

For example: Cancellation of a Product insurance policy where the product is on-sold or no longer needed. Where a refund is due, the partner (depending on method of payment collection, and policy cooling off period) may need to provide a refund to the user. This calculated pro-rata refund for the user (where applicable) is returned in the Cancellation response.

Booking Retrieval

The first step is to obtain information regarding the customers purchased insurance, this step can be skipped if you have stored all relevant information about a customers insurance booking such as INS number, Quote IDs, price paid, etc.

Retrieve a Booking

GET https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

Retrieves a specific booking by providing the quote package ID.

Path Parameters

NameTypeDescription

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID (INS)

Headers

NameTypeDescription

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
    "id": "8WD8Y-LTEKE-INS",
    "status": "CONFIRMED",
    "currency": "USD",
    "total_price": 4.27,
    "total_price_formatted": "US$4.27",
    "partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
    "created_at": "2021-01-15T01:19:49.529799Z",
    "updated_at": "2021-01-15T01:19:59.773302Z",
    "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
    "security_token": "UiRlP-6bLfQ-1YLjR-ste66",
    "quotes": [
        {
            "id": "201eb11b-4494-40e8-97fa-e107c76501bf",
            "policy_start_date": "2021-01-17T13:00:00+00:00",
            "policy_end_date": "2021-01-19T13:00:00+00:00",
            "status": "CONFIRMED",
            "price": 4.27,
            "price_formatted": "US$4.27",
            "policy": {
                "policy_type": "event_ticket_protection",
                "policy_name": "Missed Event Cover (Generic)",
                "policy_code": "MECG0001",
                "policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
                "category": "event_ticket_protection",
                "content": {
                    "title": "Missed Event Cover for Justin Bibber",
                    "header": null,
                    "description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only  per ticket it covers you - and all ticket holders - if:",
                    "optout_msg": "",
                    "disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
                },
                "underwriter": {
                    "disclaimer": "This plan is arranged by XCover.com",
                    "name": "Cover Genius Pty Ltd"
                },
                "claim_selector_id": null
            },
            "insured": [
                {
                    "id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
                    "first_name": "Darin",
                    "last_name": "Sikanic",
                    "email": "[email protected]",
                    "region": null
                }
            ],
            "tax": {
                "total_tax": 0.0,
                "total_amount_without_tax": 4.27,
                "total_tax_formatted": "US$0.00",
                "total_amount_without_tax_formatted": "US$4.27",
                "taxes": []
            },
            "duration": "2 00:00:00",
            "benefits": [
                {
                    "description": "Updated Transalation",
                    "limit": 7.77,
                    "limit_policy_currency": 10.0,
                    "limit_formatted": "US$7.77",
                    "limit_policy_currency_formatted": "A$10.00",
                    "excess": 3.88,
                    "excess_policy_currency": 5.0,
                    "excess_formatted": "US$3.88",
                    "excess_policy_currency_formatted": "A$5.00"
                },
                {
                    "description": "Updated Transalation",
                    "limit_description": "Benefit Text Test 01",
                    "excess": 4.66,
                    "excess_policy_currency": 6.0,
                    "excess_formatted": "US$4.66",
                    "excess_policy_currency_formatted": "A$6.00"
                },
                {
                    "description": "Description",
                    "limit": 11.65,
                    "limit_policy_currency": 15.0,
                    "limit_formatted": "US$11.65",
                    "limit_policy_currency_formatted": "A$15.00"
                },
                {
                    "description": "Description",
                    "limit": 15.54,
                    "limit_policy_currency": 20.0,
                    "limit_formatted": "US$15.54",
                    "limit_policy_currency_formatted": "A$20.00",
                    "excess_description": "Excess Text Test 01"
                },
                {
                    "description": "Description",
                    "limit_description": "Benefit Text Test 02",
                    "excess_description": "Excess Text Test 02"
                }
            ],
            "commission": {
                "total_commission": 0.0,
                "total_commission_formatted": "US$0.00"
            },
            "created_at": "2021-01-15T01:19:49.523137Z",
            "confirmed_at": "2021-01-15T01:19:59.750719Z",
            "updated_at": "2021-01-15T01:19:59.763517Z",
            "cancelled_at": null,
            "is_renewable": false,
            "cover_amount": 77.7,
            "cover_amount_formatted": "US$77.70",
            "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
            "attachments": [],
            "files": [],
            "extra_fields": {},
            "next_renewal": null,
            "can_be_cancelled": true
        }
    ],
    "coi": {
        "url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
        "pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
    },
    "account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
    "policyholder": {
        "first_name": "Ben",
        "middle_name": null,
        "last_name": "H",
        "email": "[email protected]",
        "phone": null,
        "country": "US",
        "age": null,
        "address1": null,
        "address2": null,
        "city": null,
        "postcode": null,
        "region": "NYC",
        "secondary_email": null,
        "birth_date": null,
        "company": null
    },
    "total_tax": 0.0,
    "total_tax_formatted": "US$0.00",
    "total_premium": 4.27,
    "total_premium_formatted": "US$4.27",
    "partner": {
        "id": "87ZRF",
        "name": "Generic Partner",
        "title": "Generic Partner",
        "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
        "contact_url": "https://staging.xcover.com/en/about",
        "partner_url": "https://staging.xcover.com",
        "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
        "updated_at": "2020-10-28T07:48:24.671777Z",
        "xpay_refund_enabled": false,
        "subsidiary": {
            "id": "87ZRF",
            "name": "Generic Partner",
            "title": "Generic Partner",
            "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
            "contact_url": "https://staging.xcover.com/en/about",
            "partner_url": "https://staging.xcover.com",
            "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
            "updated_at": "2020-10-28T07:48:24.671777Z",
            "xpay_refund_enabled": false
        }
    },
    "customer_language": "en"
}

Booking Cancellation

Once a booking has been retrieved, check the can_be_cancelled flag is set to true in the response before issuing a cancellation request.

To ensure you refund the correct amount to the customer, it is recommended to first preview a cancellation and then confirm the cancellation once you have successfully issued the refund.

Cancel Booking

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel

The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a list of quotes selected for cancellation and an optional reason for the cancellation.

Path Parameters

NameTypeDescription

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

NameTypeDescription

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
  "id": "string",
  "status": "string",
  "quotes": [
    {
      "id": "string",
      "policy_start_date": "2020-09-25T05:31:10Z",
      "policy_end_date": "2020-09-25T05:31:10Z",
      "policy_cancellation_date": "2020-09-25T05:31:10Z",
      "policy_coolingoff_date": "2020-09-25T05:31:10Z",
      "status": "string",
      "price": 0,
      "refund_value": 0,
      "adjustment_fee": 0,
      "policy": {
        "policy_type": "string",
        "policy_name": "string",
        "policy_code": "string",
        "policy_version": "string",
        "category": "string",
        "content": {
          "title": "string",
          "header": "string",
          "description": "string",
          "optout_msg": "string",
          "inclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "exclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "disclaimer": "string",
          "disclaimer_html": "string"
        },
        "underwriter": {
          "disclaimer": "string",
          "name": "string"
        }
      },
      "insured": [
        {
          "id": "string",
          "first_name": "string",
          "middle_name": "string",
          "last_name": "string",
          "email": "[email protected]",
          "country": "AF",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "postcode": "string",
          "region": "string",
          "phone": "string",
          "age": 0,
          "birth_date": "2020-09-25",
          "metadata": {
            "property1": "string",
            "property2": "string"
          },
          "company": "string"
        }
      ],
      "created_at": "2020-09-25T05:31:10Z",
      "confirmed_at": "2020-09-25T05:31:10Z",
      "updated_at": "2020-09-25T05:31:10Z",
      "cancelled_at": "2020-09-25T05:31:10Z"
    }
  ],
  "policyholder": {
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email": "[email protected]",
    "phone": "string",
    "country": "AF",
    "age": 0,
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postcode": "string",
    "region": "string",
    "secondary_email": "[email protected]",
    "birth_date": "2020-09-25",
    "company": "string",
    "tax_payer_id": "string"
  },
  "pds_url": "http://example.com",
  "coi": {
    "pdf": "http://example.com",
    "url": "http://example.com"
  },
  "created_at": "2020-09-25T05:31:10Z",
  "updated_at": "2020-09-25T05:31:10Z",
  "total_price": 0,
  "total_price_formatted": "string",
  "total_refund": 0,
  "total_refund_formatted": "string",
  "total_tax": 0,
  "total_tax_formatted": "string",
  "total_premium": 0,
  "total_premium_formatted": "string",
  "currency": "str",
  "cancellation_id": "string",
  "confirm_before": "2020-09-25T05:31:10Z",
  "partner": {
    "id": "string",
    "name": "string",
    "title": "string",
    "logo": "http://example.com",
    "contact_url": "http://example.com",
    "partner_url": "http://example.com",
    "help_center_url": "http://example.com",
    "updated_at": "2020-09-25T05:31:10Z",
    "xpay_refund_enabled": true,
    "subsidiary": {
      "id": "string",
      "name": "string",
      "title": "string",
      "logo": "http://example.com",
      "contact_url": "http://example.com",
      "partner_url": "http://example.com",
      "help_center_url": "http://example.com"
    }
  }
}
{
    "quotes": [
        {
            "id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
            "reason_for_cancellation": "No longer travelling"
        }
    ]
}

Preview a Cancellation

An optional preview flag can be set to true in the booking cancellation request payload, the response will confirm a refund amount and timeframe required before cancellation can be completed.

It is important to note key details in the response, including thecancellation_id,total_refund amount and theconfirm_beforedatetime

Preview Cancellation

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel

The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a the preview flag set to true along with a list of quotes selected for cancellation and an optional reason for the cancellation.

Path Parameters

NameTypeDescription

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

NameTypeDescription

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
  "id": "8UHPK-ALPQT-INS",
  "status": "CANCELLED",
  "quotes": [
    {
      "id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
      "policy_start_date": "2021-01-07T18:18:48Z",
      "policy_end_date": "2021-01-17T15:45:00Z",
      "policy_cancellation_date": null,
      "policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
      "status": "CANCELLED",
      "price": 22.4,
      "refund_value": 22.4,
      "adjustment_fee": 0.0,
      "created_at": "2021-01-07T18:18:49.035218Z",
      "confirmed_at": "2021-01-07T18:18:59.940059Z",
      "updated_at": "2021-01-07T18:19:04.222570Z",
      "cancelled_at": null
    }
  ],
  "created_at": "2021-01-07T18:18:49.145872Z",
  "updated_at": "2021-01-07T18:18:59.958252Z",
  "total_price": 0.0,
  "total_price_formatted": "€0.00",
  "total_refund": 22.4,
  "total_refund_formatted": "22.40",
  "currency": "EUR",
  "cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
  "confirm_before": "2021-01-08T18:19:04.228699Z"
}

{
    "preview": true,
    "quotes": [
        {
            "id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
            "reason_for_cancellation": "No longer travelling"
        }
    ]
}

Confirm Cancellation

To confirm a cancellation that has been previewed a request to the following endpoint needs to be made.

Confirm Cancellation

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/confirm_cancellation

Confirm the previewed cancellation.

Path Parameters

NameTypeDescription

partner_id

string

Unique Parter Code

quote_package_id

string

Quote Package ID

cancellation_id

string

Cancellation ID

Headers

NameTypeDescription

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
  "id": "8UHPK-ALPQT-INS",
  "status": "CANCELLED",
  "quotes": [
    {
      "id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
      "policy_start_date": "2021-01-07T18:18:48Z",
      "policy_end_date": "2021-01-17T15:45:00Z",
      "policy_cancellation_date": null,
      "policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
      "status": "CANCELLED",
      "price": 22.4,
      "refund_value": 22.4,
      "adjustment_fee": 0.0,
      "created_at": "2021-01-07T18:18:49.035218Z",
      "confirmed_at": "2021-01-07T18:18:59.940059Z",
      "updated_at": "2021-01-07T18:19:04.222570Z",
      "cancelled_at": null
    }
  ],
  "created_at": "2021-01-07T18:18:49.145872Z",
  "updated_at": "2021-01-07T18:18:59.958252Z",
  "total_price": 0.0,
  "total_price_formatted": "€0.00",
  "total_refund": 22.4,
  "total_refund_formatted": "22.40",
  "currency": "EUR",
  "cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
  "confirm_before": "2021-01-08T18:19:04.228699Z"
}
PreviousInsurance Opt-OutNextModification Workflow

Last updated