Financial data consents

Learn more about how to manage consents when retrieving financial data from a user's bank.

Status transitions

The consent status value for AIS consent depends on:

• the type of authorisation required (dependent on the Institution and PSU) during the authorisation flow - e.g. Redirect, Decoupled or Embedded
• the success or failure of the authorisation process
• the actions that are performed by the TPP, Institution or PSU after an AUTHORIZED state has been reached

Status UNKNOWN: The default value of the enum.

Re-authorisation

An AIS consent-token is valid for up to 90 days before requiring secure customer authentication (SCA) from the user again.

You can request re-authorisation of a consent using the Re-authorise Account Consent endpoint.

You should use this:

• when a consent-related failure keeps occurring (e.g. 401 status code) despite it being in AUTHORIZED state
• to increase the duration of the consent prior to it expiring while maintaining the original feature scope requested
• to re-authorise a Consent in the EXPIRED status
• to enable a greater history of financial transactions to be retrieved (i.e. when a bank limits these to the first 5 minutes after consent creation)

NOTE: For UK institutions, due to new regulation, you may be able to use reconfirmation instead.

Consent status

If re-authorisation is successful, the status of the Consent will be AWAITING_RE_AUTHORIZATION. The consent-id and the consent-token don't change.

If re-authorisation fails, the status will remain as it was.

Historical data

Different institutions can enforce their own restrictions on some endpoints when obtaining financial data. The main example is when requesting historical (older than 90 days) transactional data using GET Transactions. Institutions can limit the time in which you can make a request for historical data to as little as 5 minutes from when the authorisation was made. After this time, your requests for historical data will be rejected.

We recommend that if you need historical data, that you retrieve and store it in the first 5 minutes of obtaining the consent-token.

Reconfirmation (UK only)

For UK institutions, all regulated AISPs are now responsible for obtaining reconfirmation of consent from their customers every 90 days for continued access to their data. This is part of a FCA regulatory change for UK institutions.

You should use this:

• when a consent-related failure keeps occurring (e.g. 403 status code) despite it being in AUTHORIZED state
• to extend the duration of the Consent when the User has provided reconfirmation while maintaining the original feature scope requested

NOTE: Banks may still require re-authentication if they haven't implemented reconfirmation yet or at their discretion in specific circumstances.

If you are a regulated AISP (you are operating under your own licence), the reconfirmation of your users' consent needs to be captured as part of your user management. The consent doesn't need to be provided via SCA but it does need to be explicit. For example, a user selects a checkbox to confirm consent. You may want to use Yapily's consent object fields to manage user consents.

If you are a Yapily Connect customer, Yapily is required to confirm and record the reconfirmation of consent from your users before granting you access to their data. Yapily has built a new API endpoint that you must call in order to confirm you have received reconfirmation from the user.

Reconfirmation of consent API endpoint

You must call the Extend Consent endpoint to indicate to Yapily that reconfirmation of consent from the user has occurred.

You must include the date and time you collected reconfirmation from the user in the lastConfirmedAt field in the request body.

The request will fail when:

• lastConfirmedAt is a future date
• lastConfirmedAt is earlier or the same as the current date and time for this consent
• consent status is not AUTHORIZED
• consent type is not AIS

If successful, returns a consent object.

Consent object

There are 2 attributes on the consent object to help manage user consents:

• lastConfirmedAt - the date and time that the PSU last confirmed access to their account information, either through full authentication with the institution or through reconfirmation with the AISP
• reconfirmBy - the date and time by which consent needs to be reconfirmed in order to ensure continued, uninterrupted access to the account information

These attributes are returned on all API endpoints that return a consent object.

If you don't receive reconfirmation from the user by the reconfirmBy date, then Yapily will prevent further access to the user's data. You can still capture reconfirmation after this date to resume data access, but you will not be able to access it in the interim.

NOTE: If you are a regulated AISP, you'll still receive these additional attributes in the consent object so you can use Yapily for your consent management. However, Yapily will not prevent access to account information after the reconfirmBy date if reconfirmation has not been received.

Consent status

If reconfirmation is successful, the status of the Consent will remain AUTHORIZED. The consent-id and consent-token don't change.

If reconfirmation fails, the status will remain as it was.

If the institution has not implemented reconfirmation yet, re-authorisation is required and the status of the Consent will be AWAITING_RE_AUTHORIZATION.

Revoked Consents

At any time, the user can revoke their consent directly in the Institution, which makes the consent token unusable.

In this case, the Consent status may still display as AUTHORIZED but will return 403 Forbidden errors when you attempt to use it to obtain financial data.

To regain access to their account data, you need to create a new consent using the Create Account Authorisation endpoint.

Deleting Consents

Yapily also provides the means to delete a Consent from the api using the Delete Consent endpoint.

If the user explicitly opt-outs of consent, we strongly recommend you call the endpoint to delete the user's consent. By default, this will attempt to delete the Consent both in the Yapily system and from the Institution. If this is not supported by the Institution, the Consent will only be deleted from the Yapily system.

Any access the user's data in the future, will then require the user to submit a new consent.