Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
How will customers pay for their policy premium?
Most XCover partners operate their own shopping cart, checkout, and payment collection processes. From a customer experience perspective, a single itemised purchase transaction is preferable (for example a travel booking along with the insurance policy).
Please refer to the Single Payment page for more information.
In rare circumstances, Partners and XCover may agree to operate a dual payment integration approach. This results in two transactions against the same payment method of the user in quick succession. The merchant of record for the product/service remains the Partner, and the merchant of record for Insurance remains XCover. If this is your preferred integration method, please speak to your Partnerships manager or Client Solutions Engineer.
Please refer to the Dual Payment page for details on implementing this workflow.
In some circumstances, Partners may choose to integrate split payments (by using an approved payment provider) to split the transaction after payment collection, ie. One payment, two merchants (Partner and XCover), and two settlements (Partner and XCover). If this is your preferred integration method, please speak to your Partnerships manager or Client Solutions Engineer.
Presenting the Insurance/Protection offer in the purchase path
Partners will often present an insurance offer after customers have selected a core product (such as a laptop, travel booking, event tickets, etc.). There are key components to presenting an insurance/protection offer, where 1-3 are dynamic from API response, and the items under 4 are static (provided or approved by Cover Genius CSE):
Price
Disclaimer
Policy wording link
Product name, inclusions, panel content, Trustpilot banner, and graphical elements.
Cover Genius offers a standard or customised design structure optimised for the partner specific use case (ie. Travel, Parcel, Ticket, Retail, etc.). A Travel example is presented below:
Legend: Red = Static content , Blue = API response
A Trustpilot.com rating for XCover, demonstrates reliability
B Inclusions content, taken from XCover supplied content
API Response content:
1. Price, per ticket (division of "total_price"
by number of travellers/units) or full price if in "add" button ("total_price"
)
2. Disclaimer, taken from "content":{ "disclaimer"}
field
3. Policy Wording, taken from the "pds_url"
quote response field, for example: "view wording" as a hyperlink of: "https://www.xcover.com/en/pds/ABCD-1234-INS"
Generally, the quote display should address:
Customer relevance - Does the quote/product presentation make sense for this purchase flow?
Compliance and regulatory requirements - Does the offer meet requirements for disclaimers, price, statements of fact, and availability of policy wording?
Marketing copy and trust - Is the offer likely to be understood and selected by the customer? Is the offer trusted/compelling?
Sending a Fast Quote Request
The Fast Quote endpoint is available to partners who meet specific criteria outlined by Cover Genius. Please contact your assigned Client Solutions Engineer (CSE) to discuss use of the Fast Quote endpoint.
Fast Quote request is commonly issued at product pages to display selective information about the policy which could include:
Policy Price
Product Disclosure Statement
Legal Disclaimer
Inclusions/Exclusions
Making a POST
request to the fast quotes
endpoint returns one or several insurance products based on the request. The request to the fast quotes
endpoint is a list (as shown below). At the top level of the request, include the common fields for the quotes like currency
, customer_country
, customer_language
along with boolean field fast quote
set as true.
Every Fast Quote request should have the minimum required information to get a quote for the specific Product. For instance, in the case of Product Insurance - we need the item category, price, name, description.
The response could have the policy details, static PDS and the price in the requested currency for the supplied parameters. This information can be presented to the customer to move them to the Booking stage.
Fast Quote is followed by Instant Booking as the next stage in the user journey where insurance is selected.
An example of fast quote request can be found below.
POST
https://api.xcover.com/x/partners/:partner_id/quotes/?fast_quote=1
This API call will retrieve the most relevant policies available for distribution
In the request body, you can send multiple quote requests. This means that in the case of a 200ok, you will get back a quote for each request. You only need to make one API call to get many quotes.
Sending a Quote Request
The Quote request details the required information of this attached main product so that an appropriate policy quotation can be generated. The response from the Quote endpoint can be used to display information about the policy which includes:
Policy Reference ID - Unique 13 letter code for each policy (id
eg. TXLDR-LH8UN-INS
)
Policy Price and Applicable Taxes
Product Disclosure Statement
Legal Disclaimer
Inclusions/Exclusions
Certificate of Insurance (COI)
Benefits, Limits and Excess
Cover Amount
Making a POST
request to the quotes
endpoint returns one or several insurance products based on the request. The request to the quotes
endpoint is a list (as shown below). At the top level of the request, include the common fields for the quotes like currency
, customer_country
, customer_language
.
Every Quote request should have the minimum required information to get a quote for the specific Product. For instance, in the case of Product Insurance - we need the category, price, name, description.
The response has the insurance price and details about the policy in the requested currency for the supplied parameters. This information can be presented to the customer to move them to the Booking stage.
The response has a top-level ID that is identified by a unique 13 letter alpha-numeric string ending with -INS
suffix. There's also an individual ID assigned to each individual quote in the request. Both of these can be stored on the clients side to to cancel, modify and renew the policies during its lifecycle.
The initial status after the Quote Request is RECEIVED
For some integrations quote step can be skipped or quote responses can be cached, but we encourage all partners to implement price request via quote endpoint in order to enable dynamic product optimisations provided by BrightWrite platform.
An example of quote request can be found below.
POST
https://api.xcover.com/x/partners/:partner_id/quotes/
This API call will retrieve the most relevant policies available for distribution
POST
https://api.xcover.com/x/partners/:partner_id/quotes/
An example of requesting a QuotePackage with two policies for two separate products. The first element of the Request array is a Policy for a Laptop followed by a Mobile phone policy
The response under quotes
key in the body is zero-indexed based on the position in the request. The first element has an index of 0
in the response, the second element has an index of 1
and so on.
When you request a quote, we send you back a quote package ID (INS number) in the response body, which can be used to retrieve information about all the quotes in the quote package. This is useful incase you don't want to store the Quote response on your side.
GET
https://api.xcover.com/x/partners/:partner_id/quotes/:quote_package_id
The Quote Package ID is obtained during the Quote Request
PATCH
https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/
Use this endpoint to mutate an existing Quote in a Quote Package.
POST
https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/
The add
endpoint can be used with an already generated INS
(quote-package-id) to add new Quotes to an existing policy. For example: If the customer adds another Phone protection to their existing Product insurance policies, you could use this endpoint to add a new Quote to an existing Quote Package.
The add
method can only be used for Quotes in the RECEIEVED
status.
POST
https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/
The add
endpoint can be used with an already generated INS
(quote-package-id) to delete a specific policy, we need the ID of the Quote from the original request. Simply putting that id
in the request will delete the right policy. For example: If the customer remove a product with protection from their cart.
The remove
method can only be used for Quotes in the RECEIEVED
status.
Booking process overview
The Booking endpoint is used to confirm the purchase of the insurance offering.
If a customer has chosen to purchase the insurance product(s) offered in the previous Quote step the customer must complete the checkout process with payment being successfully collected before proceeding with the following steps to confirm and distribute the policy.
After customers complete the booking process and insurance premiums are collected by the partner a request to the booking endpoint must be made.
Validations:
1. Given the initial status after the Quote Request is RECEIVED
, when a booking request is submitted, the expected status returned in response payload after a successful booking request is CONFIRMED
.
2. The price field should also be validated, to confirm the final price matches the quote stage price.
3. The presence of an "errors" object in response payload indicates an important logic error in booking, that should be noted.
A CONFIRMED
INS is considered booked, sold, provisioned, and will result in a policy confirmation being submitted to the user.
POST
https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id
The booking endpoint accepts a JSON payload against the URI containing the quote package ID returned in the quote request. The payload consists of policyholder information (most likely the same as the customer) and a list of quotes selected for purchase. the most relevant policies available for distribution
The Instant Booking endpoint is available to partners who meet strict criteria outlined by Cover Genius. Please contact your assigned Client Solutions Engineer (CSE) to discuss use of the Instant Booking endpoint.
If a customer has chosen to purchase the insurance product(s) offered through your platform then a call to the Instant Booking endpoint should be issued after the insurance premium has been calculated and payment has been captured.
POST
https://api.xcover.com/x/partners/:partner_id/instant_booking/
The payload consists of information necessary to issue the policy (widely varying depending on policy type) and policyholder information
Using XCover elements, the work of coding to display quote response is removed.
A simple script is used as a wrapper for the quote request
If custom display settings are required, they may be applied using signals or taken from quote request variables (see ).
Using Content Delivery Network (CDN), offers are displayed within the purchase flow on partner site.
Response Signals are used to determine user interaction/purchase choices.
This approach reduces the up front development effort and any ongoing growth project maintenance, allowing for streamlined launch and optimizations
Important: Most display variations are handled by quote request attributes for example the currency display could be set as Indonesian Rp (IDR):
In some cases, partners may have custom display requirements based on experience settings or customisations. An examples of custom display settings is shown below:
In the above example, circled (blue) formatting for currency symbol is selected using custom set signals (symbol). Eg:
In the below example, the currencyDisplay config element is set to narrowSymbol
Overview of the payment process where the partner is the Merchant of Record (MoR)
Partners operating in markets that allow the collection of insurance premiums by non-insurance companies may use this method of premium collection. This is the most common approach for XCover partner integrations, and offers significant efficiency, process, and approval rate benefits.
If you are planning to sell insurance products to residents of the United States of America then it is likely the integration would use the unless the insurance products are travel or warranty related, in which case you might be eligible for a Travel Retailers or general warranty exemption. Please contact your assigned Client Solutions Engineer (CSE) for more information.
For partners planning to sell insurance products solely to residents of the Europe Union you might be eligible to become an Approved Representative of Cover Genius allowing you to collect premium. Otherwise you must use the . Please contact your assigned CSE for more information.
For partners planning to sell insurance products to residents elsewhere please contact your assigned CSE for more information on how to collect premiums if you wish to remain the Merchant of Record.
Optionally, Partners may choose to track the payment/checkout item using meta-data fields as indicated below, in the booking or instant booking request:
No integration steps are required for a single payment implementation approach
The Insurance opt-out workflow describes the API call that must be made in the case that XCover insurance is offered but not selected by the customer. The purpose of utilising the opt-out workflow is so Cover Genius can demonstrate conversion rate to the regulators ensuring the product and pricing is fit for purpose. It also enables XCover machine learning platform Brightwrite to deliver the optimal products at the optimal prices.
POST
https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/opt_out
The opt-out request does not require any data to be contained in the payload.
Overview of the dual payment process where Cover Genius is the Merchant of Record
Partners that are at a minimum of PCI DSS SAQ A compliant are able to utilise the XPay API to process the insurance transaction. This will make Cover Genius the Merchant of Record (MoR).
After a customer selects the insurance product and proceeds to the checkout stage, the payment information (credit card details) must be collected and transmitted through the customer tokens endpoint.
The XPay API uses a long lived JSON Web Token (JWT) which will be provided to you by the assigned Client Solutions Engineer (CSE).
POST
https://api.xpay.xcover.com/customer-tokens
This API call will tokenize the customers credit card details.
Note, the /cutomer-tokens endpoint will not charge the customer, just tokenise their payment details. The customer is charged on the subsequent /bookings API call.
After a successful response from the customer tokens endpoint, the partner must confirm the booking by sending a request to the booking endpoint with the customer_token_id
set to the id
from the previous step, this will charge the customer.
POST
https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id
This API call will retrieve the most relevant policies available for distribution
Once payment has been finalised policy documents, certificate of insurance will then be issued to the customer.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
Name | Type | Description |
---|
In the request body, you can send multiple quote . This means that in the case of a 201, you will get back a quote for each request. You only need to make one API call to get many quotes. The next example demonstrates this.
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
partner_id
string
Unique Partner Code
quote_package_id
string
Quote Package ID
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
partner_id
string
Unique Partner Code
fast_quote
boolean
true
Content-Type
string
application/json
Date
string
Current Datetime
Authorization
string
HMAC Signature
X-Api-Key
string
API Key
partner_id | string | Unique Partner Code |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
partner_id | string | Unique Partner Code |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
partner_id | string | Unique Partner Code |
quote_package_id | string | Quote Package ID |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
partner_id | string | Unique Partner Code |
quote_package_id | string | Quote Package ID |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api_Key | string | API Key |
partner_id | string | Unique Partner Code |
quote_package_id | string | Quote Package ID |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api_Key | string | API Key |
partner_id | string | Unique Partner Code |
quote_package_id | string | Quote Package ID |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api_Key | string | API Key |
partner_id | string | Unique Partner Code |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
partner_id | string | Uniquer Partner Code |
quote_package_id | string | Quote Package ID |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
Content-Type | string | application/json |
Authorization | string | Bearer {{JWT}} |
partner_id | string | Unique Partner Code |
quote_package_id | string | Quote Package ID |
Content-Type | string | application/json |
Date | string | Current Datetime |
Authorization | string | HMAC Signature |
X-Api-Key | string | API Key |
The XCover platform enables efficient, flexible, and compliant offer and sale of any line of insurance within a partner web experience.
Some examples include:
- A public facing Online Travel Agent selling flight and accomodation packages, with related travel and cancellation insurance.
- A merchant facing shipping management platform selling parcel and shipping insurance.
- An ecommerce retail marketplace facilitating sales and offering warranties and or insurance policies for relevant products.
In most integrations XCover policies are attached to one or more main products or services.
An example of main product is a laptop purchased from an online store, flight tickets, hotel reservations, etc.
Depending on the partner integration, the insurance offering is typically placed in the main product booking path.
Common Request Flow:
1. Quote
The initial status after the Quote Request is RECEIVED
2. Booking
After customers complete the booking process and insurance premiums are collected by the partner a request to the booking endpoint must be made.
A CONFIRMED
INS is considered booked, sold, provisioned, and will result in a policy confirmation being submitted to the user.
A simple example of such integration is demonstrated below.