Atto Developer Documentation

Number of APIs: 33

Introduction

Welcome to the Atto developer documentation.

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

Atto Connect

Overview

Atto 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.

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

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:

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:

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 Atto Connect:

Re-authentication

Atto 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.

Atto provides both Webhooks and Email notification V2 to notify of upcoming consent expirations, each of which can be configured for how many days prior to consent expiration they should be triggered.

To re-authenticate a consent:

1. Get an access token for Consent API using the Authorization API (Scope should be directid.consent).

2. Append the consent ID that needs to be re-authenticated as query parameter and add the access token as a fragment to the Atto Connect url. eg: https://connect.atto.co?consent_id=#access_token= and send it to the end user.

3. User will be prompted to confirm the details of re-authenticating their access:

Note: directid.consent Access Token validity period is about 1 hour. Attaching Reauthentication URL straight to the email would not end up with good user experience as URL would not be usable after 1 hour. Recommended approach is to redirect end user to your page, where end user can continue with Reauthentication and new Access Token can be requested.

User is redirected to their bank where they will authorize the access:

If authorization was successful, user is redirected back to Connect:

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.

Notifications

Atto dispatches Webhook evenType : Consent when the journey finishes. consentJourney value is set to Reauthentication. Once the journey finishes and a notification is received indicating success, you may resume fetching the data from the APIs.

API Flow

Reconfirmation

Get access to your user's account information for longer by allowing your user to reconfirm the consent. This feature is only available in the UK.

Atto Connect allows reconfirmation of consents to extend the lifetime of the consent. This flow should be started when a consent is about to expire. Regulation enforced by PSD2 states that consents can last up to 90 days and to continue to access the data, reconfirmation has to be received after every 90 days by the end-user.

Atto provides both Webhooks and Email notification V2 to notify of upcoming consent expirations, each of which can be configured for how many days prior to consent expiration they should be triggered.

Starting reconfirmation flow

To reconfirm a consent:

1. Get an access token for Consent API using the Authorization API (Scope should be directid.consent).

2. Append the consent ID that needs to be reconfirmed as query parameter and add the access token as a fragment to the Atto Connect url. eg: https://connect.atto.co?consent_id=#access_token= and send it to the end user.

3. User will be prompted to reconfirm the details of their access:

Note: directid.consent Access Token validity period is about 1 hour. Attaching Reconfirmation URL straight to the email would not end up with good user experience as URL would not be usable after 1 hour. Recommended approach is to redirect end user to your page, where end user can continue with Reconfirmation and new Access Token can be requested.

Based on a bank’s internal criteria, users may be required to re-authenticate their consent with the bank at certain times. See how this flow will look like in Re-authentication docs.

Disconnect flow

If a user doesn't wish to prolong access to the data, then they can revoke access to the bank data.

Notifications

Atto dispatches Webhook evenType : Consent when the journey finishes. consentJourney value is set to Reconfirmation. Once the journey finishes and a notification is received indicating success, you may resume fetching the data from the APIs.

API Flow

Configuration

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

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 Atto 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 Atto Connect can be provided with several parameters:

Atto 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.

Notifications

Notifications are used by Atto to inform you of your customer’s user journey through Atto. 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, an invitation email has been delivered, etc. Notifications also include any errors that may have occurred.
Different notifications can be set up for different providerAuthentication and dataAvailability statuses.

Email

Email notifications are useful for Dashboard product consumers, who are not utilizing Atto APIs. These notifications will give you real-time info about connected consent details.

The email notification can be enabled by contacting support.

V1 (deprecated)

NB: Email notifications are supported for v1 notifications only.

The email notification can contain the following fields:

V2

The email notification can contain the following fields:

Webhooks

Atto uses webhooks to send real-time notifications to your application regarding updates to a user consent within the Atto platform. These webhooks deliver push notifications through HTTPS requests with the data encapsulated in JSON payloads.

Configuring webhooks

To use webhooks, you will first need to set up an endpoint that accepts HTTP POST requests with the schema defined below. It is possible to apply OAuth2 authentication, if you want to make sure that no one can call your endpoint. Webhooks can be enabled by contacting support.

Payload Details

• The HTTP Method will always be POST

• The Content Type will always be application/json

Retry policy

If your endpoint is not able to handle the first webhook, then we will retry three times before discarding it. There will be 2 seconds, 4 seconds and 8 seconds delay between retries.

V1 (deprecated)

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:

• 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"	The bank data is avaiable via the Stored Data API and Data API
    "Processed"	Stored Data has been enriched and is avaiable via the 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
}

V2 Webhooks

v2 event schema

{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}

Consent

Consent schema returns a holistic overview of consent status and data availability, and provides details about connected provider, consent validity period and its journey type.

Configuring this Webhook is highly recommended in case you are using Atto APIs.

• Here is an example of the request body JSON

{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
      "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
      "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
      "providerId": 0,
      "providerName": "string",
      "configurationName": "string",
      "customerReference": "string",
      "consentStatus": "Pending",
      "consentJourney": "Reconfirmation",
      "consentStart": "2019-08-24T14:15:22Z",
      "consentEnd": "2019-08-24T14:15:22Z",
      "statusUpdated": "2019-08-24T14:15:22Z",
      "dataAvailability": "string",
      "invitationId": "string"
  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}

