DirectID Developer Documentation

Download OpenAPI specification:Download

Introduction

Welcome to the DirectID developer documentation.

There are two key integration points: DirectID Connect, which will prompt your users to select a bank and walk them through the consent and authentication stages, and the DirectID Data API that you can use to interact with users, consents and bank data. Both APIs return data in JSON format.

DirectID Connect

Overview

DirectID Connect is the mechanism by which users provide their consent for us to retrieve their banking information on your behalf. It is a hosted web UI that allows a user to search for their financial institution, select it, provide consent to share the data you require, and then log in with their credentials - allowing us to fetch their data. Once their data has been successfully retrieved, or an error occurs, a webhook will inform you.

Flow

You can experience the flow an end-user will go through by booking a demo on our site, however given below is a brief description of that flow. The user will land on the bank select page where they can choose from one of your configurable favourites. These are displayed as tiles with the financial institution's logo prominently shown.

Bank Select

A user can search for a bank should it not be displayed as a favourite:

Bank Search

Once a bank is selected the user will be prompted to select an account type if the connection to the bank is performed via credential sharing:

Provider Selection

Once an account type has been selected, or if the connection to a bank is via OAuth, the user will be prompted to provide consent to share the data you have requested:

Consent Screen

The drop downs expand to explain exactly what data will be shared. Only drop downs for the data your account has been configured to request will be displayed to an end-user. Please note that you can provide your own list of terms and conditions to display, and these will be shown beneath the five bullets. Once the user consents to share their data, they will be redirected to their financial institution's online login page when we have a direct connection to an institution's API - otherwise they will be taken to a service we control that facilitates data sharing via credential sharing. Once the user has logged in, they will be redirected back to DirectID Connect:

Sharing Success

Re-authentication

DirectID Connect allows re-authentication of consents to extend the lifetime of the consent. This flow can be started when a consent is about to expire, is expired or revoked. Optionally before starting this flow you can check the status of the consent using the Consent API.

To re-authenticate a consent: Get an access token for Consent API using the Authentication service (Scope should be directid.consent). Append the consent ID that needs to be re-authenticated as query parameter and add the access token as a fragment to the DID Connect url. eg: https://connect.directid.co?consent_id=<ConsentID>#access_token=<AccessToken>.

This user will be prompted to confirm the details of re-authenticating their access:

Reauthentication Consent Start

They will then be redirected to their bank where they will authorize the access and then redirected back to DID Connect on success:

Reauthentication Consent Finish

If the user chooses to cancel the journey, they'll be presented with this screen:

Reauthentication Consent Cancel

The notifications that will dispatched when the journey finishes will have the reauthentication flag set to true. Once the journey finishes and a notification is received indicating success, you may resume fetching the data from the APIs.

The user may be required to re-select their accounts during the reauthentication flow. This will only be applicable after their consent has been marked as Revoked by calling the Revoke Consent API.

Configuration

Your account manager can configure a variety of settings for you, these include:

Setting Value
Favourites The list of financial institutions that are listed on the landing page as tiles
Default Country The country that is selected by default for search
Available Countries The countries whose financial institutions will be available for an end-user to search through
Notification Email If you do not wish to receive a notification of a user sharing their data via a webhook, you can provide us with an email address that will be notified instead
Terms The terms you wish to have displayed to the end user on the consent screen. These can be provided in multiple languages, and the terms matching the end-user's browser settings will be displayed in the consent screen
Redirect URL When set, the end user is redirected to that URL after they journey is complete.

Note that you can have several configurations set up (for example if your business operates in multiple regions and you wish to show different terms and have a different set of institutions available for the user to search through) and you can choose between them by passing in a parameter to the URL.

Integration

To integrate DirectID Connect, you need only include a link to our hosted UI in a location of your choice in your application or on your website. This link will be given to you by your account manager once your account has been set up.

Parameters

The URL that launches DID Connect can be provided with several parameters:

Parameter Description Mandatory
client_id Your application ID which will be provided by your account manager Yes
config_id The ID of the configuration you wish to load DirectID Connect with. This ID is decided on by you No - if not provided a default configuration will be used
customer_ref Your reference for the end user going through the DirectID Connect journey Yes
provider_id If you already know which provider the user wishes to connect with, the ID can be provided to skip the bank selection and search part of the journey No
bank_code If you already know the end users bank code, the bank code can be provided to skip the bank selection and search part of the journey if we have a registered provider for the provided bank code. Note, the country_code parameter is also required No
country_code Requried parameter if passing in the bank_code parameter No

