The figo Connect API v3

Welcome to the figo Connect API. This API offers a unified interface to thousands of banks and numerous payment service providers. API Services include, for example, retrieving transaction history, initiating payments, viewing securities portfolios, or receiving notifications on changes like incoming transactions.

You can find the differences between API version 2 and version 3 here.

This is the technical documentation on the figo Connect API. For a general introduction to figo services please visit our main page.

Registering your application

If you would like to use figo Connect API in your application, please request for API credentials here. We will generate a client identifier and client secret for you to use.

Demo Access

This API provides a comprehensive demo access and user infrastructure, allowing you to prototype applications without registering a client ID. Two limitations apply to this kind of access:

  1. Access is read-only.

  2. The demo client can only be used with the demo user.

Demo Client

Demo Client ID:

CaESKmC8MAhNpDe5rvmWnSkRE_7pkkVIIgMwclgzGcQY

Demo Client Secret:

STdzfv0GXtEj_bwYn7AgCVszN1kKq5BdgEIKOM_fzybQ

Demo Access Token:

ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ

Demo User

Demo Bank

As real banks can be quite sensitive to trial and error development, we provide a special demo bank and demo bank account as part of this API which in most regards behaves just like a classical bank, but is much more patient.

SDKs and Samples

This document describes the API on the protocol level. If you would simply like to integrate figo into your application as fast as possible, we also offer a variety of SDKs for different programming environments.

Please also have a look into the other repositories in our GitHub account for examples on how to use the SDKs and figo Connect in general.

API specification files

You can download the API specification as

Technical foundation

Base API Endpoint

https://api.figo.me

Figo Connect is a completely RESTful API and aims to follow as many best practices as possible. As they are not all commonly agreed on, the following sections describe the approach taken by the API.

As your security is of high importance to us, the API and its online tools are only available via HTTPS. In addition our SDKs employ certificate pinning to validate the certificate of the API server to extend beyond the SSL trust chain. For the same reasons we recommend to do the same if not using one of our SDKs. The current list of valid certificate fingerprints will be published here:

SHA1 (DEPRECATED)

BE:C2:2D:D3:C0:A5:E9:2E:3C:A4:56:7F:CD:45:B6:9A:F7:43:EB:F9

SHA256

79:B2:A2:93:00:85:3B:06:92:B1:B5:F2:24:79:48:58:3A:A5:22:0F:C5:CD:E9:49:9A:C8:45:1E:DB:E0:DA:50

Valid until 2018-06-24T23:59:59+00:00.

Data Representation

This API uses the HTTP headers Content-Type and Accept for content negotiation and any client should set them according to its abilities and preferences. In order to simplify usage of popular CLI tools with the API, application/json is used for the response representation.

Username & password policy

Usernames have to be in e-mail address format, as specified in RFC 5322 section 3.4.1 (addr-spec).

Currently there are no requirements for passwords, but this might change in the future.

API Status

API Calls

Version

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

GET /version

Response 200

Headers
Content-Type: application/json
Body
{
  "product_environment": "api",
  "product_version": "2.0.126",
  "product_name": "figo Connect",
  "ssl_fingerprints": [
    "DB:E2:E9:15:8F:C9:90:30:84:FE:36:CA:A6:11:38:D8:5A:20:5D:93"
  ]
}
product_environment
string
Valid values:
  • api
  • staging

Environment the service runs on

product_version
string

API version

product_name
string

Product name

ssl_fingerprints
array[string]

List of service's SSL fingerprints

Errors

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

Field Description
code Numeric representation of the error
data Additional error information (validation information and other details)
description Short summary
group Group of error
message Original message of the bank (only in task errors)

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
Group Code Description
Client 1000 Invalid request
Client 1001 Entry already exists
Client 1002 Entity not found
Client 1003 Unauthorized
Client 1004 Invalid client authorization
Client 1005 Payment already processed
Client 1006 Unprocessable entity
Client 1007 Forbidden
User 10000 Login credentials are invalid
User 10001 PIN is invalid
User 10002 Online access is blocked
User 10003 TAN scheme not activated
User 10004 TAN is invalid
User 10005 No authorization for this account
User 10006 Transaction rejected
User 10007 PIN change necessary
User 10008 No authorization for this business transaction
User 10009 HBCI activation necessary
User 10010 Account is blocked
User 10011 Account no longer exists
User 10012 TAN scheme is blocked
User 10013 Status of transaction inconclusive
User 10014 Account not activated for online banking
User 10015 Redundant submissions
Bank 20000 Processing at the bank not possible
Bank 20001 Bank / account unkown
Bank 20002 Transaction canceled
Bank 20003 Maintenance
Bank 20004 Technical migration
Bank 20005 Transaction not possible
Bank 20006 Login not possible
Bank 20007 Pop up
figo 30000 Processing at figo not possible
figo 30001 DEPRECATED figo user - invalid language code
figo 30002 DEPRECATED figo user - username already exists
figo 30003 DEPRECATED figo user - username policy violation
figo 30004 DEPRECATED figo user - missing parameter
figo 30005 Task is expired
figo 40000 Bank not supported
figo 90000 Unclassified error

Authentication

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
figo Connect flow

figo Connect offline

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

figo Connect offline
figo Connect offline flow

figo Connect light

Only using figo accounts as context for interaction.

figo Connect light
figo Connect light flow

figo Connect native

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

figo Connect native
figo Connect native flow

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.

Scope Description
accounts Access to the list of accounts and their details
balance Access to account balances and limits
transactions Access to transaction lists and their details
payments Access to payments
user Access to figo account settings
clients Access to figo Connect client management

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

Flag Description
submit_payments Allow submission of payments to bank server
offline Access figo Connect when the user is not present
create_user Allow creation of figo accounts

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>

OAuth2

Obtain authorization code

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.

GET /auth/code{?response_type,client_id,redirect_uri,scope,state}
Parameters
response_type
enum[string] required
Valid values:
  • code

This parameter must be set to code.

client_id
string required
Example: CaESKmC8MAhNpDe5rvmWnSkRE_7pkkVIIgMwclgzGcQY

The client ID obtained during application registration

state
string required
Example: xqD6gjWygsBlF0uB

Any kind of string that will be forwarded with the redirection response. It serves two purposes: The value is used to maintain state between this request and the callback, e.g. it might contain a session ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

redirect_uri
string
Example: http://localhost:3000

The authorization code will be sent to this callback URL as a parameter. It must match one of the URLs registered during application registration. The value defaults to the first redirect URI configured for the client.

scope
string
Example: accounts=ro balance=ro transactions=ro offline

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions agreed during application registration. If this parameter is omitted, the permissions agreed during application registration are used in place.

Response 303

Headers
Location: http://localhost:3000/callback?code=OkA7jUIro6JNmOF7i5f7QmepCLLoIFug6621ADHLMjK6oimFYK1x5xy5rl0wVZNkheCv5nMkH3hZ0v24immWGaI5Gc0P0F9ue0sgnV7DqwvM&state=xqD6gjWygsBlF0uB

Access Tokens

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

After your application obtained an authorization code, it may exchange the authorization code for an access token.

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

POST /auth/token
Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "grant_type": "authorization_code",
  "code": "OkA7jUIro6JNmOF7i5f7QmepCLLoIFug6621...",
  "redirect_uri": "https://figo.me/test"
}
code
string required

The authorization code returned from the initial request

grant_type
string required
Valid values:
  • authorization_code
redirect_uri
string

If the callback URL was specified in the initial request, then it must also be included in this request. The value defaults to the first redirect URI configured for the client.

Response 200

