Consent Journey - App Store

Obtain End-User consent in order to access Account Servicer Data

Overview

Before any data from an Account Servicer proposition 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 present to them the Consent request screen that details the data consents that are being requested. This is done via the Consent JourneyConsent Journey - The workflow provided by Tapico allowing your end-user to give consent for your application to access their financial data..

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


🚧

Do you have an Access Token?

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

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

Consent Capture Flow

 

1. Initiate the Consent Journey:

Initiate the consent journey by making a POST request to the /account-access-consents endpoint as follows:

{
  "externalUserId": "{{a_unique_identifier_to_represent_the_end_user}}",
  "accountServicerId": "98a9a9cc-a4c0-4a87-92ca-451f094941b1",
  "callbackUri": "https://www.yourplatform.com"
}

🚧

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

This is your Id that represents the End-User on your Application.

accountServicerId

This is the Id that represents the Account ServicerAccount Servicer - The entity that holds the account(s) that contains your end-user's account information, e.g. a bank like Natwest or a financial institution like Aviva. Tapico facilitates the connection between your application and the account servicer. that you wish to retrieve data from. An accountServicerId can be sourced from a variety of locations.

  1. The accountServicerId is passed as a parameter of the URL when the user navigates from a particular account servicer’s App Store when SSO has been implemented between your Application and the Account Servicer.
  2. You can call the GET /account-servicers endpoint to retrieve a list of all the available Account Servicers.
  3. The Id is displayed on the Account Servicers page on the Tapico developer Portal
Account Servicers Page on the Tapico Developer PortalAccount Servicers Page on the Tapico Developer Portal

Account Servicers Page on the Tapico Developer Portal

🚧

What happens if you do not include an accountServicerId?

If you do not include the accountServicerId in the POST request the redirectUri returned in the response will redirect the End-User into the default Consent UX Flow created and managed by Tapico. Where the End-User is invited to select their Account Servicer from a list. Once selected they will be redirected to the Account Servicer's portal to give their consent. This is what is referred to as the Long Consent JourneyLong Consent Journey - The Long Consent Journey is when the accountServicerId is not passed in as part of a POST /account-access-consent request. Therefore the default Consent UX Flow is presented to the End-User to select an Account Servicer to which they will be redirected to give their consent to share data with your Application..

This is in contrast to the Short Consent JourneyShort Consent Journey - The Short Consent Journey is when the accountServicerId is passed in as part of the POST /account-access-consent request. This means that the default Consent UX Flow can be skipped and the End-User is redirected directly to the Account Servicer where they can give their consent to share data with your Application. which is what we are implement under this guide.

callbackUri

The callbackUri is optional and if not provided, defaults to the value configured agains your Application on the Tapico Developer Portal.

Consent Request Callback URL can be configured on the Basic Details page on the Tapico Developer PortalConsent Request Callback URL can be configured on the Basic Details page on the Tapico Developer Portal

Consent Request Callback URL can be configured on the Basic Details page on the Tapico 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",
      "expiryDate": null,
      "id": "b1836f26-e872-4e85-96b7-16a7e3b58946",
      "status": "Created",
      "redirectUri": "https://staging.tapico.io/account-access-start/b1836f26-e872-4e85-96b7-16a7e3b58946"
    }
  ],
  "meta": {
    "correlationId": "795a3d8e-c37f-4739-95ee-b9528122eec4"
  }
}

As part of this process an Authorising-userAuthorising-user - See End User is created in the Tapico Platform, which represents the End-User from your Application who will be executing the Consent Journey and allowing your Application access to their data on their behalf.

You can see in the example response above the ID associated with the Authorising-User. This will be needed later to retrieve the account data from Tapico's Open Finance API.

🚧

Re-running Consent

In case of re-running a consent for the same End-User, the old one will be revoked and all the data associated with that consent will be deleted. 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

Your Application needs to extract the redirectUri returned in the POST /account-access-consent response. This will redirect the End-User to the consent approval screen for the relevant Account Servicer.

Account Servicer Consent ExampleAccount Servicer Consent Example

Account Servicer Consent Example

📘

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 - DRAFT for details.

When the End-User gives their consent. Two things will happen.

  1. The End-User will be redirected back to your Application. Landing in the location as per the 'callbackUri' set under section 1.1..
  2. A consent record will be created in the Tapico Platform. This is visible in the Tapico Developer Portal.
Consent Records are visible on the Consent page in the Tapico Developer PortalConsent Records are visible on the Consent page in the Tapico Developer Portal

Consent Records are visible on the Consent page in the Tapico Developer Portal


Did this page help you?