Consents

A consent connects an end-user to a bank and must be created to retrieve account information. Each consent will connect one end-user to one bank. Multiple consents are required to access multiple banks for a single end-user.

Consent lifecycle

A consents can be in different states

  • Created: A session to create a consent has been started
  • Started: Someone has initiated the consent creation flow
  • Authorized: The consent is ready to be used
  • Expired: The consent has expired
  • Revoked: The consent has been revoked and is no longer available

A typical lifecyle can be as follows:

Created
Started
Authorized
Expired
Revoked

Create consent

A brief overview of how to create a consent has been described in the Quickstart section.

The consents lifetime can be controlled by specifying the expiration date in the initial POST /consents call. The date cannot be longer than 3 months* in the future as this is the lifetime for a PSD2 consent specified by the EU directive. If no date is given the lifetime is set as far into the future as possible (currently 3 months*).

*This is based upon the PSD2 directive and will be updated to 6 months in the near future.

Simplified PSU onboarding flow

The following illustrated a simplified view of how a consent is created.

  1. The client must create a new consent flow using the API.
  2. The client redirects the PSU to ZData where the PSU goes through the consent flow in a web UI.
  3. When the user has finished the consent flow he is either redirected to the client (if redirect url was provided) or shown a receipt page hosted by Aritma.
PSUClientZDataPOST /api/consents (create new consent flow)OK { redirectUrl, consentId, ... }Send user to consent flow (redirectUrl)Initiate onboarding processGoes through onboarding process<redirect to="" client="" receipt="" page=""> </redirect>PSUClientZData

When the consent flow has finished the consentId receieived in step 1 can be used to retrieve financial data. You can test the flow yourself by using our demo application.

Revoking consents

A consent can be revoked by calling DELETE /consents/{id}. This will effectively stop the billing period if a pay-per-consent model is used and the consent cannot be refreshed any longer.

End-user retracts consents (PSD2)

Another consideration all clients of the API should keep in mind is that end-users can retract their consents in the bank as specified in the PSD2 directive. Unfortunately banks do not notify about this and this will not end the billing period. If you the client use a consent that has been retracted by the end-user we will automatically update the status of the consent to expired and stop the billing period at that time.

A consent expires

A consent will expire at a given date as explained in the create consent section. The billing period will stop at this point.

Refreshing consents

A consent may be refreshed at any time as long as it has not been revoked. Either to renew an expired consent or push the expiration date of an active consent. The refresh action (PUT /consents/{id}/refresh) returns a redirect link and requires PSU action.

Note that consents that has been expired for a longer period are cleaned up and removed. Trying to refresh a consent that does not exist will return 404 and creation of a new consent is required.