Headers
Content-Type: application/json
Body
{
  "scope": "accounts=ro balance=ro offline",
  "token_type": "Bearer",
  "access_token": "ASHWLIkouP2O6bgA23DDrFv...",
  "expires_in": 3600,
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
token_type
string
Valid values:
  • Bearer
scope
string

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

access_token
string

The access token for the current user

expires_in
number

The remaining live time of the access token in seconds

refresh_token
string

A refresh token is only included in the response if client credentials have scope offline.

Request a new access token via a valid refresh token. New access tokens can be obtained as long as the user has not revoked the access granted to your application.

POST /auth/token
Headers
Content-Type: application/json
Authorization: Basic <offline>
Body
{
  "scope": "accounts=ro balance=ro offline",
  "grant_type": "refresh_token",
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
scope
string

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

grant_type
string required
Valid values:
  • refresh_token
refresh_token
string required

A refresh token that may be used to request new access tokens. Refresh tokens remain valid until the user revokes access to your application. This response parameter is only present if the permission offline has been requested in the authorization code request.

Response 200

Headers
Content-Type: application/json
Body
{
  "scope": "accounts=ro balance=ro offline",
  "token_type": "Bearer",
  "access_token": "ASHWLIkouP2O6bgA23DDrFv...",
  "expires_in": 3600,
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
token_type
string
Valid values:
  • Bearer
scope
string

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

access_token
string

The access token for the current user

expires_in
number

The remaining live time of the access token in seconds

refresh_token
string

A refresh token is only included in the response if client credentials have scope offline.

Clients with authorization to create figo accounts, may directly ask the user for his figo account credentials and use them to obtain an access token.

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

POST /auth/token
Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "scope": "accounts=ro balance=ro offline",
  "grant_type": "password",
  "username": "demo@figo.me",
  "password": "demo1234"
}
username
string required

The figo account e-mail address

scope
string

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

password
string required

The figo account password

grant_type
string required
Valid values:
  • password

Response 200

Headers
Content-Type: application/json
Body
{
  "scope": "accounts=ro balance=ro offline",
  "token_type": "Bearer",
  "access_token": "ASHWLIkouP2O6bgA23DDrFv...",
  "expires_in": 3600,
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
token_type
string
Valid values:
  • Bearer
scope
string

A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

access_token
string

The access token for the current user

expires_in
number

The remaining live time of the access token in seconds

refresh_token
string

A refresh token is only included in the response if client credentials have scope offline.

Revoke Token

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

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

POST /auth/revoke
Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "token": "ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim...",
  "cascade": true
}
cascade
boolean
Default: true

If token is an access token and cascade is set to true, the corresponding refresh token will also be revoked. Otherwise only token will be revoked.

token
string required

A refresh token or access token

Response 204

User Management

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.

API Calls

Create User

POST /auth/user
Headers
Content-Type: application/json
Authorization: Basic <create_user>
Body
{
  "email": "demo@figo.me",
  "send_newsletter": false,
  "language": "de",
  "name": "Max Mustermann",
  "password": "secret password",
  "affiliate_user": "maja@musterfrau.de",
  "affiliate_client_id": "CDrfwadf****"
}
name
string required

Full name of the figo account user

language
string
Default: "de"

Two-letter code of preferred language (ISO 639-1:2002)

affiliate_client_id
string

Client ID of the figo Connect partner from which the user was redirected to the registration form

affiliate_user
string

Base64 encoded e-mail address of the user promoting the new user

password
string required

Password of the figo Connect user

email
string required

E-mail address used for registration / figo account username

send_newsletter
boolean

DEPRECATED

Response 200

Headers
Content-Type: application/json
Body
{
  "recovery_password": "abcd-efgh-ijkl-mnop"
}
recovery_password
string

Auto-generated recovery password

Retrieve user

GET /rest/user
Headers
Authorization: Bearer <user=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "email": "demo@figo.me",
  "send_newsletter": false,
  "language": "de",
  "user_id": "U1",
  "name": "Max Mustermann",
  "join_date": "2017-01-03T00:00:00.000Z",
  "verified_email": true,
  "address": {
    "street": "Ritterstr. 2-3",
    "street2": "",
    "postal_code": "10969",
    "city": "Berlin",
    "country": "Germany",
    "company": "figo",
    "bill": false,
    "vat": ""
  },
  "force_reset": false,
  "premium": "DEPRECATED",
  "premium_subscription": "DEPRECATED",
  "premium_expires_on": "DEPRECATED"
}
user_id
string

Internal figo Connect user id

name
string

Full name of the figo account user

language
string
Default: "de"

Two-letter code of preferred language (ISO 639-1:2002)

force_reset
boolean

DEPRECATED

join_date
string

Timestamp of figo account registration

premium_subscription
string

DEPRECATED

address
object

Postal address for bills, etc.

city
string
country
string
street2
string
bill
boolean

DEPRECATED

street
string
postal_code
string
company
string
vat
string

DEPRECATED

premium_expires_on
string

DEPRECATED

premium
string

DEPRECATED

verified_email
boolean

This flag indicates whether the user's e-mail has been verified.

email
string required

E-mail address used for registration / figo account username

send_newsletter
boolean

DEPRECATED

Modify User

PUT /rest/user
Headers
Content-Type: application/json
Authorization: Bearer <user=rw>
Body
{
    "email": "new_mail@figo.me",
}
name
string

Full name of the figo account user

language
string
Default: "de"

Two-letter code of preferred language (ISO 639-1:2002)

new_password
string

New figo account password. If this parameter is set, then the parameter password must be set, too.

paymill_token
string

DEPRECATED

address
object

Postal address

city
string
country
string
street2
string
bill
boolean

DEPRECATED

street
string
postal_code
string
company
string
vat
string

DEPRECATED

password
string

Current figo account password

email
string required

E-mail address used for registration / figo account username

send_newsletter
boolean

DEPRECATED

Response 204

Delete User

DELETE /rest/user
Headers
Content-Type: application/json
Authorization: Bearer <user=rw>
Body
{}
reason
string

User's reason to cancel the subscription

Response 204

Catalog

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.

API Calls

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

Read complete Catalog

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.

GET /catalog
Headers
Authorization: Basic
Accept-Language: en

Response 200

Headers
Content-Type: application/json
Body
{
  "banks": [
    {
      "name": "Postbank Berlin",
      "bank_code": "10010010",
      "icon": [
        "https://api.figo.me/assets/images/accounts/postbank.png",
        {
          "48x48": "https://api.figo.me/assets/images/accounts/postbank_48.png",
          "60x60": "https://api.figo.me/assets/images/accounts/postbank_60.png",
          "72x72": "https://api.figo.me/assets/images/accounts/postbank_72.png",
          "84x84": "https://api.figo.me/assets/images/accounts/postbank_84.png",
          "96x96": "https://api.figo.me/assets/images/accounts/postbank_96.png",
          "120x120": "https://api.figo.me/assets/images/accounts/postbank_120.png",
          "144x144": "https://api.figo.me/assets/images/accounts/postbank_144.png",
          "192x192": "https://api.figo.me/assets/images/accounts/postbank_192.png",
          "256x256": "https://api.figo.me/assets/images/accounts/postbank_256.png"
        }
      ],
      "credentials": [
        {
          "label": "PIN oder Passwort",
          "masked": true
        }
      ],
      "advice": "Bitte beachten Sie, dass ein Postbank Login nur über Eingabe der 10-stelligen, numerischen Kontonummer und der 5-stelligen PIN möglich ist.",
      "language": {
        "available_languages": [
          "de",
          "en"
        ],
        "current_language": "de"
      },
      "bic": "PBNKDEFFXXX"
    }
  ],
  "services": [
    {
      "name": "PayPal",
      "bank_code": "PayPal",
      "icon": [
        "https://api.figo.me/assets/images/accounts/paypal.png",
        {
          "48x48": "https://api.figo.me/assets/images/accounts/paypal_48.png",
          "60x60": "https://api.figo.me/assets/images/accounts/paypal_60.png",
          "72x72": "https://api.figo.me/assets/images/accounts/paypal_72.png",
          "84x84": "https://api.figo.me/assets/images/accounts/paypal_84.png",
          "96x96": "https://api.figo.me/assets/images/accounts/paypal_96.png",
          "120x120": "https://api.figo.me/assets/images/accounts/paypal_120.png",
          "144x144": "https://api.figo.me/assets/images/accounts/paypal_144.png",
          "192x192": "https://api.figo.me/assets/images/accounts/paypal_192.png",
          "256x256": "https://api.figo.me/assets/images/accounts/paypal_256.png"
        }
      ],
      "credentials": [
        {
          "label": "PIN oder Passwort",
          "masked": true
        }
      ],
      "advice": "Bitte geben Sie Ihre Kreditkartennummer und Ihr Passwort ein.",
      "language": {
        "available_languages": [
          "de",
          "en"
        ],
        "current_language": "de"
      }
    }
  ]
}
banks
array[object]

List of supported banks

name
string

Human readable name of bank

language
object

Language information of catalog item

current_language
string

Current language of catalog item

available_languages
array[string]

List of available languages

bank_code
string

Bank code

advice
string

Any additional advice useful to locate the required credentials

bic
string

BIC

credentials
array[object]

List of credentials needed to connect to the bank.

masked
boolean

This indicates whether the this text input field is used for password entry and therefore should be masked on presentation.

label
string

Label for text input field

icon
array[string]

URL to an logo of the bank, e.g. as a badge icon, and URLs for icons with additional resolutions

services
array[object]

List of supported payment services

name
string

Human readable name of service

language
object

Language information of catalog item

current_language
string

Current language of catalog item

available_languages
array[string]

List of available languages

bank_code
string

figo Connect internal ID of service

advice
string

Any additional advice useful to locate the required credentials

credentials
array[object]

List of credentials needed to connect to the service.

masked
boolean

This indicates whether the this text input field is used for password entry and therefore should be masked on presentation.

label
string

Label for text input field

icon
array[string]

URL to an logo of the service, e.g. as a badge icon, and URLs for icons with additional resolutions

Read banks Catalog by country

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

GET /catalog/banks/{country_code}
Parameters
country_code
string
Example: de

Country code of the financial provider (ISO 3166-1 ALPHA 2). If omitted, banks from all supported countries are included

Headers
Authorization: Basic
Accept-Language: en

Response 200

Headers
Content-Type: application/json
Body
{
  "banks": [
    {
      "name": "Postbank Berlin",
      "bank_code": "10010010",
      "icon": [
        "https://api.figo.me/assets/images/accounts/postbank.png",
        {
          "48x48": "https://api.figo.me/assets/images/accounts/postbank_48.png",
          "60x60": "https://api.figo.me/assets/images/accounts/postbank_60.png",
          "72x72": "https://api.figo.me/assets/images/accounts/postbank_72.png",
          "84x84": "https://api.figo.me/assets/images/accounts/postbank_84.png",
          "96x96": "https://api.figo.me/assets/images/accounts/postbank_96.png",
          "120x120": "https://api.figo.me/assets/images/accounts/postbank_120.png",
          "144x144": "https://api.figo.me/assets/images/accounts/postbank_144.png",
          "192x192": "https://api.figo.me/assets/images/accounts/postbank_192.png",
          "256x256": "https://api.figo.me/assets/images/accounts/postbank_256.png"
        }
      ],
      "credentials": [
        {
          "label": "PIN oder Passwort",
          "masked": true
        }
      ],
      "advice": "Bitte beachten Sie, dass ein Postbank Login nur über Eingabe der 10-stelligen, numerischen Kontonummer und der 5-stelligen PIN möglich ist.",
      "language": {
        "available_languages": [
          "de",
          "en"
        ],
        "current_language": "de"
      },
      "bic": "PBNKDEFFXXX"
    }
  ]
}
banks
array[object]

List of supported banks

name
string

Human readable name of bank

language
object

Language information of catalog item

current_language
string

Current language of catalog item

available_languages
array[string]

List of available languages

bank_code
string

Bank code

advice
string

Any additional advice useful to locate the required credentials

bic
string

BIC

credentials
array[object]

List of credentials needed to connect to the bank.

masked
boolean

This indicates whether the this text input field is used for password entry and therefore should be masked on presentation.

label
string

Label for text input field

icon
array[string]

URL to an logo of the bank, e.g. as a badge icon, and URLs for icons with additional resolutions

Read services Catalog by country

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

GET /catalog/services/{country_code}
Parameters
country_code
string
Example: de

Country code of the financial provider (ISO 3166-1 ALPHA 2). If omitted, services from all supported countries are included

Headers
Authorization: Basic
Accept-Language: en

Response 200

Headers
Content-Type: application/json
Body
{
  "services": [
    {
      "name": "PayPal",
      "bank_code": "PayPal",
      "icon": [
        "https://api.figo.me/assets/images/accounts/paypal.png",
        {
          "48x48": "https://api.figo.me/assets/images/accounts/paypal_48.png",
          "60x60": "https://api.figo.me/assets/images/accounts/paypal_60.png",
          "72x72": "https://api.figo.me/assets/images/accounts/paypal_72.png",
          "84x84": "https://api.figo.me/assets/images/accounts/paypal_84.png",
          "96x96": "https://api.figo.me/assets/images/accounts/paypal_96.png",
          "120x120": "https://api.figo.me/assets/images/accounts/paypal_120.png",
          "144x144": "https://api.figo.me/assets/images/accounts/paypal_144.png",
          "192x192": "https://api.figo.me/assets/images/accounts/paypal_192.png",
          "256x256": "https://api.figo.me/assets/images/accounts/paypal_256.png"
        }
      ],
      "credentials": [
        {
          "label": "PIN oder Passwort",
          "masked": true
        }
      ],
      "advice": "Bitte geben Sie Ihre Kreditkartennummer und Ihr Passwort ein.",
      "language": {
        "available_languages": [
          "de",
          "en"
        ],
        "current_language": "de"
      }
    }
  ]
}
services
array[object]

List of supported payment services

name
string

Human readable name of service

language
object

Language information of catalog item

current_language
string

Current language of catalog item

available_languages
array[string]

List of available languages

bank_code
string

figo Connect internal ID of service

advice
string

Any additional advice useful to locate the required credentials

credentials
array[object]

List of credentials needed to connect to the service.

masked
boolean

This indicates whether the this text input field is used for password entry and therefore should be masked on presentation.

label
string

Label for text input field

icon
array[string]

URL to an logo of the service, e.g. as a badge icon, and URLs for icons with additional resolutions

Read individual Catalog Entry

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.

GET /catalog/{catalog_category}/{country_code}/{financial_provider_id}
Parameters
catalog_category
enum[string] required
Valid values:
  • banks
  • services

Type of financial providers to request. This can either be banks for regular banks or services for payment services like PayPal.

country_code
string required
Example: de

Country code of the financial provider (ISO 3166-1 ALPHA 2)

financial_provider_id
string required
Example: PayPal

figo Connect internal ID of the financial provider. This can be a bank code for German banks, a BIC for European banks, or service names like paypal.

Headers
Authorization: Basic
Accept-Language: en

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "PayPal",
  "bank_code": "PayPal",
  "icon": "https://api.figo.me/assets/images/accounts/paypal.png",
  "credentials": [
    {
      "label": "PIN oder Passwort",
      "masked": true
    }
  ],
  "advice": "Bitte geben Sie Ihre Kreditkartennummer und Ihr Passwort ein.",
  "language": {
    "available_languages": [
      "de",
      "en"
    ],
    "current_language": "de"
  },
  "additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/paypal_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/paypal_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/paypal_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/paypal_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/paypal_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/paypal_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/paypal_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/paypal_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/paypal_256.png"
  }
}
name
string

Human readable name of service

language
object

Language information of catalog item

current_language
string

Current language of catalog item

available_languages
array[string]

List of available languages

bank_code
string

figo Connect internal ID of service

advice
string

Any additional advice useful to locate the required credentials

additional_icons
object

Dictionary mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
credentials
array[object]

List of credentials needed to connect to the service.

masked
boolean

This indicates whether the this text input field is used for password entry and therefore should be masked on presentation.

label
string

Label for text input field

icon
string required
Valid values:
  • https://api.figo.me/assets/images/accounts/paypal.png

URL to an logo of the service, e.g. as a badge icon

PIN/TAN encryption

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

Accounts

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

API Calls

Connect to Bank Accounts

POST /rest/accounts
Headers
Content-Type: application/json
Authorization: Bearer
Body
{
  "bank_code": "90090042",
  "iban": "DE67900900424711951500",
  "country": "de",
  "credentials": [
    "demo",
    "demo"
  ],
  "save_pin": true,
  "disable_first_sync": false,
  "sync_tasks": [
    ""
  ],
  "redirect_uri": "https://figo.me/test"
}
sync_tasks
array[string]
Default: ["transactions"]
Valid values in array:
  • transactions
  • standingOrders
  • categorizations

List of additional information to be fetched from the bank.

save_pin
boolean
Default: false

