Account Information Services (AIS)

Learn more about how Yapily can help you unlock Open Banking for AIS.

In order to access a user's financial data, the user will need to authenticate with their financial institution and give explicit consent. In most cases, this will involve redirecting users to the Institution authorisation screen either in the web browser or if on a mobile through the user's mobile banking application by redirecting to the link provided by the Authorisation Url or QR Code Url. In any case, the goal is to obtain a consentToken which is supplied as the Consent header parameter to sign financial data requests.

Account Authorisation Flow

The Account Authorisation Flow starts when your user (PSU) indicates their intent to share their account data with you. To formally obtain the user's authorisation, simply follow these steps:

  • Send a POST request to the Create Account Authorisation endpoint with the userUuid, institutionId of their bank and callback, which is the URL to return the user to after authorisation.
  • In response to the Create Account Authorisation call, we will return an authorisationUrl and qrCodeUrl, which you should redirect the user to.
  • The user will authorise your application with their bank
  • The consent-token will be returned to your callback url
  • The consent-token can be used to call the Account endpoint to retrieve the user's financial data.

It is also possible to complete the Account Authorisation Flow without a callback URL. Instead of redirecting the user back to your callback URL, you can poll the GET consent endpoint. See Decoupled Account Authorisation Flow for more information.

Using a Callback

The Dashboard allows you to add multiple callbacks if this is required for your application. If you have multiple callbacks at the same domain, you can simply add one callback at the domain with a trailing forward slash e.g. If your domain was https://tpp-application and you wanted to register the following two callbacks:

https://tpp-application/confirmation-accounts
https://tpp-application/confirmation-payments

You could add https://tpp-application/ as a single callback rather than individually defining both of these callbacks:

For testing, you can use the small utility created by Yapily (https://display-parameters.herokuapp.com/) as a callback to make consuming the consent-token easier for you when testing the authorisation flows (Remember to first add this as a callback to your application in the Yapily Dashboard).

One Time Token

As an addition, when using the above flow you can make use of the one-time-token when executing POST Create Account Authorisation Request to retrieve a consent-token without exposing it as a query string parameter at the callback:

  • The one-time-token is a short lived token that will be available at the callback after redirecting from Yapily's authorisation server once the user authorises the request.
  • The one-time-token can then be exchanged for a consent-token using POST Exchange One Time Token (OTT)
  • You can then obtain account information using this consent-token as with the other flows

AIS Consent tokens are valid for 90 days.

Financial Data

Once you have obtained an AIS consent token, you can use it to call the following financial data endpoints:

  • GET Accounts
  • GET Account
  • GET Balances
  • GET Transactions
  • GET Identity
  • GET Account Statements
  • GET Account Statement
  • GET Account Statement File
  • GET Account Direct Debits
  • GET Account Scheduled Payments
  • GET Account Perioic Payments

Features

Name Description
ACCOUNT Get account information for a single account.
ACCOUNTS Get account information for a list of accounts.
ACCOUNTS_WITHOUT_BALANCE Get account information for a list of accounts without any balance information. See CBI Globe Gateway to learn more.
ACCOUNT_BALANCES Get account balance information. See CBI Globe Gateway to learn more.
ACCOUNT_DIRECT_DEBITS Get direct debits for an account.
ACCOUNT_PERIODIC_PAYMENTS Get periodic payments for an account.
ACCOUNT_REQUEST_DETAILS Get account consent details.
ACCOUNT_SCHEDULED_PAYMENTS Get scheduled payments for an account.

Authorisation Errors

After creating any authorisation request to access a user's financial data, in the event of a failure, Yapily will respond with an error, error-source and error-description to help identify what went wrong. The following table summarises the list of possible values:

Error source Error Institution Error
USER ACCESS_DEINED access_denied
USER ACCESS_DEINED user_cancelled
USER ACCESS_DEINED login_required
USER ACCESS_DEINED account_selection_required
USER ACCESS_DEINED interaction_required
INSTITUTION INVALID_GRANT invalid_grant
INSTITUTION INVALID_GRANT consent_required
INSTITUTION INVALID_GRANT server_error
INSTITUTION INVALID_GRANT temporarily_unavailable
INSTITUTION INVALID_GRANT request_not_supported
INSTITUTION INVALID_GRANT request_uri_not_supported
INSTITUTION INSTITUTION_SERVER_ERROR invalid_request
INSTITUTION INSTITUTION_SERVER_ERROR registration_not_supported
INSTITUTION INSTITUTION_SERVER_ERROR unauthorized_client
INSTITUTION INSTITUTION_SERVER_ERROR unsupported_grant_type
INSTITUTION INSTITUTION_SERVER_ERROR invalid_scope
INSTITUTION CONFIGURATION_ERROR invalid_client
INSTITUTION UNCATEGORIZED_ERROR -