Skip to main content

Account access consents

Data API concepts start with the idea of account access consent regardless of whether you were to use “/accounts”, “/balances” or “/transactions” endpoints. Consent creation and authorisation by end-users is a permission to third-party providers (Fena, in our case) to access and use data from users' bank accounts.

The flow to create and authorise consent is pretty simple. API spec can be found here. First, you are calling our POST /data/access-consents endpoint with appropriate data for us to construct and register your intent with the bank. If successful, we will return authorisation URI to which your end-users should be redirected to authorise the consent on the bank side. After successful authorisation we will redirect your end-users to the URI supplied in the payload of the above mentioned POST request (recommended way) or to the default redirect URI of the customer credentials of which you were using to make a call. id, status and customerConsentId will be supplied as a query string alongside the message which will contain string result of the flow which can be shown to end-users.

Also, we will send webhook message to the webhook URI either you’ve supplied with the POST request (the same way as with redirect URI) or to the default webhook URI of the customer if one exists. Payload will consist of following keys: eventType (it’s value will correspond to the flow for which you are getting the message, new consent, call to accounts, balances or transactions endpoints), time (server time of the event), message (human-readable message) and consentId. If your system doesn’t need this feature you can just omit Option.WebhookUri parameter in POST request’s payload and we won’t send an event upon completion of the flow.

Reconsent​

AIS consents created after *March 2022 MUST BE reconsented (reconfirmed) by users every 90 days. It can be as simple as showing a banner or a pop-up to users that asks them whether they agree that their data will be accessed using the AIS consent that they have authorized earlier.

Provider API sends 4 webhooks that notify API clients that the consent is soon to be expired: when it's less than 30 days left to reconfirm the consent, less than 14 days, less than 1 day, and when it's expired. When users reconfirm the consent the timer resets and the 90-day period starts over. To reset the timer a POST request to /data/access-consents/<CONSENT_ID>/reconsent should be sent.

If the expired webhook was sent, API requests will not be processed until the consent is reconfirmed.

Webhook payload:

{
      "type": "account-access-consent-reconsent-notification",
      "consentId": <CONSENT_ID>,
      "customerConsentId": <CUSTOMER_CONSENT_ID>,
      "consentExpiresAt": null,
      "timeLeftToReconsent": <ENUM: ["less_than_30_days", "less_than_14_days", "less_than_1_day", "expired"]>
}

Example flow:

API client gets a webhook saying that it is less than 30 days left to reconfirm a consent. A pop-up with Accept and Decline buttons is displayed to a user that authorized the consent asking whether they agree to the API client using their data for next 90 days. If the Accept button was clicked - the POST reconsent API request is sent to Provider API.

Extended flow​

After successfully creating and authorising account access consent you will get a chance to call /accounts, /balances or /transactions endpoints with the ID of newly created consent. As your end-user gave you permission to view their account details you now can pull data related to their bank account. You can find details of above mentioned endpoints in their appropriate sections.

On the other hand, we have something called “Extended flow”. The idea behind this is to merge 2 flows that otherwise are running separately and need 2 calls from the client side. In the payload of creating a new account access consent we have an optional parameter called flow. It’s an enum with values accounts, balances or transactions. If you supply one of these in the payload to create account consent then at the end of the flow you’ll get the same redirect as is the case with simple flows and additionally you’ll get the data from the endpoint you’ve selected through the flow parameter wrapped in the webhook message. Webhook message payloads are exactly the same as if you had called the endpoints with a separate call. If you omit the Option.WebhookUri parameter you won’t get a webhook message nor at the end of extended flow nor at the end of any Data API endpoints called with that specific consent ID as an argument. The only exception being if your credentials on the Fena side have associated default webhookUri. All the details and the API spec of Data API related endpoints can be found here

note

For balances and transactions values of the flow field you already need to have the bank's side accountId. If you don't have them, follow the usual approach to obtain balances or transactions:

  1. Create a consent without the flow set or with the flow set to accounts so you don’t need to know the accountId beforehand.
  2. When the consent gets authorized if the flow: accounts value was set you will receive a webhook with bank accounts of the end-user. If you didn't set the flow to accounts, simply make a GET call to /accounts endpoint to obtain the accounts.
  3. Using the acquired accountId make a GET request to obtain balances or transactions data. :::