This flag indicates whether the given PIN should be saved on the figo Connect server.

country
string

DEPRECATED

bank_code
string

Internal figo Connect bank code of the bank or service associated with the account

redirect_uri
string

The user will be redirected to this URI after completing the account setup. The value defaults to the first redirect URI configured for the client.

iban
string

The IBAN of the account.

disable_first_sync
boolean
Default: false

This flag indicates whether the initial synchronization of the account with figo Connect will be skipped.

credentials
array[string]

List of credentials as demanded by the bank or service. They must be in the same order as in the credentials list from the login settings.

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor the setup process. Use this to call /task/progress.

POST /rest/accounts
Headers
Content-Type: application/json
Authorization: Bearer
Body
{
  "bank_code": "90090042",
  "iban": "DE67900900424711951500",
  "country": "de",
  "credentials": {
    "type": "encrypted",
    "value": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIifQ.aq_baOMnl2WPI7LfDQ3E7zv6X6lWegDgwCwqNgLx8fK752mM56Q_WZ5Z7oob5Nl6GduF9nYL-ew6ijg6wkxtqplWZtEX-G_CQSjc2xTVZtEfFixL2_J4j4eHnioH5qsXaCZmxd0ZekEXNCRS9jsw6XI-5ztccRvZKkARhlP_BH_j0phosJotxwSleIQIVZg_1baw-KHNoL7uIJWNj10x5hqFVjg2tLPBzkndzVZaIAMCZ1W1W736sWS0UCMYcPjzaDEPn4K2dhOW9d_1ZPobPuqH0hVf6SVTRCoAv-FG6t18YTOdp3GQcYML7A9NSLtcnestPyh_VFZnoDVr3xSqPw.kJqefpeucfJKM1y3ONYllg._GbDGpxL5xVhErPz8HTZhbdUQru22DHQD4Dmm9tLos4.YEj_gkdNb1pdJxAfEr3q5KcXPoBkYCX0n9qZZQcFJN0"
  },
  "save_pin": true,
  "disable_first_sync": false,
  "sync_tasks": [
    ""
  ],
  "redirect_uri": "https://figo.me/test"
}
sync_tasks
array[string]
Default: ["transactions"]
Valid values in array:
  • transactions
  • standingOrders
  • categorizations

List of additional information to be fetched from the bank.

save_pin
boolean
Default: false

This flag indicates whether the given PIN should be saved on the figo Connect server.

country
string

DEPRECATED

bank_code
string

Internal figo Connect bank code of the bank or service associated with the account

redirect_uri
string

The user will be redirected to this URI after completing the account setup. The value defaults to the first redirect URI configured for the client.

iban
string

The IBAN of the account. If set, will override bank_code.

disable_first_sync
boolean
Default: false

This flag indicates whether the initial synchronization of the account with figo Connect will be skipped.

credentials
object

JWE encrypted list of credentials as demanded by the bank or service. They must be in the same order as in the credentials list from the login settings.

type
string
Valid values:
  • encrypted
value
string

Encrypted credentials

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor the setup process. Use this to call /task/progress.

Read available Accounts

GET /rest/accounts/{account_id}{?cents}
Parameters
account_id
string
Example: A1.1

ID of a specific account. If omitted, a list of all the user’s accounts is returned.

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "auto_sync": true,
  "preferred_tan_scheme": "",
  "account_id": "A1.1",
  "bank_id": "B607.1",
  "name": "Girokonto",
  "owner": "Max Mustermann",
  "supported_tan_schemes": [
    {
      "tan_scheme_id": "M607.1",
      "name": "iTAN",
      "medium_name": "Girocard",
      "additional_info": {}
    }
  ],
  "iban": "DE67900900424711951500",
  "bic": "DEMODE01",
  "account_number": "4711951500",
  "bank_code": "90090042",
  "bank_name": "Demobank",
  "balance": {
    "balance": 3250.31,
    "balance_date": "2017-02-20T00:00:00.000Z",
    "monthly_spending_limit": 0,
    "credit_line": 0
  },
  "currency": "EUR",
  "type": "Giro account",
  "icon": "https://api.figo.me/assets/images/accounts/default.png",
  "additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "supported_payments": {
    "Transfer": {
      "allowed_recipients": [],
      "max_purpose_length": 108,
      "supported_text_keys": [
        51,
        53
      ],
      "can_be_recurring": false,
      "can_be_scheduled": false,
      "supported_file_formats": []
    }
  },
  "status": {
    "code": 1,
    "sync_timestamp": "2017-02-16T18:27:25.000Z",
    "success_timestamp": "2017-02-16T18:27:25.000Z"
  },
  "verification_status": false,
  "save_pin": true,
  "in_total_balance": false
}
verification_status
boolean

Status whether this account is verified

currency
string

Three-character currency code (ISO 4217:2015)

owner
string

Owner of account

preferred_tan_scheme
string

DEPRECATED

save_pin
boolean
Default: false

This flag indicates whether the user has chosen to save the PIN on the figo Connect server.

supported_payments
object

Object where keys are payment types and values their payment parameters as supported by this account.

Transfer
object
supported_text_keys
array[number]

List of supported DTA text keys

max_purpose_length
number

Maximum string length of purpose text

can_be_scheduled
boolean

Indicates whether payments of this type can be scheduled to be executed on a specific date. This usually applies for standing orders.

allowed_recipients
array[string]

List of account IDs. The payment recipient must be one of these accounts. No restriction applies if this field is omitted

can_be_recurring
boolean

Indicates whether payments of this type can be recurring. This usually applies for standing orders.

supported_file_formats
array[string]

List of supported payment file formats for file upload. Currently always empty

type
string
Valid values:
  • Giro account
  • Savings account
  • Daily savings account
  • Credit card
  • Loan account
  • PayPal
  • Depot
  • Unknown

Account type

status
object

Synchronization status

sync_timestamp
string

Timestamp of last synchronization. For multiple accounts, the oldest timestamp is displayed.

code
number

DEPRECATED

message
string

Human-readable error message

success_timestamp
string

Timestamp of last successful synchronization. For multiple accounts, the oldest timestamp is displayed.

bank_name
string

Name of the bank

account_id
string required

Internal figo Connect account ID

bank_code
string

The old school bank code

bic
string

BIC of the bank

additional_icons
object

Dictionary mapping from resolution to URL for additional resolutions of the banks icon

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
iban
string

IBAN of the account

icon
string

Bank icon

name
string

Name of account

auto_sync
boolean

This flag indicates whether the account will be automatically synchronized

bank_id
string required

Internal figo Connect bank ID

supported_tan_schemes
array[object]

List of TAN schemes supported by this account

medium_name
string

TAN medium name

name
string

TAN scheme name

tan_scheme_id
string

Internal figo Connect TAN scheme ID

additional_info
object

Additional information on the TAN scheme

in_total_balance
boolean

DEPRECATED

account_number
string

The old school account number

balance
object

Account balance

balance_date
string

Bank server timestamp of balance. This response parameter will be omitted if the balance is not yet known.

balance
number

Account balance. This response parameter will be omitted if the balance is not yet known.

monthly_spending_limit
number

DEPRECATED This value is not used anymore and always set to 0.

credit_line
number

DEPRECATED This value is not used anymore and always set to 0.

Modify Account

PUT /rest/accounts/{account_id}
Parameters
account_id
string required
Example: A1.1

ID of a specific account

Headers
Content-Type: application/json
Authorization: Bearer
Body
{
  "auto_sync": true,
  "preferred_tan_scheme": ""
}
auto_sync
boolean

This flag indicates whether the account will be automatically synchronized

preferred_tan_scheme
string

DEPRECATED

Response 204

Delete Account

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

DELETE /rest/accounts/{account_id}
Parameters
account_id
string required
Example: A1.1

ID of a specific account

Headers
Authorization: Bearer

Response 204

Account Balance and Limits

Read Account Balance

GET /rest/accounts/{account_id}/balance/{?cents}
Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "balance": 3250.31,
  "balance_date": "2017-02-20T00:00:00.000Z",
  "monthly_spending_limit": 0,
  "credit_line": 0
}
balance_date
string

Bank server timestamp of balance. This response parameter will be omitted if the balance is not yet known.

balance
number

Account balance. This response parameter will be omitted if the balance is not yet known.

monthly_spending_limit
number

DEPRECATED This value is not used anymore and always set to 0.

credit_line
number

DEPRECATED This value is not used anymore and always set to 0.

Synchronization

Create Synchronization Task

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.

POST /rest/sync
Headers
Content-Type: application/json
Authorization: Bearer <balance=ro transactions=ro>
Body
{
  "state": "fP7XfLatwhrtu0sA",
  "redirect_uri": "http://figo.me/test",
  "disable_notifications": false,
  "if_not_synced_since": 2,
  "auto_continue": false,
  "account_ids": [
    "A1.1"
  ],
  "sync_tasks": [
    ""
  ]
}
sync_tasks
array[string]
Default: ["transactions"]
Valid values in array:
  • transactions
  • standingOrders
  • categorizations

List of additional information to be fetched from the bank

state
string required

Arbitrary string to maintain state between this request and the callback, e.g. it might contain a session ID from your application. The value should also contain a random component, which your application checks to prevent cross-site request forgery. The allowed legnth is between 1 and 1024 characters.

redirect_uri
string

At the end of the synchronization process a response will be sent to this callback URL. The value defaults to the first redirect URI configured for the client.

if_not_synced_since
number

If this parameter is set, only those accounts will be synchronized, which have not been synchronized within the specified number of minutes.

account_ids
array[string]

Only sync the accounts with these IDs.

disable_notifications
boolean

This flag indicates whether notifications should be sent to your application. Since your application will be notified by the callback URL anyway, you might want to disable any additional notifications.

auto_continue
boolean

Automatically acknowledge and ignore any errors.

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor the setup process. Use this to call /task/progress.

Bank Contacts

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.

API Calls

Read Bank Contact

GET /rest/banks/{bank_id}
Parameters
bank_id
string required
Example: B1.1

Internal figo Connect bank ID

Headers
Authorization: Bearer <accounts=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "bank_id": 1,
  "bank_code": "90090042",
  "sepa_creditor_id": "DE02ZZZ0123456789",
  "save_pin": true
}
save_pin
boolean

This flag indicates whether the user has chosen to save the PIN on the figo Connect server.

sepa_creditor_id
string

SEPA direct debit creditor ID

bank_id
number

Internal figo Connect bank ID

bank_code
string

The old school bank code

Remove stored PIN from Bank Contact

POST /rest/banks/{bank_id}/remove_pin
Parameters
bank_id
string required
Example: B1.1

Internal figo Connect bank ID

Headers
Authorization: Bearer <accounts=ro>

Response 204

Transactions

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.

Transactions

Read Transactions

GET /rest/transactions{?cents,since,since_type,include_pending,type,sort,offset,count,until,accounts,filter,include_statistics}
Parameters
cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

since
string
Example: 2017-01-01T00:00:00.000Z

Return only transactions after this date based on since_type. This parameter can either be a transaction ID or an ISO date. Given at least one transaction matches the filter criterion, if provided as transaction ID the result will not contain this ID. If provided as ISO date, the result will contain this date. This behavior may change in the future.

since_type
enum[string]
Valid values:
  • booked
  • created
  • modified

This parameter defines how the parameter since will be interpreted.

include_pending
boolean
Default: false
Example: true

This flag indicates whether pending transactions should be included in the response. Pending transactions are always included as a complete set, regardless of the since parameter. Before caching a copy of the pending transactions, all existing pending transactions for the same account must be removed from the local cache.

sort
enum[string]
Valid values:
  • asc
  • desc

Determine whether results will be sorted in ascending or descending order.

type
array[Transaction Type]
Example: Transfer,Standing order

A list of transactions types which the transactions are filtered by.

offset
number
Example: 200

Skip this number of transactions in the response. In combination with the count parameter this can be used to paginate the result list.

count
number
Default: 1000
Example: 100

Limit the number of returned transactions. In combination with the offset parameter this can be used to paginate the result list.

until
string
Example: 2017-01-01T00:00:00.000Z

Return only transactions which were booked on or before this date. Please provide as ISO date. It is not possible to use the since_type semantics with until.

filter
string
Example: date:2017-02-03

