Skip to content
Get started
/
/
Bank monitoring
Last updated

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 screen is displayed in the Hosted Pages.

Maintenance window in the API

The maintainanceWindow array in the GET /banks and GET /v2/banks 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 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 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 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 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 call call or the status of a particular bank using GET /reports/banks/{bank_id}/status. 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 screen will be displayed in the Hosted Pages.

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

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

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

Bank status response for all banks

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

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

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

Previous page
Next page