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:
Access is read-only.
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 User Login:
demo@figo.me
Demo User Password:
demo1234
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.
IBAN:
DE67900900424711951500
BIC:
DEMODE01
Bank Code:
90090042
Account number:
4711951500
Username:
demo
Password:
demo
TAN:
111111
(constant for all transactions)
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:
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 offline
Just like figo Connect but including the use of OAuth 2 refresh tokens for offline access.
figo Connect light
Only using figo accounts as context for interaction.
figo Connect native
Similar to figo Connect, but using password-based login as well as allowing account creation directly inside your app.
Depending on the use-case of figo Connect inside your application, we will advise you on the most suitable implementation strategy. If you either have the need to change your integration strategy or the scope assigned to your client, please contact us.
Authenticating as Client
In this case no user is involved, but the client acts in a global context. This is mainly used for login and user management actions as well as viewing the catalog of supported banks and services. Client authentication is performed via HTTP Basic Auth with client ID as username and client secret as password.
Authenticating as User
In order to access any information belonging to a user, a client has to authenticate with a token linking itself to the user. This token is called an access token and contains information on the client, the user and the level of access the client has to the users data. In order to authenticate using such an access token the HTTP header is set to Authorization: Bearer <access token>
.
Such an access token is either returned, when
exchanging an authorization code after a successful OAuth login flow
logging in with the users credentials
exchanging a refresh token, which in turn gets returned at either of the aforementioned points
Authentication Errors
In case of an authentication error a HTTP code 401
response is returned containing further
details on the kind of error in the WWW-Authenticate
header.
Scope
This API uses the following OAuth scopes for managing what your client can do at best. In case of using figo Connect, these can be further limited by the user connecting your application to his figo account. When registering your application we will advise you on the most suitable scope and if you encounter a need to change it, please contact us.
The following scopes designed the level of access your application has, each one
can be either read-only ro
or read-write rw
.
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:
This parameter must be set to |
||
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:
|
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:
|
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 |
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
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 |
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:
|
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 |
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:
|
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:
|
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 |
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
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. |
||||||||||||||||
|
|||||||||||||||||
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 |
||||||||||||||||
paymill_token
string
|
DEPRECATED |
||||||||||||||||
address
object
|
Postal address |
||||||||||||||||
|
|||||||||||||||||
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-Header
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-Header: 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 |
||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||
services
array[object]
|
List of supported payment services |
||||||||||||||||||||||||||
|
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-Header: 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 |
||||||||||||||||||||||||||
|
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-Header: 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 |
||||||||||||||||||||||||
|
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:
Type of financial providers to request. This can either be |
||
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 |
Headers
Authorization: Basic
Accept-Language-Header: 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 |
||||||||||||||||||
|
|||||||||||||||||||
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. |
||||||||||||||||||
|
|||||||||||||||||||
credentials
array[object]
|
List of credentials needed to connect to the service. |
||||||||||||||||||
|
|||||||||||||||||||
icon
string
required
|
Valid values:
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:
Determine the
bank_code
of the financial service to connect with. A list of supported banks and services can be retrieved fromGET /catalog
. Each entry also contains the required credentials format.Obtain the login credentials for the account.
Submit the credentials together with the bank code to
POST /rest/accounts
.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:
Valid values in array:
["transactions"]
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 |
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:
Valid values in array:
["transactions"]
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 |
||||
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. |
||||
|
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 |
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 |
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. |
||||||||||||||||||
|
|||||||||||||||||||
type
string
|
Valid values:
Account type |
||||||||||||||||||
status
object
|
Synchronization status |
||||||||||||||||||
|
|||||||||||||||||||
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 |
||||||||||||||||||
|
|||||||||||||||||||
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 |
||||||||||||||||||
|
|||||||||||||||||||
in_total_balance
boolean
|
DEPRECATED |
||||||||||||||||||
account_number
string
|
The old school account number |
||||||||||||||||||
balance
object
|
Account balance |
||||||||||||||||||
|
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
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 |
credit_line
number
|
DEPRECATED This value is not used anymore and always set to |
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:
Valid values in array:
["transactions"]
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 |
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 |
||
since
string
|
Example:
2017-01-01T00:00:00.000Z Return only transactions after this date based on |
||
since_type
enum[string]
|
Valid values:
This parameter defines how the parameter |
||
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 |
||
sort
enum[string]
|
Valid values:
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
number
|
Default:
1000 Example:
100 Limit the number of returned transactions. In combination with the |
||
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 |
||
filter
string
|
Example:
date:2017-02-03 Filter transactions by given |
||
include_statistics
boolean
|
Default:
false Example:
true If |
||
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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statistics
object
|
Statistics on the transactions |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
transactions
array[object]
|
List of transactions for this user |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 |
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 |
||||||||||||||||
customer_reference
string
|
HBCI: Customer reference, e.g. your insurance number |
||||||||||||||||
additional_info
object
|
Additional info on the transaction, if available. |
||||||||||||||||
|
|||||||||||||||||
booking_date
string
|
Booking date |
||||||||||||||||
creditor_id
string
|
HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with |
||||||||||||||||
amount
number
|
Transaction amount |
||||||||||||||||
sepa_purpose_code
string
|
HBCI: Additional key to already existing |
||||||||||||||||
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 |
||||||||||||||||
|
|||||||||||||||||
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 |
||||||||||||||||
name
string
|
Name of originator or recipient |
||||||||||||||||
type
string
|
Valid values:
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 |
||||||||||||||||
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 |
||
since
string
|
Example:
2017-01-01T00:00:00.000Z Return only transactions after this date based on |
||
since_type
enum[string]
|
Valid values:
This parameter defines how the parameter |
||
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 |
||
sort
enum[string]
|
Valid values:
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
number
|
Default:
1000 Example:
100 Limit the number of returned transactions. In combination with the |
||
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 |
||
filter
string
|
Example:
date:2017-02-03 Filter transactions by given |
||
include_statistics
boolean
|
Default:
false Example:
true If |
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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statistics
object
|
Statistics on the transactions |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
transactions
array[object]
|
List of transactions for this user |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 |
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 |
||||||||||||||||
customer_reference
string
|
HBCI: Customer reference, e.g. your insurance number |
||||||||||||||||
additional_info
object
|
Additional info on the transaction, if available. |
||||||||||||||||
|
|||||||||||||||||
booking_date
string
|
Booking date |
||||||||||||||||
creditor_id
string
|
HBCI: SEPA creditor identifier (for SEPA direct debits), must be unique in combination with |
||||||||||||||||
amount
number
|
Transaction amount |
||||||||||||||||
sepa_purpose_code
string
|
HBCI: Additional key to already existing |
||||||||||||||||
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 |
||||||||||||||||
|
|||||||||||||||||
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 |
||||||||||||||||
name
string
|
Name of originator or recipient |
||||||||||||||||
type
string
|
Valid values:
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 |
||||||||||||||||
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:
compile all information on the payment by creating and modifying a payment object
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. Please contact us for more details. This format is designated as
HHD
in this API.
- 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. Please contact us for more details. This format is designated as
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.
- 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
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 |
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:
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 |
||||||||||||||||||
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. |
||||||||||||||||||
|
|||||||||||||||||||
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:
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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 |
||||||||||||||||||
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. |
||||||||||||||||||
|
|||||||||||||||||||
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:
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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 |
||||||||||||||||||
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. |
||||||||||||||||||
|
|||||||||||||||||||
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:
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 |
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:
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 |
||||||||||||||||||
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. |
||||||||||||||||||
|
|||||||||||||||||||
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:
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 |
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 |
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 |
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 |
interval
string
required
|
Valid values:
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:
Payment type, must be set to |
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 |
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 |
creation_timestamp
string
|
Internal creation timestamp on the figo Connect server. |
interval
string
required
|
Valid values:
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:
Payment type, must be set to |
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 |
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 |
||||||||||||||||||||||||||||||||||||||
|
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 |
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 |
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 |
creation_timestamp
string
|
Internal creation timestamp on the figo Connect server. |
interval
string
required
|
Valid values:
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:
Payment type, must be set to |
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 |
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 |
||||||||||||||||||||||||||||||||||||||
|
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 |
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 |
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 |
creation_timestamp
string
|
Internal creation timestamp on the figo Connect server. |
interval
string
required
|
Valid values:
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:
Payment type, must be set to |
text_key
number
|
DTA text key |
account_number
string
|
DEPRECATED |
Modify Standing Order ↑
To modify an existing standing order, conduct the following steps:
Synchronize accounts, including
standingOrders
insync_tasks
GET /rest/standing_orders
and pickstanding_order_id
of the one to modifyPUT /rest/accounts/<account_id>/payments
withstanding_order_id
and fields to modify. Response contains apayment_id
.POST /rest/accounts/<account_id>/payments/<payment_id>/submit
to submit modified standing order to bank. Returns atask_token
.
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 |
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:
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. |
||||||||||||||||||
|
|||||||||||||||||||
text_key
number
|
DTA text key |
||||||||||||||||||
type
string
required
|
Valid values:
Payment type, must be set to |
||||||||||||||||||
execution_day
number
required
|
Identifier of the day when the standing order will be regularly executed. Permitted values depend on the |
||||||||||||||||||
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 |
||||||||||||||||||
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:
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 |
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 |
||
continue
boolean
|
Default:
false Example:
false If |
||
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 |
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 |
||
since
string
|
Example:
2017-01-01T00:00:00.000Z Return only securities after this ISO date, based on |
||
since_type
enum[string]
|
Valid values:
This parameter defines how the parameter |
||
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
number
|
Default:
1000 Example:
1000 Limit the number of returned securities. In combination with the |
||
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 |
||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||
securities
array[object]
|
List of securities for this user |
||||||||||||||||||||||||||||||||||||||
|
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 |
||
since
string
|
Example:
2017-01-01T00:00:00.000Z Return only securities after this ISO date, based on |
||
since_type
enum[string]
|
Valid values:
This parameter defines how the parameter |
||
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
number
|
Default:
1000 Example:
1000 Limit the number of returned securities. In combination with the |
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 |
||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||
securities
array[object]
|
List of securities for this user |
||||||||||||||||||||||||||||||||||||||
|
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 |
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 |
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 |
||||||||
|
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 |
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 |
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
- Similar to the
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 |
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 |
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
|
|||||
|
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 |
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 |
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
|
|||||
|
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 |
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