Filter transactions by given key:value combination. Possible keys: date (maps to booking_date, please use ISO date here, not datetime), person (maps to payer/payee name), purpose, amount. Values are interpreted using wildcards: person:Max Mustermann will match %Max Mustermann%.

include_statistics
boolean
Default: false
Example: true

If true includes statistics on the returned transactions: maximum deposit, total deposits, maximum expense, total expenses.

accounts
array[string]
Example: A1.1,A1.2

Return transactions only from given comma-separated list of account IDs.

Headers
Authorization: Bearer <transactions=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "deleted": [],
  "status": {
    "code": 1,
    "sync_timestamp": "2017-02-16T18:27:25.000Z",
    "success_timestamp": "2017-02-16T18:27:25.000Z"
  },
  "statistics": {
    "deposit_max": 1612.12,
    "deposit_sum": 61284.51,
    "expense_max": 599.95,
    "expense_sum": 12589.19
  },
  "transactions": [
    {
      "value_date": "2017-01-03T00:00:00.000Z",
      "bank_name": "Demobank",
      "account_id": "A1.1",
      "bank_code": "90090042",
      "currency": "EUR",
      "purpose": "A2432122990100992929929",
      "transaction_code": 4,
      "booked": true,
      "booking_date": "2017-01-03T00:00:00.000Z",
      "name": "Amazing Services Europe",
      "creation_timestamp": "2017-01-04T14:44:16.000Z",
      "amount": -19.9,
      "account_number": "4711951501",
      "iban": "DE67900900424711951500",
      "bic": "DEMODE01",
      "visited": false,
      "modification_timestamp": "2017-01-04T14:44:16.000Z",
      "type": "Direct debit",
      "transaction_id": "T1.1715",
      "booking_text": "Lastschrift",
      "categories": [
        {
          "id": 162,
          "parent_id": 150,
          "name": "Spende"
        }
      ],
      "additional_info": {
        "gross_amount": 0,
        "fee": 0
      }
    }
  ]
}
deleted
array[string]

List of deleted transaction IDs

status
object

Synchronization status

sync_timestamp
string

Timestamp of last synchronization. For multiple accounts, the oldest timestamp is displayed.

code
number

DEPRECATED

message
string

Human-readable error message

success_timestamp
string

Timestamp of last successful synchronization. For multiple accounts, the oldest timestamp is displayed.

statistics
object

Statistics on the transactions

deposit_sum
number

Sum of deposits

deposit_max
number

Maximum deposit amount

expense_max
number

Maximum expense amount

expense_sum
number

Sum of expenses

transactions
array[object]

List of transactions for this user

value_date
string

Value date

prima_nota_number
string

HBCI: Bank-internal number to group and identify transactions

currency
string

Three-character currency code (ISO 4217:2015)

end_to_end_reference
string

HBCI: A reference that can be filled by the payer of transaction, e.g. with your customer number

text_key_addition
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

customer_reference
string

HBCI: Customer reference, e.g. your insurance number

additional_info
object

Additional info on the transaction, if available.

reference_party_creditor
string

HBCI: Deviating receiver of the transfer

fee
number

Possible payed fees

reference_party_debitor
string

HBCI: Deviating sender of the transfer

bank_reference
string

HBCI: Bank reference or instruction ID, can be filled by the payers bank

gross_amount
number

Gross amount of the transaction

debitor_id
string

HBCI: An identifier of the payer

compensation_amount
string

HBCI: Sum of reimbursement of out-of-pocket expenses plus processing fee in case of a national return / refund debit as well as an optional interest equalization (for SEPA direct debit returns)

original_amount
string

HBCI: Amount of the original direct debit (for SEPA direct debit returns)

booking_date
string

Booking date

creditor_id
string

HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with mandate_reference

amount
number

Transaction amount

sepa_purpose_code
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

booking_key
string

HBCI: A key that indicates the purpose of a transaction, also called "posting key"/"Buchungsschlüssel".

booking_text
string

Booking text. This field might be empty if the transaction has no booking text.

creation_timestamp
string

Internal creation timestamp on the figo Connect server

transaction_id
string

Internal figo Connect transaction ID

bank_name
string

Bank name of originator or recipient.

account_id
string

Internal figo Connect account ID

bank_code
string

Bank code of originator or recipient. This field might be empty if the transaction has no bank code, e.g. interest transactions.

sepa_remittance_info
string

HBCI: Pure purpose text without other SEPA fields.

bic
string

BIC of payer

iban
string

IBAN of payer

purpose
string

Purpose text. This field might be empty if the transaction has no purpose.

transaction_code
number

Transaction type as DTA Tx Key code.

categories
array[object]

List of categories for this transaction. Categories are stored in a tree, and the figo API returns a path from the root to the leaf. That is, the list of category objects is ordered from general to specific. Categories are only returned to users with scope at least categories=ro.

parent_id
number

ID of parent category

id
number

ID of category

name
string

Name of category

booked
boolean

Some banks provide information on transactions which have not yet been executed. These transactions are called pending, and the flag is set to false. As soon as the bank reports the execution of these transactions, this flag changes to true. If such a pending transaction fails to execute, it is automatically removed from the transaction list.

name
string

Name of originator or recipient

type
string
Valid values:
  • Transfer
  • Standing order
  • Direct debit
  • Salary or rent
  • GeldKarte
  • Charges or interest
  • Direct debit

Transaction type to simplify your analysis of the users transaction

mandate_reference
string

HBCI: SEPA mandate reference (for SEPA direct debits), must be unique in combination with creditor_id

account_number
string

Account number of originator or recipient. This field might be empty if the transaction has no account number, e.g. interest transactions.

visited
boolean

DEPRECATED

modification_timestamp
string

Internal modification timestamp on the figo Connect server

Read single Transaction

GET /rest/transactions/{transaction_id}{?cents}
Parameters
transaction_id
string required
Example: T1.1715

ID of a specific transaction

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer <transactions=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "value_date": "2017-01-03T00:00:00.000Z",
  "bank_name": "Demobank",
  "account_id": "A1.1",
  "bank_code": "90090042",
  "currency": "EUR",
  "purpose": "A2432122990100992929929",
  "transaction_code": 4,
  "booked": true,
  "booking_date": "2017-01-03T00:00:00.000Z",
  "name": "Amazing Services Europe",
  "creation_timestamp": "2017-01-04T14:44:16.000Z",
  "amount": -19.9,
  "account_number": "4711951501",
  "iban": "DE67900900424711951500",
  "bic": "DEMODE01",
  "visited": false,
  "modification_timestamp": "2017-01-04T14:44:16.000Z",
  "type": "Direct debit",
  "transaction_id": "T1.1715",
  "booking_text": "Lastschrift",
  "categories": [
    {
      "id": 162,
      "parent_id": 150,
      "name": "Spende"
    }
  ],
  "additional_info": {
    "gross_amount": 0,
    "fee": 0
  }
}
value_date
string

Value date

prima_nota_number
string

HBCI: Bank-internal number to group and identify transactions

currency
string

Three-character currency code (ISO 4217:2015)

end_to_end_reference
string

HBCI: A reference that can be filled by the payer of transaction, e.g. with your customer number

text_key_addition
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

customer_reference
string

HBCI: Customer reference, e.g. your insurance number

additional_info
object

Additional info on the transaction, if available.

reference_party_creditor
string

HBCI: Deviating receiver of the transfer

fee
number

Possible payed fees

reference_party_debitor
string

HBCI: Deviating sender of the transfer

bank_reference
string

HBCI: Bank reference or instruction ID, can be filled by the payers bank

gross_amount
number

Gross amount of the transaction

debitor_id
string

HBCI: An identifier of the payer

compensation_amount
string

HBCI: Sum of reimbursement of out-of-pocket expenses plus processing fee in case of a national return / refund debit as well as an optional interest equalization (for SEPA direct debit returns)

original_amount
string

HBCI: Amount of the original direct debit (for SEPA direct debit returns)

booking_date
string

Booking date

creditor_id
string

HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with mandate_reference

amount
number

Transaction amount

sepa_purpose_code
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

booking_key
string

HBCI: A key that indicates the purpose of a transaction, also called "posting key"/"Buchungsschlüssel".

booking_text
string

Booking text. This field might be empty if the transaction has no booking text.

creation_timestamp
string

Internal creation timestamp on the figo Connect server

transaction_id
string required

Internal figo Connect transaction ID

bank_name
string

Bank name of originator or recipient.

account_id
string required

Internal figo Connect account ID

bank_code
string

Bank code of originator or recipient. This field might be empty if the transaction has no bank code, e.g. interest transactions.

sepa_remittance_info
string

HBCI: Pure purpose text without other SEPA fields.

bic
string

BIC of payer

iban
string

IBAN of payer

purpose
string

Purpose text. This field might be empty if the transaction has no purpose.

transaction_code
number

Transaction type as DTA Tx Key code.

categories
array[object]

List of categories for this transaction. Categories are stored in a tree, and the figo API returns a path from the root to the leaf. That is, the list of category objects is ordered from general to specific. Categories are only returned to users with scope at least categories=ro.

parent_id
number

ID of parent category

id
number

ID of category

name
string

Name of category

booked
boolean

Some banks provide information on transactions which have not yet been executed. These transactions are called pending, and the flag is set to false. As soon as the bank reports the execution of these transactions, this flag changes to true. If such a pending transaction fails to execute, it is automatically removed from the transaction list.

name
string

Name of originator or recipient

type
string
Valid values:
  • Transfer
  • Standing order
  • Direct debit
  • Salary or rent
  • GeldKarte
  • Charges or interest
  • Direct debit

Transaction type to simplify your analysis of the users transaction

mandate_reference
string

HBCI: SEPA mandate reference (for SEPA direct debits), must be unique in combination with creditor_id

account_number
string

Account number of originator or recipient. This field might be empty if the transaction has no account number, e.g. interest transactions.

visited
boolean

DEPRECATED

modification_timestamp
string

Internal modification timestamp on the figo Connect server

Delete Transactions

DELETE /rest/transactions/{transaction_id}
Parameters
transaction_id
string required
Example: T1.1715

ID of transaction to delete. You can only delete one transaction at once.

Headers
Authorization: Bearer <transactions=rw>

Response 204

Transactions by Account

Read Transactions by Account

GET /rest/accounts/{account_id}/transactions{?cents,since,since_type,include_pending,type,sort,offset,count,until,filter,include_statistics}
Parameters
cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

since
string
Example: 2017-01-01T00:00:00.000Z

Return only transactions after this date based on since_type. This parameter can either be a transaction ID or an ISO date. Given at least one transaction matches the filter criterion, if provided as transaction ID the result will not contain this ID. If provided as ISO date, the result will contain this date. This behavior may change in the future.

since_type
enum[string]
Valid values:
  • booked
  • created
  • modified

This parameter defines how the parameter since will be interpreted.

include_pending
boolean
Default: false
Example: true

This flag indicates whether pending transactions should be included in the response. Pending transactions are always included as a complete set, regardless of the since parameter. Before caching a copy of the pending transactions, all existing pending transactions for the same account must be removed from the local cache.

sort
enum[string]
Valid values:
  • asc
  • desc

Determine whether results will be sorted in ascending or descending order.

type
array[Transaction Type]
Example: Transfer,Standing order

A list of transactions types which the transactions are filtered by.

offset
number
Example: 200

Skip this number of transactions in the response. In combination with the count parameter this can be used to paginate the result list.

count
number
Default: 1000
Example: 100

Limit the number of returned transactions. In combination with the offset parameter this can be used to paginate the result list.

until
string
Example: 2017-01-01T00:00:00.000Z

Return only transactions which were booked on or before this date. Please provide as ISO date. It is not possible to use the since_type semantics with until.

filter
string
Example: date:2017-02-03

Filter transactions by given key:value combination. Possible keys: date (maps to booking_date, please use ISO date here, not datetime), person (maps to payer/payee name), purpose, amount. Values are interpreted using wildcards: person:Max Mustermann will match %Max Mustermann%.

include_statistics
boolean
Default: false
Example: true

If true includes statistics on the returned transactions: maximum deposit, total deposits, maximum expense, total expenses.

