# 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.

<picture><source srcset="/files/GKLg93bTRAbBtKix2Kyi" media="(prefers-color-scheme: dark)"><img src="/files/E0juaitsAX5uFa3hYabI" alt=""></picture>

### 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.

```json
{
    "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.

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

<mark style="color:blue;">`GET`</mark> `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          |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

### 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

<mark style="color:green;">`POST`</mark> `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          |

{% tabs %}
{% tab title="204: No Content " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Payload" %}

```javascript
{
  "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": {}
    }
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.covergenius.com/xcover/instalments-workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.