Overview

Before any data from an Account Servicer can be shared with your Application, the End-User must consent to do so. Therefore the very first time the End-User logs into your Application you must send them through the Consent Journey to gain authorisation.

Below is a step-by-step walk-through of how to capture End-User consent using the default Consent Flow.

🚧

Do you have an Access Token?

Before you can make any calls against the Open Finance API you need to get an access token.

It must be included in the Authorization header of your request.

Short Consent Flow

For the App Store use case we recommend the 'Short' consent flow which bypasses user selection of the Account Servicer. This is because the user will arrive at your application from the App Store with a pre-selected Account Servicer.

The landing request to your App will include a query param accountServicerId denoting their Account Servicer of origin.

This value should then be extracted and included in the subsequent request to initiate the consent journey.

1. Initiate the Consent Journey

Initiate the consent journey by making a request to POST /Account-access-consents.

Example request:

curl -X POST 'https://api.sandbox.tapico.io/v1/account-access-consents' \
-H 'Content-Type: application/json' \
-H 'Region: EU' \
-H 'Authorization: Bearer eyJhbGc.CJkPD9.lqjnVzo1zx7B-tg' \
-d '{
    "externalUserId": "{{unique_user_id_in_your_system}}",
    "accountServicerId": "98a9a9cc-a4c0-4a87-92ca-451f094941b1",
    "callbackUri": "https://yourplatform.com/callback"
}'

🚧

Does the region in your header match the region in the access token?

The region within header for the POST /account-access-consents call must match the region of the access token obtained under the POST /oauth/token call.

See Regions for more details.

1.1. Body Parameters

externalUserId - External User ID

This unique system identifier for the End-User in your Application.

accountServicerId - Account Servicer ID

This is the Account Servicer that you wish to retrieve data from.

1. You can call the GET /account-servicers endpoint to retrieve a list of all the available Account Servicers.
2. The ID is also displayed on the Account Servicers page on the developer Portal:

🚧

What happens if you do not include an accountServicerId?

If you do not include the accountServicerId in the POST request the End-User will be sent into the default Consent UX Flow created and managed by FNZ, where they can select their Account Servicer from a list. They'll then be redirected to the Account Servicer's portal to authenticate and authorise consent. This is referred to as the Long Consent Journey.

When an accountServicerId is supplied the Account Servicer selection screen is skipped and the user is sent directly to the Account Servicer's portal.

callbackUri - Consent Request Callback URL

The callbackUri is optional and if not provided defaults to the value configured against your Application on the FNZ Developer Portal.

1.2. POST /account-access-consent response

You'll get back a response which looks like:

{
  "data": [
    {
      "accountServicer": "98a9a9cc-a4c0-4a87-92ca-451f094941b1",
      "application": "24bc2545-25c8-490f-a258-37428b054f50",
      "createdDateTime": "2020-07-08T18:24:42.817Z",
      "authorisingUser": "4a4d1122-eb40-4a85-abb0-5830e5084d2b",
      "id": "b1836f26-e872-4e85-96b7-16a7e3b58946",
      "status": "Created",
      "redirectUri": "https://sandbox.tapico.io/account-access-start/b1836f26-e872-4e85-96b7-16a7e3b58946"
    }
  ],
  "meta": {
    "correlationId": "795a3d8e-c37f-4739-95ee-b9528122eec4"
  }
}

Consents are associated with an Authorising-User record, which represents the End-User who is granting consent. It is the primary context through which to access data from the Open Finance API.

The externalUserId provided in the request is used to automatically create the Authorising-User entity in the system. An entity will be created per distinct externalUserId provided - If the same externalUserId is provided multiple times, then the same Authorising-User record will be returned.

🚧

Re-running Consent

An End-User can only have a single active consent for a specific Account Servicer.

Any subsequent consent journeys you send your End-User through for the same Account Servicer will overwrite the existing consent - This means the new consent will generate new data represented by new entities with new ids in our system.

2. Redirect your End-User to capture their consent

Extract the redirectUri returned in the POST /Account-access-consents response. This will redirect the End-User to the consent approval screen for the selected Account Servicer.

📘

Which Consents are to be presented?

Like Account Servicers, only those consents that you have configured as part of your Application's setup will be presented. See step 4 Create an Application for details.

When the End-User concludes the consent journey the following things will happen:

1. The End-User will be redirected back to your Application, landing on the 'callbackUri' set under section 1.1..
   1. If the consent is successful and the user has granted consent, the query parameter success=true will be attached to the consent callbackUri.
   2. If the consent has NOT been successful, the query parameter error={error_code where error_code is either:
      1. access_denied - The user explicitly rejected the consent request by clicking "cancel" or similar on the AccountServicers website
      2. server_error - Catch all for any other system error with the process
2. A consent record will be created in the Platform. This is visible in the FNZ Developer Portal.
3. The consent record can also be fetched via GET /account-access-consents to determine whether the user has authorised it or not.