Headers
Authorization: Bearer <transactions=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "deleted": [],
  "status": {
    "code": 1,
    "sync_timestamp": "2017-02-16T18:27:25.000Z",
    "success_timestamp": "2017-02-16T18:27:25.000Z"
  },
  "statistics": {
    "deposit_max": 1612.12,
    "deposit_sum": 61284.51,
    "expense_max": 599.95,
    "expense_sum": 12589.19
  },
  "transactions": [
    {
      "value_date": "2017-01-03T00:00:00.000Z",
      "bank_name": "Demobank",
      "account_id": "A1.1",
      "bank_code": "90090042",
      "currency": "EUR",
      "purpose": "A2432122990100992929929",
      "transaction_code": 4,
      "booked": true,
      "booking_date": "2017-01-03T00:00:00.000Z",
      "name": "Amazing Services Europe",
      "creation_timestamp": "2017-01-04T14:44:16.000Z",
      "amount": -19.9,
      "account_number": "4711951501",
      "iban": "DE67900900424711951500",
      "bic": "DEMODE01",
      "visited": false,
      "modification_timestamp": "2017-01-04T14:44:16.000Z",
      "type": "Direct debit",
      "transaction_id": "T1.1715",
      "booking_text": "Lastschrift",
      "categories": [
        {
          "id": 162,
          "parent_id": 150,
          "name": "Spende"
        }
      ],
      "additional_info": {
        "gross_amount": 0,
        "fee": 0
      }
    }
  ]
}
deleted
array[string]

List of deleted transaction IDs

status
object

Synchronization status

sync_timestamp
string

Timestamp of last synchronization. For multiple accounts, the oldest timestamp is displayed.

code
number

DEPRECATED

message
string

Human-readable error message

success_timestamp
string

Timestamp of last successful synchronization. For multiple accounts, the oldest timestamp is displayed.

statistics
object

Statistics on the transactions

deposit_sum
number

Sum of deposits

deposit_max
number

Maximum deposit amount

expense_max
number

Maximum expense amount

expense_sum
number

Sum of expenses

transactions
array[object]

List of transactions for this user

value_date
string

Value date

prima_nota_number
string

HBCI: Bank-internal number to group and identify transactions

currency
string

Three-character currency code (ISO 4217:2015)

end_to_end_reference
string

HBCI: A reference that can be filled by the payer of transaction, e.g. with your customer number

text_key_addition
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

customer_reference
string

HBCI: Customer reference, e.g. your insurance number

additional_info
object

Additional info on the transaction, if available.

reference_party_creditor
string

HBCI: Deviating receiver of the transfer

fee
number

Possible payed fees

reference_party_debitor
string

HBCI: Deviating sender of the transfer

bank_reference
string

HBCI: Bank reference or instruction ID, can be filled by the payers bank

gross_amount
number

Gross amount of the transaction

debitor_id
string

HBCI: An identifier of the payer

compensation_amount
string

HBCI: Sum of reimbursement of out-of-pocket expenses plus processing fee in case of a national return / refund debit as well as an optional interest equalization (for SEPA direct debit returns)

original_amount
string

HBCI: Amount of the original direct debit (for SEPA direct debit returns)

booking_date
string

Booking date

creditor_id
string

HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with mandate_reference

amount
number

Transaction amount

sepa_purpose_code
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

booking_key
string

HBCI: A key that indicates the purpose of a transaction, also called "posting key"/"Buchungsschlüssel".

booking_text
string

Booking text. This field might be empty if the transaction has no booking text.

creation_timestamp
string

Internal creation timestamp on the figo Connect server

transaction_id
string

Internal figo Connect transaction ID

bank_name
string

Bank name of originator or recipient.

account_id
string

Internal figo Connect account ID

bank_code
string

Bank code of originator or recipient. This field might be empty if the transaction has no bank code, e.g. interest transactions.

sepa_remittance_info
string

HBCI: Pure purpose text without other SEPA fields.

bic
string

BIC of payer

iban
string

IBAN of payer

purpose
string

Purpose text. This field might be empty if the transaction has no purpose.

transaction_code
number

Transaction type as DTA Tx Key code.

categories
array[object]

List of categories for this transaction. Categories are stored in a tree, and the figo API returns a path from the root to the leaf. That is, the list of category objects is ordered from general to specific. Categories are only returned to users with scope at least categories=ro.

parent_id
number

ID of parent category

id
number

ID of category

name
string

Name of category

booked
boolean

Some banks provide information on transactions which have not yet been executed. These transactions are called pending, and the flag is set to false. As soon as the bank reports the execution of these transactions, this flag changes to true. If such a pending transaction fails to execute, it is automatically removed from the transaction list.

name
string

Name of originator or recipient

type
string
Valid values:
  • Transfer
  • Standing order
  • Direct debit
  • Salary or rent
  • GeldKarte
  • Charges or interest
  • Direct debit

Transaction type to simplify your analysis of the users transaction

mandate_reference
string

HBCI: SEPA mandate reference (for SEPA direct debits), must be unique in combination with creditor_id

account_number
string

Account number of originator or recipient. This field might be empty if the transaction has no account number, e.g. interest transactions.

visited
boolean

DEPRECATED

modification_timestamp
string

Internal modification timestamp on the figo Connect server

Read single Transaction by Account

GET /rest/accounts/{account_id}/{transaction_id}{?cents}
Parameters
account_id
string required
Example: A1.1

ID of the account related to the transaction

transaction_id
string required
Example: T1.1715

ID of a specific transaction

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer <transactions=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "value_date": "2017-01-03T00:00:00.000Z",
  "bank_name": "Demobank",
  "account_id": "A1.1",
  "bank_code": "90090042",
  "currency": "EUR",
  "purpose": "A2432122990100992929929",
  "transaction_code": 4,
  "booked": true,
  "booking_date": "2017-01-03T00:00:00.000Z",
  "name": "Amazing Services Europe",
  "creation_timestamp": "2017-01-04T14:44:16.000Z",
  "amount": -19.9,
  "account_number": "4711951501",
  "iban": "DE67900900424711951500",
  "bic": "DEMODE01",
  "visited": false,
  "modification_timestamp": "2017-01-04T14:44:16.000Z",
  "type": "Direct debit",
  "transaction_id": "T1.1715",
  "booking_text": "Lastschrift",
  "categories": [
    {
      "id": 162,
      "parent_id": 150,
      "name": "Spende"
    }
  ],
  "additional_info": {
    "gross_amount": 0,
    "fee": 0
  }
}
value_date
string

Value date

prima_nota_number
string

HBCI: Bank-internal number to group and identify transactions

currency
string

Three-character currency code (ISO 4217:2015)

end_to_end_reference
string

HBCI: A reference that can be filled by the payer of transaction, e.g. with your customer number

text_key_addition
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

customer_reference
string

HBCI: Customer reference, e.g. your insurance number

additional_info
object

Additional info on the transaction, if available.

reference_party_creditor
string

HBCI: Deviating receiver of the transfer

fee
number

Possible payed fees

reference_party_debitor
string

HBCI: Deviating sender of the transfer

bank_reference
string

HBCI: Bank reference or instruction ID, can be filled by the payers bank

gross_amount
number

Gross amount of the transaction

debitor_id
string

HBCI: An identifier of the payer

compensation_amount
string

HBCI: Sum of reimbursement of out-of-pocket expenses plus processing fee in case of a national return / refund debit as well as an optional interest equalization (for SEPA direct debit returns)

original_amount
string

HBCI: Amount of the original direct debit (for SEPA direct debit returns)

booking_date
string

Booking date

creditor_id
string

HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with mandate_reference

amount
number

Transaction amount

sepa_purpose_code
string

HBCI: Additional key to already existing transaction_key field, also called "business transaction key"/"Textschlüsselergänzng". It helps to find a finer purpose of a transaction.

booking_key
string

HBCI: A key that indicates the purpose of a transaction, also called "posting key"/"Buchungsschlüssel".

booking_text
string

Booking text. This field might be empty if the transaction has no booking text.

creation_timestamp
string

Internal creation timestamp on the figo Connect server

transaction_id
string required

Internal figo Connect transaction ID

bank_name
string

Bank name of originator or recipient.

account_id
string required

Internal figo Connect account ID

bank_code
string

Bank code of originator or recipient. This field might be empty if the transaction has no bank code, e.g. interest transactions.

sepa_remittance_info
string

HBCI: Pure purpose text without other SEPA fields.

bic
string

BIC of payer

iban
string

IBAN of payer

purpose
string

Purpose text. This field might be empty if the transaction has no purpose.

transaction_code
number

Transaction type as DTA Tx Key code.

categories
array[object]

List of categories for this transaction. Categories are stored in a tree, and the figo API returns a path from the root to the leaf. That is, the list of category objects is ordered from general to specific. Categories are only returned to users with scope at least categories=ro.

parent_id
number

ID of parent category

id
number

ID of category

name
string

Name of category

booked
boolean

Some banks provide information on transactions which have not yet been executed. These transactions are called pending, and the flag is set to false. As soon as the bank reports the execution of these transactions, this flag changes to true. If such a pending transaction fails to execute, it is automatically removed from the transaction list.

name
string

Name of originator or recipient

type
string
Valid values:
  • Transfer
  • Standing order
  • Direct debit
  • Salary or rent
  • GeldKarte
  • Charges or interest
  • Direct debit

Transaction type to simplify your analysis of the users transaction

mandate_reference
string

HBCI: SEPA mandate reference (for SEPA direct debits), must be unique in combination with creditor_id

account_number
string

Account number of originator or recipient. This field might be empty if the transaction has no account number, e.g. interest transactions.

visited
boolean

DEPRECATED

modification_timestamp
string

Internal modification timestamp on the figo Connect server

Delete Transaction by Account

DELETE /rest/accounts/{account_id}/transactions/{transaction_id}
Parameters
transaction_id
string required
Example: T1.1715

ID of transaction to delete. You can only delete one transaction at once.

Headers
Authorization: Bearer <transactions=rw>

Response 204

Payments

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.

API Calls

Create a Payment

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

POST /rest/accounts/{account_id}/payments
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

Headers
Content-Type: application/json
Authorization: Bearer
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "cents": false
}
name
string required

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number required

Order amount

iban
string required

IBAN of creditor or debtor.

purpose
string required

Purpose text

text_key_extension
number

DTA text key extension

type
string required
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "account_id": "A1.1",
  "payment_id": "P1.2073",
  "bank_name": "Demobank",
  "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
  "bank_additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "submission_timestamp": "null",
  "creation_timestamp": "2016-04-13T16:03:45.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Read Payments

View unsubmitted payments as stored in the figo database.

GET /rest/payments
Headers
Authorization: Bearer <payments=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "payments": [
    {
      "name": "John Doe",
      "iban": "DE67900900424711951500",
      "amount": 22.8,
      "purpose": "Thanks for all the fish.",
      "currency": "EUR",
      "text_key": 51,
      "text_key_extension": 0,
      "type": "SEPA transfer",
      "account_id": "A1.1",
      "payment_id": "P1.2073",
      "bank_name": "Demobank",
      "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
      "bank_additional_icons": {
        "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
        "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
        "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
        "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
        "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
        "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
        "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
        "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
        "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
      },
      "submission_timestamp": "null",
      "creation_timestamp": "2016-04-13T16:03:45.000Z",
      "modification_timestamp": "2016-04-13T16:03:45.000Z"
    }
  ]
}
payments
array[object]

List of payments

payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Read single Payment

View unsubmitted payment as stored in the figo database.

GET /rest/payments/{payment_id}
Parameters
payment_id
string
Example: P1.2073

Internal figo Connect ID of the payment

Headers
Authorization: Bearer <payments=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "account_id": "A1.1",
  "payment_id": "P1.2073",
  "bank_name": "Demobank",
  "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
  "bank_additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "submission_timestamp": "null",
  "creation_timestamp": "2016-04-13T16:03:45.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Read Payments by Account

GET /rest/accounts/{account_id}/payments
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

Headers
Authorization: Bearer <payments=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "payments": [
    {
      "name": "John Doe",
      "iban": "DE67900900424711951500",
      "amount": 22.8,
      "purpose": "Thanks for all the fish.",
      "currency": "EUR",
      "text_key": 51,
      "text_key_extension": 0,
      "type": "SEPA transfer",
      "account_id": "A1.1",
      "payment_id": "P1.2073",
      "bank_name": "Demobank",
      "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
      "bank_additional_icons": {
        "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
        "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
        "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
        "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
        "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
        "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
        "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
        "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
        "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
      },
      "submission_timestamp": "null",
      "creation_timestamp": "2016-04-13T16:03:45.000Z",
      "modification_timestamp": "2016-04-13T16:03:45.000Z"
    }
  ]
}
payments
array[object]

