# Bank monitoring

Token.io provides the ability to monitor bank connections using the following methods:

- Notifications of the maintenance window in the API for planned outages
- Bank outage job for unplanned outages
- Bank status API for planned and unplanned outages


When there is a bank outage, the [Bank unavailable](#Bank_unavailable) screen is displayed in the Hosted Pages.

### Maintenance window in the API

The `maintainanceWindow` array in the [GET /banks](../../api/reference/Banks-v1#operation/GatewayService.GetBanks!c=200&path=banks/maintenanceWindow&t=response) and [GET /v2/banks](../../api/reference/Banks-v2#operation/GetBanksv2!c=200&path=banks/maintenanceWindow&t=response) responses is a list of maintenance windows planned for the bank. Additionally, it's possible for a maintenance window to be set for a bank if the bank is experiencing problems.

The `maintainanceWindow` statuses are used to indicate what the status of the bank will be during the maintenance window:

- `NO_DOWNTIME_EXPECTED` - the bank is currently connected, accepting API calls, and returning appropriate responses.
- `DOWNTIME_EXPECTED` - there is a planned outage between the `startTime` and `endTime` specified. This can be set manually in the Admin dashboard by a member of Token.io's Support team.
- `OUTAGE` - connection interrupted; the bank cannot currently accept API calls for this service between the `startTime` and `endTime` specified.


You can set up a [webhook](../sip/sip-v1/sip-v1-webhooks) to receive a Bank outage notification for the bank's availability. The webhook will return the following statuses for `previousOutageStatus` and `currentOutageStatus`:

- `AVAILABLE` - maps to a `maintenanceWindow` status of `NO_DOWNTIME_EXPECTED` or `DOWNTIME_EXPECTED`
- `COMPLETE_OUTAGE` - maps to a `maintenanceWindow` status of `OUTAGE`


When the `startTime` in the `maintenanceWindow` is reached, and the status is `OUTAGE`, Token.io will automatically change the bank availability status to `COMPLETE_OUTAGE` and send out a webhook notification to customers who have subscribed. Token.io will also set the bank as down in the Admin Dashboard and the [Bank unavailable](#Bank_unavailable) screen will be displayed in the Hosted Pages.

When the `endTime` is passed, Token.io will automatically change the bank availability status to `AVAILABLE` and send out a webhook notification to customers who have subscribe

### Bank outage job

Token.io's bank outage job runs every 15 minutes and checks for the percentage of transfers from each bank that have not progressed to a either a Failed or Successful status. The bank outage job checks for unplanned outages, *i.e.*, not those registered in the maintenance window.

The results of the bank outage job are recorded as:

- `AVAILABLE` - the bank is accepting API calls.
- `POTENTIAL_OUTAGE` - the bank may still accept API requests but some payment attempts may fail.
- `COMPLETE_OUTAGE` - the bank cannot currently accept API requests.


Token.io checks the percentage of non-processing transfers and processing instant-payment transfers (SEPA Instant and Faster Payments). An alert is triggered if either of these percentages reaches the threshold of 60%.

The percentage of **non-processing transfers** is calculated from the number of transfers with a status in either `INVALID_STATUS`, `PENDING`, `PENDING_EXTERNAL_AUTHORIZATION` or `FAILURE_EXPIRED` as a percentage of all payments.

The percentage of **processing instant-payment transfers** is calculated from the number of transfers with status of `PROCESSING` as a percentage of the total number of processing and final instant-payment (SEPA Instant and Faster Payments) transactions (*i.e.*, excluding transfers which haven't reached `PROCESSING`).

Based on these calculations, scenarios can be configured as follows:

- **Default outage** - where the threshold is set to 60% of transfers (non-processing and processing instant) over 1 hour, with a minimum volume of 100 transfers.
- **Low volume outage** - where there is a 60% failure (non-processing and processing instant) over 2 hours, with a minimum volume of 50 transfers.
- **Full outage** - where there is 100% failure (non-processing and processing instant) over 1 hour, with a minimum volume of 25 transfers.


Additional scenarios can be configured by Token.io as required.

If the criteria in these scenarios are met, Token.io will investigate. If, as a result of the investigation, it's established that a genuine outage is taking place, a [webhook notification](../sip/sip-v1/sip-v1-webhooks) with the status `COMPLETE_OUTAGE` is sent to customers who have subscribed to receive bank outage notifications.

Once the outage is resolved, Token.io will automatically send out a webhook notification to customers that have subscribed, confirming that the status is `AVAILABLE`.

For customers using Hosted Pages (HP), if a bank is experiencing a `COMPLETE_OUTAGE`, Token.io blocks the bank by displaying the [Bank unavailable](#Bank_unavailable) screen and the user will not be able to select it.

### Bank status API

You can get a summary report on the health status of all banks with regard to Token.io API connectivity/responsiveness or the status of a particular bank with a [GET /reports/banks/status](../../api/reference/Reports#operation/GatewayService.GetBanksStatus) call call or the status of a particular bank using [GET /reports/banks/{bank_id}/status](../../api/reference/Reports#operation/GatewayService.GetBankStatus). will respond with the corresponding `aisStatus` and `pisStatus`.

Possible states are:

- `LIVE` – bank is currently connected, accepting API calls, and returning appropriate responses, maps to `AVAILABLE`.
- `DOWN` – connection interrupted; the bank cannot currently accept API calls for this service, maps to `COMPLETE_OUTAGE`.


If there is a complete outage, Token.io sets the bank as down in the Admin Dashboard and the [Bank unavailable](#Bank_unavailable) screen will be displayed in the Hosted Pages.

If you want to know the status for *all* banks, the call will be:


```json
GET {{BASE_URL}}/reports/banks/status
```

For which you'll receive a corresponding response similar to this:

**Bank status response for all banks**


```json
{
    "banksStatus": [
        {
         "bankId": "ob-anybank1",
         "aisStatus": "DOWN",
         "pisStatus": "LIVE",
         "lastUpdatedAt": "2020-03-18T12:10:55.624Z"
        },
        {
         "bankId": "ob-anybank2",
         "aisStatus": "LIVE",
         "pisStatus": "DOWN",
         "lastUpdatedAt": "2020-02-11T09:21:29.078Z"
        },
        {
         "bankId": "ob-anybank3",
         "aisStatus": "DOWN",
         "pisStatus": "DOWN",
         "lastUpdatedAt": "2020-02-11T14:51:52.968Z"
        },
        ...
{
```

If you want to know the status for a *specific* Token.io-connected bank, here's the call:


```json
GET {{BASE_URL}}/reports/banks/{bank_id}/status
```

The response for this call will include the status for a single bank matching the `bank_id` included in the call.

**Bank status response for a specified bank**


```json
{
    "banksStatus": {
       "bankName": "Any Bank",
       "aisStatus": "DOWN",
       "pisStatus": "LIVE",
       "lastUpdatedAt": "2020-03-18T12:10:55.624Z"
    }
}
```

### Bank unavailable

When there is a bank outage, Token.io manually sets this in the Admin Dashboard and the Bank unavailable screen is displayed in the Hosted Pages.

Here is the screen displayed for Hosted Pages v1 during a bank outage.

|  |
|  --- |
| Bank unavailable |


This is an example of the screen displayed on the desktop for Hosted Pages v2 during a bank outage.

|  |
|  --- |
| Bank unavailable |


If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)