Shows the current version of the figo Connect API and all available fingerprints you can use to perform certificate pinning against.

Error responses

If an error occurs during a request, the API returns an HTTP status code >= 400 and provides more information in the JSON-body of the response.

Examples

Not Found - 404

{
  "error": {
    "code": 1002,
    "data": {},
    "description": "Not Found",
    "group": "client",
  }
}

Bad Request - 400

{
  "error": {
    "code": 1000,
    "data": {"bank_code": ["Not a valid string."],
             "credentials": ["Credentials must contain at least 2 strings."]},
    "description": "Request body doesn't match input schema.",
    "group": "client"
  }
}

Task Progress Errors

Errors that occur while processing a background task are reported in the error field of the /task/progress response.

Note: The HTTP status code of the /task/progress response will be set to 200, even though the background task may have encountered an error, because the polling request itself was successful. Example

{
  "account_id": "A1.1",
  "challenge": {},
  "error": {
    "code": 10001,
    "description": "Die Anmeldung zum Online-Zugang Ihrer Bank ist fehlgeschlagen. Bitte überprüfen Sie Ihre Benutzerkennung.",
    "group": "user",
    "message": "Bitte geben Sie ihre korrekten Online-Banking Zugangsdaten ein.",
    "name": "Zugangdaten sind inkorrekt"
  },
  "is_ended": false,
  "is_erroneous": True,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": "Bitte geben Sie ihre korrekten Online-Banking Zugangsdaten ein."
}

Error object structure

Error codes

Error codes are grouped in 5 sections:

     < 1000: http status code
  1000-1999: Client
10000-19999: User
20000-29999: Bank
30000-39999: figo
40000-49999: Connectivity
50000-59999: Categorization

This API uses OAuth 2 in two ways for authentication: representing a client or representing a user.

We provide different levels of access depending on the kind of integration planned:

figo Connect

Using the classical OAuth 2 flow for user login and granting access.

figo Connect offline

Just like figo Connect but including the use of OAuth 2 refresh tokens for offline access.

figo Connect light

Only using figo accounts as context for interaction.

figo Connect native

Similar to figo Connect, but using password-based login as well as allowing account creation directly inside your app.

Depending on the use-case of figo Connect inside your application, we will advise you on the most suitable implementation strategy. If you either have the need to change your integration strategy or the scope assigned to your client, please contact us.

Authenticating as Client

In this case no user is involved, but the client acts in a global context. This is mainly used for login and user management actions as well as viewing the catalog of supported banks and services. Client authentication is performed via HTTP Basic Auth with client ID as username and client secret as password.

Authenticating as User

In order to access any information belonging to a user, a client has to authenticate with a token linking itself to the user. This token is called an access token and contains information on the client, the user and the level of access the client has to the users data. In order to authenticate using such an access token the HTTP header is set to Authorization: Bearer <access token>.

Such an access token is either returned, when

• exchanging an authorization code after a successful OAuth login flow

• logging in with the users credentials

• exchanging a refresh token, which in turn gets returned at either of the aforementioned points

Authentication Errors

In case of an authentication error a HTTP code 401 response is returned containing further details on the kind of error in the WWW-Authenticate header.

Scope

This API uses the following OAuth scopes for managing what your client can do at best. In case of using figo Connect, these can be further limited by the user connecting your application to his figo account. When registering your application we will advise you on the most suitable scope and if you encounter a need to change it, please contact us.

The following scopes designed the level of access your application has, each one can be either read-only ro or read-write rw.

In addition this API uses the following flags to signal single bit permissions.

Example

The string accounts=rw balance=ro submit_payments is URL-encoded and passed as the URL parameter scope.

Authentication with scopes

Which scope is required for the respective operation is indicated in the HTTP authentication header of the sample requests.

Example

Consider a call that requires client credentials with scope create_user. This call will have the Authentication header field denoted as follows.

Authentication: Basic <create_user>

A call that requires an access token with scope accounts=rw will have in its header

Authentication: Bearer <accounts=rw>

If your client is not authorized to create figo accounts itself, your application must first obtain an authorization code before it can request an access token. Your application can initiate the authorization process by directing the user’s web browser to a popup window of figo Connect. The popup window will ask the user for their figo account credentials. The user will see the permissions as specified in scope and a list of bank and payment service accounts to choose from. If the user grants access to your application, the figo Connect server sends an authorization code to the callback URL by redirecting the browser to redirect_uri.

NOTE You cannot use the demo client ID for this call.

Access tokens authorize your application to perform operations on a user’s data.

Use this endpoint to invalidate an access token or refresh token.

NOTE You cannot use the demo client ID for this call.