List of payments for given account

payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Read single Payment by Account

GET /rest/accounts/{account_id}/payments/{payment_id}
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

payment_id
string
Example: P1.2073

Internal figo Connect ID of the payment

Headers
Authorization: Bearer <payments=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "account_id": "A1.1",
  "payment_id": "P1.2073",
  "bank_name": "Demobank",
  "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
  "bank_additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "submission_timestamp": "null",
  "creation_timestamp": "2016-04-13T16:03:45.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Modify a Payment

PUT /rest/accounts/{account_id}/payments/{payment_id}
Headers
Content-Type: application/json
Authorization: Bearer <payments=rw>
Body
{
  "name": "John Doe Junior",
  "iban": "DE67900900424711951502",
  "amount": 33.9,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "cents": false
}
name
string

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

type
string required
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "type": "SEPA transfer",
  "account_id": "A1.1",
  "payment_id": "P1.2073",
  "bank_name": "Demobank",
  "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
  "bank_additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "submission_timestamp": "null",
  "creation_timestamp": "2016-04-13T16:03:45.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
payment_id
string

Internal figo Connect payment ID

bank_name
string

Bank name of creditor or debtor

modification_timestamp
string

Internal modification timestamp on the figo Connect server

name
string

Name of creditor or debtor

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

bank_code
string

DEPRECATED

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

account_id
string

Internal figo Connect ID of the account

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

text_key_extension
number

DTA text key extension

bank_icon
string

Icon of creditor or debtor bank

type
string
Valid values:
  • Transfer
  • SEPA transfer

Payment type

text_key
number

DTA text key

account_number
string

DEPRECATED

Submit a Payment to Bank Server

POST /rest/accounts/{account_id}/payments/{payment_id}/submit
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

payment_id
string required
Example: P1.2073

Internal figo Connect ID of the payment

Headers
Content-Type: application/json
Authorization: Bearer <submit_payments>
Body
{
  "redirect_uri": "https://figo.me/test",
  "state": "fP7XfLatwhrtu0sA",
  "tan_scheme_id": "M607.1"
}
state
string required

The value can be any kind of string that will be forwarded in the callback response message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

redirect_uri
string

At the end of the submission process a response will be sent to this callback URL. The value defaults to the first redirect URI configured for the client. This field may also assume the value close_window for use in the figo web interface. It implies that after completing a TAN challenge, the window is closed instead of triggering a redirect.

tan_scheme_id
string required

TAN scheme ID of user-selected TAN scheme

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor the submission process. Use this to call /task/progress.

Delete a Payment

DELETE /rest/accounts/{account_id}/payments/{payment_id}
Headers
Authorization: Bearer <payments=rw>

Response 204

Standing Orders

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.

API Calls

Create Standing Order  

POST /rest/accounts/{account_id}/payments/
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

Headers
Content-Type: application/json
Authorization: Bearer
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "cents": false,
  "type": "SEPA standing order",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-15",
  "last_execution_date": "2017-01-15"
}
execution_day
number required

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string required

The first date when the standing order will be executed

name
string required

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

interval
string required
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number required

Order amount

iban
string required

IBAN of creditor or debtor.

purpose
string required

Purpose text

text_key_extension
number

DTA text key extension

type
string required
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "cents": false,
  "type": "SEPA standing order",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-15",
  "last_execution_date": "2017-01-15",
  "standing_order_id": "S01.1",
  "account_id": "A1.1",
  "creation_timestamp": "2015-05-01T00:00:00.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
execution_day
number required

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string required

The first date when the standing order will be executed

name
string required

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string required
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

account_id
string

Internal figo Connect ID of the account

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number required

Order amount

iban
string required

IBAN of creditor or debtor.

purpose
string required

Purpose text

standing_order_id
string

Internal figo Connect standing order ID

text_key_extension
number

DTA text key extension

modification_timestamp
string

Internal modification timestamp on the figo Connect server

type
string required
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Read Standing Orders

GET /rest/standing_orders{?cents}
Parameters
cents
boolean
Default: false
Example: true

If true, the amount of the standing order will be shown in cents.

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "standing_orders": [
    {
      "name": "John Doe",
      "iban": "DE67900900424711951500",
      "amount": 22.8,
      "purpose": "Thanks for all the fish.",
      "currency": "EUR",
      "text_key": 51,
      "text_key_extension": 0,
      "cents": false,
      "type": "SEPA standing order",
      "interval": "quarterly",
      "execution_day": 15,
      "first_execution_date": "2015-05-15",
      "last_execution_date": "2017-01-15",
      "standing_order_id": "S01.1",
      "account_id": "A1.1",
      "creation_timestamp": "2015-05-01T00:00:00.000Z",
      "modification_timestamp": "2016-04-13T16:03:45.000Z"
    }
  ]
}
standing_orders
array[object]

List of active standing orders

execution_day
number

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string

The first date when the standing order will be executed

name
string

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

account_id
string

Internal figo Connect ID of the account

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

standing_order_id
string

Internal figo Connect standing order ID

text_key_extension
number

DTA text key extension

modification_timestamp
string

Internal modification timestamp on the figo Connect server

type
string
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Read single Standing Order

GET /rest/standing_orders/{standing_order_id}{?cents}
Parameters
standing_order_id
string
Example: SO1.1

ID of a specific standing order

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "cents": false,
  "type": "SEPA standing order",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-15",
  "last_execution_date": "2017-01-15",
  "standing_order_id": "S01.1",
  "account_id": "A1.1",
  "creation_timestamp": "2015-05-01T00:00:00.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
execution_day
number required

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string required

The first date when the standing order will be executed

name
string required

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string required
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

account_id
string

Internal figo Connect ID of the account

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number required

Order amount

iban
string required

IBAN of creditor or debtor.

purpose
string required

Purpose text

standing_order_id
string

Internal figo Connect standing order ID

text_key_extension
number

DTA text key extension

modification_timestamp
string

Internal modification timestamp on the figo Connect server

type
string required
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Read Standing Orders by Account

GET /rest/account/{account_id}/standing_orders{?cents}
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

cents
boolean
Default: false
Example: true

If true, the amount of the standing order will be shown in cents.

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "standing_orders": [
    {
      "name": "John Doe",
      "iban": "DE67900900424711951500",
      "amount": 22.8,
      "purpose": "Thanks for all the fish.",
      "currency": "EUR",
      "text_key": 51,
      "text_key_extension": 0,
      "cents": false,
      "type": "SEPA standing order",
      "interval": "quarterly",
      "execution_day": 15,
      "first_execution_date": "2015-05-15",
      "last_execution_date": "2017-01-15",
      "standing_order_id": "S01.1",
      "account_id": "A1.1",
      "creation_timestamp": "2015-05-01T00:00:00.000Z",
      "modification_timestamp": "2016-04-13T16:03:45.000Z"
    }
  ]
}
standing_orders
array[object]

List of active standing orders

execution_day
number

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string

The first date when the standing order will be executed

name
string

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

account_id
string

Internal figo Connect ID of the account

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number

Order amount

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

standing_order_id
string

Internal figo Connect standing order ID

text_key_extension
number

DTA text key extension

modification_timestamp
string

Internal modification timestamp on the figo Connect server

type
string
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Read single Standing Order by Account

GET /rest/account/{account_id}/standing_orders/{standing_order_id}{?cents}
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

standing_order_id
string
Example: SO1.1

ID of a specific standing order

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "cents": false,
  "type": "SEPA standing order",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-15",
  "last_execution_date": "2017-01-15",
  "standing_order_id": "S01.1",
  "account_id": "A1.1",
  "creation_timestamp": "2015-05-01T00:00:00.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z"
}
execution_day
number required

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string required

The first date when the standing order will be executed

name
string required

Name of creditor or debtor

bank_code
string

DEPRECATED

cents
boolean

If true, the amount is submitted as cents.

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string required
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

account_id
string

Internal figo Connect ID of the account

last_execution_date
string

The last date when the standing order will be executed. The day of month must be the same as that of the first execution.

currency
string

Three-character currency code (ISO 4217:2015)

amount
number required

Order amount

iban
string required

IBAN of creditor or debtor.

purpose
string required

Purpose text

standing_order_id
string

Internal figo Connect standing order ID

text_key_extension
number

DTA text key extension

modification_timestamp
string

Internal modification timestamp on the figo Connect server

type
string required
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

text_key
number

DTA text key

account_number
string

DEPRECATED

Modify Standing Order

To modify an existing standing order, conduct the following steps:

  1. Synchronize accounts, including standingOrders in sync_tasks

  2. GET /rest/standing_orders and pick standing_order_id of the one to modify

  3. PUT /rest/accounts/<account_id>/payments with standing_order_id and fields to modify. Response contains a payment_id.

  4. POST /rest/accounts/<account_id>/payments/<payment_id>/submit to submit modified standing order to bank. Returns a task_token.

  5. Complete task as usual.

PUT /rest/accounts/{account_id}/payments
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

Headers
Content-Type: application/json
Authrorization: Bearer
Body
{
  "standing_order_id": "S01.1",
  "amount": 10,
  "name": "Max Mustermann",
  "purpose": "Thanks for all the fish.",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-01",
  "last_execution_date": "2017-01-01"
}
execution_day
number

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

first_execution_date
string

The first date when the standing order will be executed

name
string

Name of creditor or debtor

interval
string
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

amount
number

Transaction amount

purpose
string

Purpose text

standing_order_id
string required

Internal figo Connect ID of standing order to modify

last_execution_date
string

The last date when the standing order will be executed

Response 200

Headers
Content-Type: application/json
Body
{
  "name": "John Doe",
  "iban": "DE67900900424711951500",
  "amount": 22.8,
  "purpose": "Thanks for all the fish.",
  "currency": "EUR",
  "text_key": 51,
  "text_key_extension": 0,
  "account_id": "A1.1",
  "payment_id": "P1.2073",
  "bank_name": "Demobank",
  "bank_icon": "https://api.figo.me/assets/images/accounts/default.png",
  "bank_additional_icons": {
    "48x48": "https://api.figo.me/assets/images/accounts/default_48.png",
    "60x60": "https://api.figo.me/assets/images/accounts/default_60.png",
    "72x72": "https://api.figo.me/assets/images/accounts/default_72.png",
    "84x84": "https://api.figo.me/assets/images/accounts/default_84.png",
    "96x96": "https://api.figo.me/assets/images/accounts/default_96.png",
    "120x120": "https://api.figo.me/assets/images/accounts/default_120.png",
    "144x144": "https://api.figo.me/assets/images/accounts/default_144.png",
    "192x192": "https://api.figo.me/assets/images/accounts/default_192.png",
    "256x256": "https://api.figo.me/assets/images/accounts/default_256.png"
  },
  "submission_timestamp": "null",
  "creation_timestamp": "2016-04-13T16:03:45.000Z",
  "modification_timestamp": "2016-04-13T16:03:45.000Z",
  "type": "SEPA standing order",
  "interval": "quarterly",
  "execution_day": 15,
  "first_execution_date": "2015-05-01",
  "last_execution_date": "2017-01-01"
}
last_execution_date
string

The last date when the standing order will be executed

currency
string

Three-character currency code (ISO 4217:2015)

text_key_extension
number

DTA text key extension

bank_additional_icons
object

Mapping from resolution to URL for additional resolutions of the banks icon.

60x60
string
84x84
string
192x192
string
256x256
string
96x96
string
72x72
string
144x144
string
120x120
string
48x48
string
text_key
number

DTA text key

type
string required
Valid values:
  • SEPA standing order

Payment type, must be set to SEPA standing order to be recognized as a standing order instead of a regular payment.

execution_day
number required

Identifier of the day when the standing order will be regularly executed. Permitted values depend on the interval.

bank_name
string

Bank name of creditor or debtor

account_id
string

Internal figo Connect ID of the account

bank_code
string

DEPRECATED

submission_timestamp
string nullable