DirectID Connect can be setup to redirect to a URL. This can be setup by contacting support.

On redirection we will pass the following parameters to the redirection URL.

Parameter Description Mandatory
customer_ref Your reference for the end user going through the DirectID Connect journey Yes
state the state of the end user journey. success or error Yes
error an error code. see DirectID Connect Errors for possible codes. Yes if state is error, No otherwise
consent_id Unique ID for the end-user's Consent that allows us to fetch their data Yes if state is success, No otherwise

Notifications

Notifications are used by Direct ID to inform you of your customer’s user journey through Direct ID. Notifications come in two flavours, email and webhook. Notifications can be used to track the customer's status e.g. whether they have successfully connnected, their data is available, etc. Notifications also include any errors that may have occurred. Different notifications can be setup for different providerAuthentication and dataAvailability statuses. It is also possible to have both email and webhook notifications enabled at the same time.

Email

The email notification can contain the following fields:

Parameter Description
ConsentId Unique ID for the end-user's Consent that allows us to fetch their data
CustomerReference Your reference for the end-user
ProviderAuthentication The provider authentication status for the consent: Success, Error
DataAvailability The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null: Error, Partial, Complete, Processed
ErrorMessage The error message if there are any errors raised for this event (Optional)

The email notification can be enabled by contacting support.

The email notification also supports custom templates.

Webhook

Webhooks can be enabled by contacting support.

The webhook can be configured to call an endpoint on your backend system in the result of success or user error.

The webhook will contain your unique ID customerReference passed back to you as well as our internal reference consentId. The internal reference is required to access any of our endpoints about that individual.

  • You will need to set up an endpoint
  • This endpoint must be able to accept a post request from our server as defined below.

Payload Details

  • The HTTP Method will always be POST
  • The Content Type will always be application/json
  • The request JSON will have the following properties:
Property Type Nullable Details
consentId string No Unique ID for the end-user's Consent that allows us to fetch their data
applicationId string No The ID of your account in our system
customerReference string Yes Your reference for the end-user
providerAuthentication string
Enum: "Success", "Error"
No The provider authentication status for the consent
dataAvailability string
Enum: "Error", "Partial", "Complete", "Processed"
Yes The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null
paymentConfirmation string
Enum: "Complete", "Incomplete"
Yes The payment confirmation status for the consent. Populated when Payment Confirmation is enabled
reauthentication boolean No Indicates whether the consent is being re-authenticated
errorMessage string Yes The error message if there are any errors raised for this event
  • Given below is a brief explanation of all the enums mentioned above

    • providerAuthentication

      Value Explanation
      "Success" Provider authentication was successful
      "Error" There was an error during provider authentication
    • dataAvailability

      Value Explanation
      null Data availability status is pending
      "Error" There has been an error in fetching data from the provider
      "Partial" Account data is available from Data API, however transaction data is still pending
      "Complete" All data is available to be fetched from Data API
      "Processed" Data is now available on Dashbaord and Stored Data API
    • paymentConfirmation

      Value Explanation
      null Payment account confirmation is not available/enabled
      "Complete" Payment account confirmation was completed
      "Incomplete" Payment account confirmation is incomplete
  • Here is an example of the request body JSON

    {
     "consentId":"207e50aa-72c0-11eb-9439-0242ac130002",
     "applicationId":"26e667b6-72c0-11eb-9439-0242ac130002",
     "customerReference":"defaultuser",
     "providerAuthentication":"Success",
     "dataAvailability":"Complete",
     "paymentConfirmation":null,
     "reauthentication":false,
     "errorMessage":null
    }

Optional OAuth2 Authentication

If you want to make sure that no one can call your endpoint, except for verified clients, we can enable our server to connect to your OAuth2 authorisation server and get an access token. We then send it to you in the same way, as you connected to our OAuth2 provider to authenticate you to use our API. In addition to the data listed above, we will require the following details:-

  • A Client ID for your OAuth authorisation server
  • A Secret Key for your OAuth authorisation server
  • An endpoint to request the access Token
  • An optional scope

DirectID Data API

Getting started: what you need

To access the DirectID Data API, you will need access credentials that will be provided to you by our support team.

These credentials will be used to obtain an access_token that is required to authenticate with the DirectID Data API endpoints.

