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

NameTypeDescription

partner_id

string

Unique Partner ID

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

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

NameTypeDescription

partner_id

string

Unique Partner ID

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

{
    // Response
}
{
  "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": {}
    }
  ]
}

Last updated