Timestamp of submission to the bank server. Is null if payment has not been submitted yet.

iban
string

IBAN of creditor or debtor.

purpose
string

Purpose text

bank_icon
string

Icon of creditor or debtor bank

payment_id
string

Internal figo Connect payment ID

first_execution_date
string required

The first date when the standing order will be executed

name
string

Name of creditor or debtor

creation_timestamp
string

Internal creation timestamp on the figo Connect server.

interval
string required
Valid values:
  • weekly
  • monthly
  • two monthly
  • four monthly
  • quarterly
  • half yearly
  • yearly

Interval in which the standing order will be executed

amount
number

Order amount

account_number
string

DEPRECATED

modification_timestamp
string

Internal modification timestamp on the figo Connect server

Submit Standing Order

POST /rest/{account_id}/payments/{payment_id}/submit
Parameters
account_id
string required
Example: A1.1

Internal figo Connect ID of the account

payment_id
string required
Example: P1.2073

ID of a specific standing order

Headers
Content-Type: application/json
Authrorization: Bearer
Body
{
  "redirect_uri": "https://figo.me/test",
  "state": "fP7XfLatwhrtu0sA",
  "tan_scheme_id": "M607.1"
}
state
string required

The value can be any kind of string that will be forwarded in the callback response message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

redirect_uri
string

At the end of the submission process a response will be sent to this callback URL. The value defaults to the first redirect URI configured for the client. This field may also assume the value close_window for use in the figo web interface. It implies that after completing a TAN challenge, the window is closed instead of triggering a redirect.

tan_scheme_id
string required

TAN scheme ID of user-selected TAN scheme

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor a task

Delete Standing Order

DELETE /rest/accounts/{account_id}/payments/{standing_order_id}{?submit,continue,tan_scheme_id}
Parameters
standing_order_id
string required
Example: SO1.1

ID of a specific standing order

submit
boolean
Default: false
Example: true

If true, the standing order will be deleted from the figo Connect servers and the bank server. It this parameter is set to false, the standing order will be deleted from figo Connect backend only.

continue
boolean
Default: false
Example: false

If true, the standing order will deleted even when it was changed since the last sync. If this parameter is set to false, the standing order will not be deleted in case it is not in sync between figo and the corresponding bank.

tan_scheme_id
string
Example: M1.3

ID of the TAN scheme, used for deleting the standing order

Headers
Authorization: Bearer

Response 200

Headers
Content-Type: application/json
Body
{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKzLdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}
task_token
string

Token to monitor a task

Securities

Each depot account has a list of securities associated with it. In general the information provided for each security should be roughly similar to the contents of the printed or online depot listings available from the respective bank. Please note that not all banks provide the same level of detail.

Securities

Get single Security

GET /rest/accounts/{account_id}/securites/{security_id}{?cents}
Parameters
account_id
string required
Example: A1.4

ID of the account for which to retrieve securities

security_id
string required
Example: S1.2

ID of a specific security

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

Headers
Authorization: Bearer <securities=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "security_id": "S1.2",
  "account_id": "A1.4",
  "name": "Mustermann AG, Vorzugsaktien",
  "market": "XASX",
  "isin": "DE0123456790",
  "wkn": "123457",
  "currency": "EUR",
  "quantity": 100,
  "amount": 5460,
  "amount_original_currency": 0,
  "exchange_rate": 0,
  "price": 54.6,
  "price_currency": "EUR",
  "purchase_price": 42.75,
  "purchase_price_currency": "EUR",
  "visited": "false",
  "trade_timestamp": "1999-05-28T22:59:59.000Z",
  "creation_timestamp": "2014-07-01T22:00:00.000Z",
  "modification_timestamp": "2016-08-10T04:57:06.000Z"
}
amount_original_currency
number

Monetary value in trading currency

price_currency
string

Currency of trading price

modification_timestamp
string

Internal modification timestamp on the figo Connect server

trade_timestamp
string

Trading timestamp

account_id
string

Internal figo Connect account ID the security is held on

wkn
string

Wertpapierkennnummer (WKN), if available

purchase_price_currency
string

Currency of purchase price

price
number

Trading price

visited
string

DEPRECATED

currency
string

Account currency, three-character code (ISO 4217:2015)

amount
number

Monetary value in account currency

creation_timestamp
string

Internal creation timestamp on the figo Connect server

isin
string

String International Securities Identification Number

security_id
string

Internal figo Connect security ID

quantity
number

Quantity in stock

exchange_rate
number

Exchange rate between trading and account currency

purchase_price
number

Purchase price

market
string

Market the security is traded on

name
string

Name of the security

Get Securities

GET /rest/securities{?cents,since,since_type,offset,count,accounts}
Parameters
cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

since
string
Example: 2017-01-01T00:00:00.000Z

Return only securities after this ISO date, based on since_type.

since_type
enum[string]
Valid values:
  • traded
  • created
  • modified

This parameter defines how the parameter since will be interpreted.

offset
number
Example: 1000

Offset into the implicit complete list of securities used as starting point for the returned list of securities. In combination with the count parameter this can be used to paginate the result list.

count
number
Default: 1000
Example: 1000

Limit the number of returned securities. In combination with the offset parameter this can be used to paginate the result list.

accounts
array[string]
Example: A1.2,A1.4

Filter the securities to be only from these account IDs.

Headers
Authorization: Bearer <securities=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "deleted": [],
  "status": {
    "code": 1,
    "sync_timestamp": "2017-02-16T18:27:25.000Z",
    "success_timestamp": "2017-02-16T18:27:25.000Z"
  },
  "securities": [
    {
      "security_id": "S1.2",
      "account_id": "A1.4",
      "name": "Mustermann AG, Vorzugsaktien",
      "market": "XASX",
      "isin": "DE0123456790",
      "wkn": "123457",
      "currency": "EUR",
      "quantity": 100,
      "amount": 5460,
      "amount_original_currency": 0,
      "exchange_rate": 0,
      "price": 54.6,
      "price_currency": "EUR",
      "purchase_price": 42.75,
      "purchase_price_currency": "EUR",
      "visited": "false",
      "trade_timestamp": "1999-05-28T22:59:59.000Z",
      "creation_timestamp": "2014-07-01T22:00:00.000Z",
      "modification_timestamp": "2016-08-10T04:57:06.000Z"
    }
  ]
}
deleted
array[string]

List of deleted securities IDs

status
object

Synchronization status

sync_timestamp
string

Timestamp of last synchronization. For multiple accounts, the oldest timestamp is displayed.

code
number

DEPRECATED

message
string

Human-readable error message

success_timestamp
string

Timestamp of last successful synchronization. For multiple accounts, the oldest timestamp is displayed.

securities
array[object]

List of securities for this user

amount_original_currency
number

Monetary value in trading currency

price_currency
string

Currency of trading price

modification_timestamp
string

Internal modification timestamp on the figo Connect server

trade_timestamp
string

Trading timestamp

account_id
string

Internal figo Connect account ID the security is held on

wkn
string

Wertpapierkennnummer (WKN), if available

purchase_price_currency
string

Currency of purchase price

price
number

Trading price

visited
string

DEPRECATED

currency
string

Account currency, three-character code (ISO 4217:2015)

amount
number

Monetary value in account currency

creation_timestamp
string

Internal creation timestamp on the figo Connect server

isin
string

String International Securities Identification Number

security_id
string

Internal figo Connect security ID

quantity
number

Quantity in stock

exchange_rate
number

Exchange rate between trading and account currency

purchase_price
number

Purchase price

market
string

Market the security is traded on

name
string

Name of the security

Get Securities by Account

GET /rest/accounts/{account_id}/securities{?cents,since,since_type,offset,count}
Parameters
account_id
string required
Example: A1.4

ID of the account for which to retrieve securities

cents
boolean
Default: false
Example: true

If true, monetary amounts will be shown in cents.

since
string
Example: 2017-01-01T00:00:00.000Z

Return only securities after this ISO date, based on since_type.

since_type
enum[string]
Valid values:
  • traded
  • created
  • modified

This parameter defines how the parameter since will be interpreted.

offset
number
Example: 1000

Offset into the implicit complete list of securities used as starting point for the returned list of securities. In combination with the count parameter this can be used to paginate the result list.

count
number
Default: 1000
Example: 1000

Limit the number of returned securities. In combination with the offset parameter this can be used to paginate the result list.

Headers
Authorization: Bearer <securities=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "deleted": [],
  "status": {
    "code": 1,
    "sync_timestamp": "2017-02-16T18:27:25.000Z",
    "success_timestamp": "2017-02-16T18:27:25.000Z"
  },
  "securities": [
    {
      "security_id": "S1.2",
      "account_id": "A1.4",
      "name": "Mustermann AG, Vorzugsaktien",
      "market": "XASX",
      "isin": "DE0123456790",
      "wkn": "123457",
      "currency": "EUR",
      "quantity": 100,
      "amount": 5460,
      "amount_original_currency": 0,
      "exchange_rate": 0,
      "price": 54.6,
      "price_currency": "EUR",
      "purchase_price": 42.75,
      "purchase_price_currency": "EUR",
      "visited": "false",
      "trade_timestamp": "1999-05-28T22:59:59.000Z",
      "creation_timestamp": "2014-07-01T22:00:00.000Z",
      "modification_timestamp": "2016-08-10T04:57:06.000Z"
    }
  ]
}
deleted
array[string]

List of deleted securities IDs

status
object

Synchronization status

sync_timestamp
string

Timestamp of last synchronization. For multiple accounts, the oldest timestamp is displayed.

code
number

DEPRECATED

message
string

Human-readable error message

success_timestamp
string

Timestamp of last successful synchronization. For multiple accounts, the oldest timestamp is displayed.

securities
array[object]

List of securities for this user

amount_original_currency
number

Monetary value in trading currency

price_currency
string

Currency of trading price

modification_timestamp
string

Internal modification timestamp on the figo Connect server

trade_timestamp
string

Trading timestamp

account_id
string

Internal figo Connect account ID the security is held on

wkn
string

Wertpapierkennnummer (WKN), if available

purchase_price_currency
string

Currency of purchase price

price
number

Trading price

visited
string

DEPRECATED

currency
string

Account currency, three-character code (ISO 4217:2015)

amount
number

Monetary value in account currency

creation_timestamp
string

Internal creation timestamp on the figo Connect server

isin
string

String International Securities Identification Number

security_id
string

Internal figo Connect security ID

quantity
number

Quantity in stock

exchange_rate
number

Exchange rate between trading and account currency

purchase_price
number

Purchase price

market
string

Market the security is traded on

name
string

Name of the security

Notifications

Whenever the bank account of a user received new transactions, your application can asynchronously be notified via webhooks. For which events your applications gets called depends on the notification key used, which is described in the next section.

For a notification to be considered as delivered successfully, the webhook endpoint should return HTTP response codes in the range of 2xx or 3xx. Everything else will be assumed an error.

Callback Request Headers

On callback, figo Connect will set the user agent header to figo-notification/<figo-connect-version>, for example

User-Agent: figo-notification/3.0.0

Notification Keys

In order to create a notification, a notification key needs to be defined. This key tells figo Connect in which situation a notification is to be triggered. The following keys are available right now:

Account Balance

Triggered when the respective account balance changes

Notification key

/rest/accounts/{account_id}/balance

Authentication

Access token including scope balance=ro

Parameter Description
account_id Internal figo Connect account ID
inferior_limit Trigger if the balance of the account is under the provided value

Account Transactions

Triggered when an account has received new transactions

Notification key

/rest/accounts/{account_id}/transactions

Authentication

Access token including scope transactions=ro

Parameter Description
account_id Internal figo Connect account ID.
include_pending Trigger not only for booked but also for pending transactions.
more_expenses_then_deposits Trigger only if the sum of expenses in the current month exceeds the sum of deposits in the same time. Only combinable with include_pending
current_month_expense_goal Trigger only if the sum of expenses in the current month exceeds the provided value. Only combinable with include_pending
single_expense_goal Trigger only for expense transactions exceeding the provided value. Only combinable with include_pending
single_deposit_goal Trigger only for expense transactions exceeding the provided value. Only combinable with include_pending
purpose Trigger only on transactions whose purpose contains the provided value. Only combinable with include_pending
name Trigger only on transactions whose sender/receiver name contains the provided value. Only combinable with include_pending