Consent event flow

Success flow

Failure flow

Invitation

Invitation event type webhooks are meant to be used hand in hand with Atto Connect Invitation API product. The webhook will contain necessary information to track specific invitations through their phases.

• Here is an example of the request body JSON

{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
      "invitationId": "fdd86d02-5745-4cc9-ad9a-8372d6ec2c9b",
      "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
      "emailState": "Received",
      "customerReference": "ProposalNumber",
      "smtpErrorCode": "",
      "smtpErrorMessage": "",
      "connectionStatus": "Pending",
  },
  "eventType": "Invitation",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Email",
  "schemaVersion": "1.0.0"
}

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 to authenticate you to use our API, in the same way that you connected to our OAuth2 provider. 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

Example requests

Here are two example requests we do to compete the OAuth2 Webhook flow:

• Make a request for bearer token using the customer supplied: Authorisation Server Url, Client Id, Client Secret, and Optional Scope which returns the accessToken that we use to authenticate with their webhook URL. We use Basic authentication so the request will contain a header of the form Authorization: Basic where encodedCredentials is a Base64 encoded ClientId:ClientSecret

• We call the customer supplied Webhook Url using the access token returned as the bearer token

Example initial token request

curl --location -g --request POST 'https://[CustomerAuthorisationServerUrl]' \
--header 'Authorization: Basic W0NsaWVudElkXTpbQ2xpZW50U2VjcmV0XQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=[Optional Scope]'

Example expected response

{
  "token_type": "bearer",
  "expires_in": 123,
  "access_token": "ReturnedAccessToken"
}

Example webhook POST request

curl --location -g --request POST 'https://[CustomerWebhookUrl]' \
--header 'Authorization: Bearer [ReturnedAccessToken]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "consentId": "207e50aa-72c0-11eb-9439-0242ac130002",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "customerReference": "defaultuser",
  "providerAuthentication": "Success",
  "dataAvailability": "Complete",
  "paymentConfirmation": null,
  "reauthentication": false,
  "errorMessage": null
}'

Atto APIs

Getting started: what you need

To access the Atto 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 Atto Data API endpoints.

Once your user has connected to their bank through Atto Connect, you can call the Atto 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.

We'll send you a set of credentials for the test environment, initially. When you're ready to push to production then we'll issue you with a separate set of credentials that you should use in production.
It's important that you keep test and production environments separate.

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 Atto Data API

• A page on which you can insert the link to Atto Connect

• A web service Webhook that we call when your user has completed their journey, and the bank data is ready

Tokenized account numbers

Providers in the U.S. are adopting the use of Tokenized Account Numbers (TANs) to reduce the potential exposure of sensitive personal information. When you fetch data from a provider that implements this method, TANs are provided instead of the full or masked account numbers. You will find the Tokenized Account Number (TAN) returned in the accountNumber field, typically located within the identifiers object in our API responses.

The functionality provided does not enable customers to conduct Bank account verification checks or perform any other form of account number matching for payment purposes.

The following providers are returning tokenized account number(s):

Chase Bank (US) - Tokenized Account Number

Security

Atto APIs are currently supporting only TLS 1.2

Errors

Atto Connect

If an error occurs during the Atto 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.

Atto 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"
}

Authentication

Bearer

JWT Authorization header using the Bearer scheme.

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

Example: Bearer token123

1. Reporting - Get PDF statement for the account GET {{baseUrl}}/stored-data/v1/consents/:consentId/accounts/:accountId/statement

2. Authorization API - Request a token for the provided scope and grant type (only client_credentials supported) POST {{baseUrl}}/v1/oauth2/token

3. Stored Data API-stored-data/v1/consents/{consent Id} - Gets the income verifications for the accounts shared for a consent. GET {{baseUrl}}/stored-data/v1/consents/:consentId/income-verifications?accountId=adipisicing quis&includeFlags=false&excludeBenefits=false

4. Atto Score - Get Atto Score GET {{baseUrl}}/atto-score/v1/consents/:consentId/accounts/:accountId

5. Advanced Insights API-advanced-insights/v1/consents/{consent Id} - Get Consumer Financial Health GET {{baseUrl}}/advanced-insights/v1/consents/:consentId/consumer-financial-health

6. Connect Invitation API-connect-invitations/v1 - Gets a single email invitation GET {{baseUrl}}/connect-invitations/v1/:invitationId

7. Connect Invitation API-connect-invitations/v1 - Sends an email invitation POST {{baseUrl}}/connect-invitations/v1

8. Authorization API - Request a validation token for Atto Connect. GET {{baseUrl}}/v1/connect/validation-token

9. Stored Data API-stored-data/v1/consents/{consent Id} - Refreshes data for a consent. POST {{baseUrl}}/stored-data/v1/consents/:consentId/refresh

10. Consent API-/consents/v1 - Retrieve list of consents. GET {{baseUrl}}/consents/v1?consentStatus=active&limit=10