One figo user per application user

If the use case requires to interact with the figo Connect API for one user over an extended period of time, it is recommended to create one figo user per application user. This way the data of each of your users is securely separated.

In this scenario it is recommended to create the figo users with a username directly mappable from your application user IDs, e.g. using <your user ID>@figo.<your application domain>. That way you do not have to save any additional information and still do not block email address of your user for explicit figo Connect usage. A similar, but more secure, mapping is recommended for the users password.

One figo user per application transaction

It is possible to only integrate figo Connect as part of processing a transaction, e.g. to verify account owner information. In this scenario it is recommended to create one figo user per transaction and delete it after the figo Connect integration part of the transaction processing is completed.

For the same reasons as in the other case a simple mapping between your transaction and the figo username/password is recommended for this case as well, e.g. <your transaction ID>@figo.<your application domain> as username.

In order to keep transaction processing time as short as possible, we recommend to defer any clean-up activities.

The figo Connect API provides access to many different financial providers, like banks and online payment services. Information on them can be accessed in the catalog, where service details and credentials requirements are listed.

Setting the Accept-Language-Header to one of the available languages will return results in this language.

NOTE You cannot use the demo client ID for this call.

The real catalog contains thousands of entries, so expect the call to cause some traffic and delay. The example is only to highlight the data structure.

NOTE You cannot use the demo client ID for this call.

NOTE You cannot use the demo client ID for this call.

NOTE You cannot use the demo client ID for this call.

NOTE The icon information currently has a different format than in the list view.

Consider a setup where partners provide their users a client application which communicates with an intermediate server.

(Client App) <-> (Partner Server) <-> (figo API)

To avoid privacy/security issues the secret PIN/TAN values can be encrypted with JWE on the user’s side to conceal them from the partner server.

figo provides an example library which implements user-side JWE encryption of the PIN/TAN credential fields.

figo public key

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1qB2hmObbCbAM+lc+ggDauoIZReejEimnvrmeqEs0opeTeZiiietoHT1FkB8HjlgCWrh6UimxrRvBwwvNn/4uiVEqxuPb37ozWRj87bp1R3iwhzIGHBMgkibfFf9v3FxEjtY6CgCvOJ/12+AiotL+4jBCwsUWcqui3phq4/C19bQTWaN8u1Q1ABB0SSExcfqH3Ahg6i4pJfDwY+/khb4rgvmqPpb7a0tHiWuWqAMUxfEO/GJVaDV+Bq4k5vfUNirIcazUtmnLhBVSTBcjw7OEDEIHGckwUHs6prKE0kkQD4Xjm06XupuZW8/H+/oPBdHJBr+Ugv5Kzlsst/81BEyoQIDAQAB

Available algorithms

Key encryption

• RSA-OAEP

Content encryption

• A128CBC-HS256

• A256CBC-HS512

Account setup

In order to be able to use bank or payment service accounts with figo Connect they need to be setup first. This is a multi-step process roughly following this procedure:

1. Determine the bank_code of the financial service to connect with. A list of supported banks and services can be retrieved from GET /catalog. Each entry also contains the required credentials format.

2. Obtain the login credentials for the account.

3. Submit the credentials together with the bank code to POST /rest/accounts.

4. Wait for the returned task token to complete.

Note that setting up accounts means connecting to the respective financial service (called Bank Contact) with appropriate credentials. There may be multiple accounts available with one set of credentials, e.g. a checking account and a savings account at a bank. After setup they are accessible under GET /rest/accounts.

While most calls to this API do not require interaction with the users banks servers, setting up new accounts or updating transaction lists cannot do without. As bank servers are quite slow in comparison to other requests to this API, this processing takes place in the background and the API client is given a handle on the progress called task token. Please consult the chapter on task processing chapter for more details.

After initial setup the account state and transactions are stored at figo Connect and can be retrieved using the respective API calls.

Account synchronization

As banks commonly do not provide a push mechanism for distributing transaction updates, they need to be polled, which is called synchronization in this API. When triggering a synchronization please make sure that either the PIN for the bank contact is stored inside figo Connect or that the user has the possibility to enter it.

Usually the bank accounts are synchronized on a daily basis. However, the synchronization has to be triggered manually if either:

• the user has disabled automatic synchronization

• there was a PIN error

• the PIN has not been saved

• a saved PIN should be deleted

Once the last remaining account of a bank contact has been removed, the bank contact will be automatically removed as well

In order for figo Connect to have up-to-date transaction and account information, it needs to query the bank servers, a process which is called synchronization. With this call you can create a new task, synchronizing all (or the specified) accounts with the state returned by the bank. This call will immediately return a task token. Please see the chapter on task processing for more details.

