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.

Cancellation Workflow

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

Name	Type	Description
partner_id	string	Unique Partner Code
quote_package_id	string	Quote Package ID (INS)

Headers

Name	Type	Description
Content-Type	string	application/json
Date	string	Current Datetime
Authorization	string	HMAC Signature
X-Api-Key	string	API Key

200

{
    "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

Name	Type	Description
partner_id	string	Unique Partner Code
quote_package_id	string	Quote Package ID

Headers

Name	Type	Description
Content-Type	string	application/json
Date	string	Current Datetime
Authorization	string	HMAC Signature
X-Api-Key	string	API Key

200

{
  "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"
    }
  }
}

Request Payload

{
    "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

Name	Type	Description
partner_id	string	Unique Partner Code
quote_package_id	string	Quote Package ID

Headers

Name	Type	Description
Content-Type	string	application/json
Date	string	Current Datetime
Authorization	string	HMAC Signature
X-Api-Key	string	API Key

200 The Quote will appear cancelled but note the cancelled_at field is set to null. To confirm cancellation send the cancellation_id in the subsequent /confirm_cancellation request

{
  "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"
}

Request Payload

{
    "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

Name	Type	Description
partner_id	string	Unique Parter Code
quote_package_id	string	Quote Package ID
cancellation_id	string	Cancellation ID

Headers

Name	Type	Description
Content-Type	string	application/json
Date	string	Current Datetime
Authorization	string	HMAC Signature
X-Api-Key	string	API Key

200 The Quote will appear cancelled but note the cancelled_at field is set to null. To confirm cancellation send the cancellation_id in the subsequent /confirm_cancellation request

{
  "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"
}