All Transactions

Notification key

/rest/transactions

Authentication

Access token including scope transactions=ro

Parameter Description
include_pending Trigger not only for booked but also for pending transactions.

Auto-sync error

Triggered when the saved PIN of a user is not accepted from the corresponding bank while performing an auto sync.

Notification Key

/rest/accounts/{account_id}/sync?wrong_pin=1

Authentication

Access token including scope balance=ro transactions=ro

Test notification

Triggered immediately. This special notification key can be used to test the delivery of notifications. The notification message will be sent immediately and no registration occurs.

Notification Key

/rest/notifications/test

Notifications

Create Notification

POST /rest/notifications/
Headers
Content-Type: application/json
Authorization: Bearer <balance=ro>
Body
{
  "observe_key": "/rest/transactions",
  "notify_uri": "http://figo.me/test",
  "state": "qwe"
}
state
string

The value can be any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

observe_key
string

Notification key

notify_uri
string

Notification messages will be sent to this URL. The URL schemes https:// and http:// are used for webhooks.

Response 200

Headers
Content-Type: application/json
Body
{
  "observe_key": "/rest/transactions",
  "notify_uri": "http://figo.me/test",
  "state": "qwe",
  "notification_id": "N1.8324"
}
notification_id
string

Notification ID

state
string

The value can be any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

observe_key
string

Notification key

notify_uri
string

Notification messages will be sent to this URL. The URL schemes https:// and http:// are used for webhooks.

Read Notifications

GET /rest/notifications/{notification_id}
Headers
Authorization: Bearer <balance=ro>

Response 200

Headers
Content-Type: application/json
Body
{
  "notifications": [
    {
      "observe_key": "/rest/transactions",
      "notify_uri": "http://figo.me/test",
      "state": "qwe",
      "notification_id": "N1.8324"
    }
  ]
}
notifications
array[object]

List of notifications

notification_id
string

Notification ID

state
string

The value can be any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

observe_key
string

Notification key

notify_uri
string

Notification messages will be sent to this URL. The URL schemes https:// and http:// are used for webhooks.

Modify Notification

PUT /rest/notifications/{notification_id}
Headers
Content-Type: application/json
Authorization: Bearer <balance=ro>
Body
{
  "observe_key": "/rest/transactions",
  "notify_uri": "http://figo.me/test",
  "state": "qwe"
}
state
string

The value can be any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

observe_key
string

Notification key

notify_uri
string

Notification messages will be sent to this URL. The URL schemes https:// and http:// are used for webhooks.

Response 200

Headers
Content-Type: application/json
Body
{
  "observe_key": "/rest/transactions",
  "notify_uri": "http://figo.me/test",
  "state": "qwe",
  "notification_id": "N1.8324"
}
notification_id
string

Notification ID

state
string

The value can be any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain a user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

observe_key
string

Notification key

notify_uri
string

Notification messages will be sent to this URL. The URL schemes https:// and http:// are used for webhooks.

Delete Notification

DELETE /rest/notifications/{notification_id}
Headers
Authorization: Bearer <balance=ro>

Response 204

Task processing

As any interactions with a customers banks server might take some time, they are not synchronous with the requests causing them. Instead the figo API uses a task concept encapsulating such activities and providing an interface to query the current state of such a task. It also provides an interface to interact with the current task, such as entering a PIN (if not saved) or responding to a TAN challenge.

Polling task progress

Calls that return a task_token, like bank account setup, synchronization, or payment submission, create a task in the figo database. The task is not started until the client polls it for the first time. A task may result in a request to the client, like submitting the PIN (if it is not stored) or a TAN.

Displaying TAN challenges

Depending on the user selection, one of the following TAN challenge types might occur during task processing:

  • Text

    • A simple text should be displayed to the user. The text is passed-through from the bank and should explain the user what to do.
  • HTML

    • Similar to the Text case but using HTML to format the text
  • HHD

    • The data encodes an animated image processable by the users TAN generator. Please contact us in case you would like to provide native support for this in your application.
  • Matrix

    • An image which should be shown to the user. The image is encoded following RFC 2397.

API Calls

Interact with tasks

While the figo Connect server communicates with a bank server, your application can monitor its progress by periodically polling this method. This method will start a task on the first call if it wasn’t started already.

POST /task/progress{?id}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "continue": false
}
continue
boolean
Default: false

This flag signals to continue after an error condition or to skip a PIN or challenge-response entry

Response 200

Headers
Content-Type: application/json
Body
{
  "account_id": "A1.1",
  "challenge": {},
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": ""
}
account_id
string

Internal figo Connect account id

challenge
object

This object provides all information if a TAN is needed for further processing

error
object

Task error object

is_ended
boolean

Communication with the bank server has been completed.

is_waiting_for_pin
boolean

The figo Connect server waits for a PIN.

is_erroneous
boolean

An error occurred. Details can be found in the error object.

message
string

Status message or error message for currently processed account

is_waiting_for_response
boolean

The figo Connect server waits for a response to the parameter challenge.

If the requested task needs to receive a PIN this will be indicated in the /task/progress response.

Example:
{
  "account_id": "A1.1",
  "challenge": {},
  "error": null,
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": true,
  "is_waiting_for_response": false,
  "message" "Please provide PIN."
}
Response:
POST /task/progress{?id}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "continue": false,
  "pin": "secretpin123",
  "save_pin": true
}
continue
boolean
Default: false

This flag signals to continue after an error condition or to skip a PIN or challenge-response entry

pin
string

PIN/Password to the user's online banking account

save_pin
boolean
Default: false

This flag indicates whether the given PIN should be saved on the figo Connect server

Response 200

Headers
Content-Type: application/json
Body
{
  "account_id": "A1.1",
  "challenge": {},
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": ""
}
account_id
string

Internal figo Connect account id

challenge
object

This object provides all information if a TAN is needed for further processing

error
object

Task error object

is_ended
boolean

Communication with the bank server has been completed.

is_waiting_for_pin
boolean

The figo Connect server waits for a PIN.

is_erroneous
boolean

An error occurred. Details can be found in the error object.

message
string

Status message or error message for currently processed account

is_waiting_for_response
boolean

The figo Connect server waits for a response to the parameter challenge.

More information on how to encrypt the credentials with JWE can be found here.

POST /task/progress{?id}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "continue": false,
  "pin": {
    "type": "encrypted",
    "value": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIifQ.EdCMnSp7M_0UQEe5mPGuQtNf3hcaPcjQ3tbmfEkjV5wa-6mZMnhCD6Zq0U0anft4iuaBLQha-EAflD-7D2Wl6MfZeFYka_TC9flrV-av-cxDvzP2r4Cj_YedmBj3EOLawz4YRo_s65dX7hvwsdd--uOxXbdx-UXYLvDxykh8E1M1mfjdLFwpeGgVILPhJeURMglWttovrB22cEV8UASNHV7dDfvyqKIfYfecxCqKvr-D6bnyZf6w-Jp49GLNCXz9e6ZgDD521Z_Ci_-bBEwbQdIUkNLuGtFLKUuiv1oMinBzwOrAlREL1zOnem06olXpcSCZE_Esto80ISWHOW0k3w.-0imErCMK7ahidc0d0ivwg.K4_6p6qT6W7jILdLjeZMww.slCawx18gWmPRCSPWOePC46OcweOve_B7DA0Kj6Wkdk"
  }
}
continue
boolean
Default: false

This flag signals to continue after an error condition or to skip a PIN or challenge-response entry

pin
object
type
string
Valid values:
  • encrypted
value
string

Encrypted PIN

Response 200

Headers
Content-Type: application/json
Body
{
  "account_id": "A1.1",
  "challenge": {},
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": ""
}
account_id
string

Internal figo Connect account id

challenge
object

This object provides all information if a TAN is needed for further processing

error
object

Task error object

is_ended
boolean

Communication with the bank server has been completed.

is_waiting_for_pin
boolean

The figo Connect server waits for a PIN.

is_erroneous
boolean

An error occurred. Details can be found in the error object.

message
string

Status message or error message for currently processed account

is_waiting_for_response
boolean

The figo Connect server waits for a response to the parameter challenge.

For some tasks you’ll have to provide TAN response to a TAN challenge. If this kind of response is necessary, the /task/progress response will indicate that.

Example:
{
  "account_id": "A1.1",
  "challenge": {
    "data": "<PHOTO TAN DATA>",
    "format": "Matrix",
    "label": "photoTAN"
  },
  "error": null,
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": true,
  "message" "Please provide response."
}
POST /task/progress{?id}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "continue": false,
  "response": "11111"
}
continue
boolean
Default: false

This flag signals to continue after an error condition or to skip a PIN or challenge-response entry

response
string

Response to TAN challenge

Response 200

Headers
Content-Type: application/json
Body
{
  "account_id": "A1.1",
  "challenge": {},
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": ""
}
account_id
string

Internal figo Connect account id

challenge
object

This object provides all information if a TAN is needed for further processing

error
object

Task error object

is_ended
boolean

Communication with the bank server has been completed.

is_waiting_for_pin
boolean

The figo Connect server waits for a PIN.

is_erroneous
boolean

An error occurred. Details can be found in the error object.

message
string

Status message or error message for currently processed account

is_waiting_for_response
boolean

The figo Connect server waits for a response to the parameter challenge.

POST /task/progress{?id}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Content-Type: application/json
Authorization: Basic
Body
{
  "continue": false,
  "response": {
    "type": "encrypted",
    "value": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIifQ.P_IxB6UUAIOmhUnGx2NynW7CXyqKEaRAd2iCUVgJLGEI66qW8QcM6X0uB-RskSvnOl8noD5RlURbk7Eha8EmqGCGe0TdteYz2cs69V2vs8C9bcTGPTSumAxBsXsYm2Nqlv_7HXZyg5W8lJRx3QK3nAg3S8fuct5TfuxHqbi4o5Zw296AERgO1BIIaOtfO8YrGFIpuzvNMRrUefWIzudV6yIjhsMkKtMywXqR4bQPMkc46NEU6SWngzQT8jYENohPZ5NM6KU213KslfSAKo9rC4hXRjklzPaGGVYVjzw7VL62ueCUOPBJ_dLMWWm9sqF-Pg2TGJNnp8Tvxs0uDE8RJg.9PPpfzW8JKDtm2bRKm4kyw.jiRUmCt44jliQgJq1iKTJA.jXNibBVsqwEnB-AqKTgvy1hVU87x8srAGOvnhujFpiE"
  }
}
continue
boolean
Default: false

This flag signals to continue after an error condition or to skip a PIN or challenge-response entry

response
object
type
string
Valid values:
  • encrypted
value
string

Encrypted TAN

Response 200

Headers
Content-Type: application/json
Body
{
  "account_id": "A1.1",
  "challenge": {},
  "is_ended": false,
  "is_erroneous": false,
  "is_waiting_for_pin": false,
  "is_waiting_for_response": false,
  "message": ""
}
account_id
string

Internal figo Connect account id

challenge
object

This object provides all information if a TAN is needed for further processing

error
object

Task error object

is_ended
boolean

Communication with the bank server has been completed.

is_waiting_for_pin
boolean

The figo Connect server waits for a PIN.

is_erroneous
boolean

An error occurred. Details can be found in the error object.

message
string

Status message or error message for currently processed account

is_waiting_for_response
boolean

The figo Connect server waits for a response to the parameter challenge.

Cancel Task (DEPRECATED)

Depending on the task type, canceling it might not be possible. In addition if the task has ended in the mean time, it will still be canceled.

POST /task/cancel{?id}
Parameters
id
string required
Example: YYIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Authorization: Basic

Response 204

Headers
Content-Type: application/json

Start Task

Start communication with bank server. After your application obtained a task token, you can direct the user’s web browser to a popup window of figo Connect. The popup window will ask the user for their account PIN, perform two-factor authentication or ask for a TAN. It also displays status messages as the task proceeds.

GET /task/start{?id,redirect_uri}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Authorization: Basic

Response 302

Headers
Location: http://example.com

GET /task/start{?id,redirect_uri}
Parameters
id
string required
Example: YIO4UiH7PjdCGdnF36LNAHxbkjPLbizI...

Task token

Headers
Authorization: Basic

Response 200