# 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="https://1637184925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LsQ_haI87nzaKJrV84e%2Fuploads%2Fgit-blob-162c0c3811cb6421aac75e04394e3f52a4737b60%2Fplatforms-xcover-instalmentsWF-monthlyisntalments-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1637184925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LsQ_haI87nzaKJrV84e%2Fuploads%2Fgit-blob-0ce0be89edc715d3f3b22ad8319d1e754c60c8f6%2Fplatforms-xcover-instalmentsWF-monthlyisntalments-light.png?alt=media" 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 %}