Once your user has connected to their bank through DirectID Connect, you can call the DirectID Data API endpoints to retrieve their bank data. Each set of credentials comprises the following information:

  • A client_id, which is the OAuth public identifier for your application
  • A client_secret, which is the secret used to authenticate the client_id
  • A scope, which is used to determine API access.

To receive notifications about the user's status, you need to provide us with a webhook URL which we will notify upon successful connection with the bank. For further information please see the Webhooks section.

In summary, you'll need the following:

  • URL, resource ID, and credentials for the DirectID Data API
  • A page on which you can insert the link to DirectID Connect
  • A web service "Webhook" that we call when your user has completed their journey, and the bank data is ready

Errors

DirectID Connect

If an error occurs during the DirectID Connect journey, a URL parameter error will be included in the callback and in a webhook if specified. An optional parameter of error_description may be included with further information.

Error Description
access_denied The Customer or the bank has denied consent. A reauthentication may result in a successful journey.
provider_permanent_error An error has occurred with the bank and we are not able to complete the request.
provider_unsupported_feature Feature is unsupported for provider.
customer_cancelled The customer has cancelled the DirectID Connect journey. The customer will need to complete the journey again.
unexpected_error An unexpected error has occurred which is not recoverable.

DirectID APIs

These errors will be returned via the API Endpoints in the application/json response format below. CorrelationId is our unique reference to trace the error.

{
    "Code": "string",
    "Description": "string",
    "Details": "string",
    "CorrelationId": "string"
}
HTTP Status Code Description
400 parameters_invalid Invalid parameters were provided.
401 unauthorised_client Client is not authorised.
403 consent_denied Consent was denied access by the bank.
403 consent_expired Consent has expired.
403 consent_revoked Consent was revoked.
403 account_refresh_not_allowed Refresh is not allowed for this account.
404 consent_not_found Consent for the provided consent id was not found.
404 client_not_found Client for the provided client id was not found.
404 account_not_found Account requested was not found.
422 provider_unsupported_feature Feature is unsupported for provider.
500 unexpected_error Unexpected error has occured. Please contact our support team.
502 provider_temporarily_unavailable Provider is temporarily unavailable. Please try again later.
502 provider_permanent_error Provider is permanently unavailable.
502 provider_rate_limit_reached Cannot request data for this provider as the rate limit has been reached.

Authentication

Bearer

JWT Authorization header using the Bearer scheme.

Enter 'Bearer' [space] and then your token in the text input below.

Example: "Bearer token123"

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Get Token

Overview

To access our APIs you need to pass your client_id and client_secret, along with the scope that you are requesting, to our authentication service. If that all goes according to plan then an access_token will be returned to you, which is valid for one hour.

Integration

A request with the following payload to our endpoint should return an access token for use in subsequent calls in any of our Data API endpoints.

Key Value
grant_type client_credentials
client_id The client_id that we supplied to you
client_secret The client_secret that we supplied to you
scope The scope value for the API that you need access to

Please find below the scopes values for our APIs, these values need to be specified when requesting a token:

API Scope
DirectID Consent Service directid.consent
DirectID Data API directid.data
DirectID Stored Data API directid.stored_data

Assuming the authentication was successful, you should receive a 200 OK response.

The important fields in the authentication response are:

Field Description
expires_in The number of seconds before the token expires (defaults to 3600 seconds)
token_type Bearer
access_token The token you will use in subsequent requests

If you expect to make repeated and/or delayed calls using this access_token, you should pay attention to the expires_in field and request a new token if you have exceeded the expiration time.

Using the acccess token

Once you have the access_token, you'll assign it to the Authorization header with a prefix of Bearer. More information can be found here .

Request a token for the provided scope and grant type (only client_credentials supported)

Request Body schema: application/x-www-form-urlencoded
grant_type
string Nullable
client_id
string Nullable
client_secret
string Nullable
scope
string Nullable

Responses

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresIn": 0,
  • "accessToken": "string"
}

Get Consents

Overview

This allows you retrieve details for consents such as expiry date, status, provider, permissions and any other detail about the consent that has been stored.

Retrieve list of consents.

Authorizations:
Bearer (appid)
query Parameters
consentStatus
string Nullable

Optional filter to get consents with a particular status.

configurationName
string Nullable

Optional filter to get consents only for a particular configuration name for the client.

providerId
integer <int32> Nullable

Optional filter to get consents only for a particular provider id.

offset
integer <int32>
Default: 0

Number of consents to skip

limit
integer <int32>
Default: 0

Maximum number of consents in the response

Responses