When users have multiple accounts in one bank, they still use only one set of credentials associated with that bank. figo Connect takes care of actual bank logins through Bank Contacts, which can be accessed by bank ID, and automatically deduplicates bank accounts if they use the same Bank Contact.

Each bank account has a list of transactions associated with it. The length of this list depends on the bank and time this account has been set up. In general the information provided for each transaction should be roughly similar to the contents of the printed or online transaction statement available from the respective bank. Please note that not all banks provide the same level of detail.

Fields marked with HBCI contain additional data retrieved from banks supporting HBCI and are only present if the respective bank supplies this data.

To display categories, access tokens must also include including scope categories=ro.

In addition to retrieving information on a bank account, this API also provides the ability to submit SEPA wires in the name of the account owner.

Submitting a new payment generally is a two-phased process:

1. compile all information on the payment by creating and modifying a payment object

2. submitting that payment object to the bank.

While the first part is normal live interaction with this API, the second one uses the task processing system to allow for more time as bank servers are sometimes slow to respond. In addition you will need a TAN (Transaktionsnummer) from your bank to authenticate the submission.

Using the Demobank

The Demobank, provided by this API for testing purposes, supports payments to any valid German or SEPA account. Please be aware that you can also submit payments from your normal bank to the Demobank, which will only fail in the validation stage.

Data validation

As banks have to adhere to money laundering regulations and safeguard against malicious or broken clients, some additional validations steps are performed by the API to verify the validity of a submitted payment. The most important one is the “Doppeleinreichungskontrolle”, which denies submitting two very similar payments right after each other. The exact definition of similar payments depends on the specific banks, but the payee, the amount and the purpose are most often taken into account.

TAN processing

Depending on the bank there are quite a few TAN processes in production in Germany, which from an API standpoint boil down to the following scenarios:

• text challenge TAN

  • The user needs to follow some simple text rules, e.g. looking up a TAN with a certain number or looking at his phone.

• smartTAN

  • An animated image is shown which can be read with the TAN generator supplied by the customers bank. This image is encoded in a meta-language to be rendered by a JavaScript library, check this. Please contact us for more details. This format is designated as HHD in this API.

• PhotoTAN

  • A QRcode-like image is shown which can be read with the TAN generator supplied by the customers bank. This image is transported as such an only needs to be displayed. This format is designated as Matrix in this API.

For each scheme the respective challenge information, e.g. the text or image, needs to be displayed to the user, which in turn enters a 6 digit number.

Create a payment in the figo database. The payment can be viewed and modified before submission to the bank or service provider.

View unsubmitted payments as stored in the figo database.

View unsubmitted payment as stored in the figo database.

Bank accounts can have standing orders associated with them if supported by the respective bank. In general the information provided for each standing order should be roughly similar to the content of the printed or online standing order statement available from the respective bank. Please note that not all banks provide the same level of detail.

Execution day and interval

When working with standing orders you have to take some characteristics into account.

If a last_execution_date is set, the standing order has a limited term and will not run indefinitely. Its day of month must be the same as that of the first execution.

If you want to identify the next execution date you have to use the interval and execution_day parameters to calculate the next execution date. interval defines the regular cycle the standing order gets executed. On top of it the execution_day states the day of execution within the interval.

This value depends on the interval chosen. If the interval is set to weekly, possible values for execution_day are: 00 (daily), 01 (monday), 02 (tuesday) … 07 (sunday). Note that not every bank supports the weekly interval.

If the interval is set to one of the other possible values, execution_day could be: 01-30 (1st day of the month to 30th day of the month) or 97 (closing of the month minus two), 98(closing of the month minus one), 99(closing of the month).

The same values are used for all the other intervals. That is, you can only specify the day of month of a payment, even for yearly payments. The date of a repeated execution is then computed by adding interval to the month of the date of submission, ignoring first_execution_date, and using execution_day for day of month.

(Contrived) Example:

• Submission: 2017-01-20

• First execution: 2017-02-10

• Interval: half yearly

• Execution day: 15

• Next execution (computed): 2017-06-15

To be sure, set the execution day to the day of the first execution and set the first execution date in the current month.

(Realistic) Example:

• Submission: 2017-02-01

• First execution: 2017-02-10

• Interval: half yearly

• Execution day: 20

• Next execution (computed): 2017-07-20

The the minimum lead time (time between submission and first execution) is 2 days, maximum lead time is 180 days. This means you cannot submit a standing order to be executed on the same day.

Also note that the actual execution of a standing order may occur later due to weekends or holidays.