Instalments Workflow

This feature allows customers to pay for an insurance product that covers them for a period of time (annually) in instalments instead of up-front.

The above diagram illustrates the API calls and webhook events made in order to record the payment of each instalment.

Policy Instalment Options

When a quote request is made for a policy that allows payment to be made in instalments an instalment_plans property will be returned in the API response.

The amount to surface to the customer is reflected in the first_instalment_amount attribute.

{
    "quotes": {
        "0": {
            ...,
            "instalment_plans": [
                {
                    "name": "1year-monthly",
                    "label": "1Year-Monthly",
                    "amount": 308.0,
                    "first_instalment_amount": 25.67
                }
            ]
        }
    }
}

Confirming Instalment Plan

The instalment plan can be selected by provide the desired instalment name in the instalment_plan attribute during a booking request.

{
    "quotes": [
        {
            "id": "UUID",
            "instalment_plan": "1year-monthly"
        }
    ],
    "policyholder": {
        ...
    }
}

Processing a Periodic Payment

Depending on the payment services provider a periodic payment will generate a webhook event. This event should be processed by your platform and the following API calls should be made to the instalments endpoint.

Fetching Payment Plan Details

In order to record an instalment the correct instalment_id needs to be provided. The next scheduled instalment_id can be obtained by performing a GET request against the instalment endpoint.

Fetch Instalment Details

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

Returns instalment details including the payment schedule.

Path Parameters

Name	Type	Description
partner_id	string	Unique Partner ID
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

{
    "quotes": [
        {
            "id": "95230b02-9f7f-463f-be6d-81b46e3c5955",
            "next_payment": {
                "id": "ba718007-964a-4115-b0f9-f746f20d6bdd",
                "number": 2,
                "quote": "95230b02-9f7f-463f-be6d-81b46e3c5955",
                "period_start_date": "2021-09-25T02:47:00Z",
                "period_end_date": "2021-10-24T02:47:00Z",
                "status": "UNPAID",
                ..
                "tax": {
                    "taxes": [],
                    "total_amount_without_tax": "7.50",
                    "total_amount_without_tax_formatted": "€7.50"
                },
                "surcharges": {},
                "payment_failures": null
            },
            "paid_until": "2021-08-25T02:47:12.115862Z",
            "payment_schedule": [
                {
                    "id": "2b0c7a96-be7a-450b-86b1-04feb5813b37",
                    "number": 1,
                   ....
                },
            "total_amount_paid": 7.5,
            "total_amount_due": 82.5
        }
    ],
    "currency": "USD"
}

Confirming an Instalment Transaction

To confirm the instalment once a payment attempt has been made a request to the following endpoint needs to be made containing the instalment_id from the previous step.

Confirm Instalment

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

Confirms the instalment providing whether the payment was successful or not.

Path Parameters

Name	Type	Description
partner_id	string	Unique Partner ID
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

204: No Content

{
    // Response
}

Request Payload

{
  "quotes": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "instalment_id": "286b1dc2-e2f0-40ea-bc39-079ef019b7d0",
      "instalment_number": 0,
      "payment_attempted_date": "2019-08-24T14:15:22Z",
      "payment_status": "PAID",
      "payment_failures": {}
    }
  ]
}