Consent Journey - App Store

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

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 JourneyConsent Journey - The workflow provided by Tapico allowing your end-user to give consent for your application to access their financial data. to gain authorisation.

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.

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://sandbox.tapico.io/api/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 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.

  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 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 End-User will be sent into the default Consent UX Flow created and managed by Tapico, 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 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..

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 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",
      "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-UserAuthorising-User - A user of your application who is also a user of one or more Account Servicers. The Authorising User is the person who authorises your application to access data on their behalf from Account Servicer Platforms. See also: End-User. record, which represents the End-User who is granting consent. It is the primary context through which to access data from the Tapico Open Finance API.

The externalUserId provided in the request is used to automatically create the Authorising-User entity in the Tapico 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.

Example Account Servicer Consent Authorisation PromptExample Account Servicer Consent Authorisation Prompt

Example Account Servicer Consent Authorisation Prompt

📘

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 Tapico Platform. This is visible in the Tapico 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.
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?