NAV

Introduction

  /ffffff   /ffffff  /ff
 /ff__  ff /ff__  ff| ff
| ff  \ ff| ff  \ ff| ff
| ffffffff| ffffff  | ff
| ff__  ff| ff      | ff
| ff  | ff| ff      | ff
| ff  | ff| ff      | ff
|__/  |__/|__/      |__/

Welcome to the Fidor Banking API! Our API allows you to easily access your Fidor bank account, get information about your transaction history and submit various types of payments. In addition you may provide services for Fidor customers and access their accounts if certain conditions are met.

For general introduction to our developer program please visit our developer community.

Our API is RESTful, we use JSON format and OAuth2.0 authorization.

Endpoints

Here’s a quick overview of our API endpoints:

Method Endpoint Usage Returns
GET /users/current Get user’s data users
GET /customers Get customer data customers
POST /customers Create customer object customer
GET /accounts Get customer’s bank accounts accounts
POST /internal_transfers Send money to another fidor user
GET /internal_transfers Get all fidor-to-fidor transfers for the current user internal transfer
POST /fps_transfers Send money to another bank account through FPS
GET /fps_transfers Get all fps_transfers for the current user fps transfer
POST /sepa_credit_transfers Send money to another bank account through SEPA
GET /sepa_credit_transfers Get all sepa transfers for the current user sepa credit transfer
POST /batch_transfers Send money in batch either with internal or sepa credit transfer or both
GET /batch_transfers Get all batch transfers for the current user batch transfer
GET /transactions Get all transactions for the current user transaction
GET /creditor_identities Get all UCIs you can use to create SEPA Mandates creditor_identities
GET /sepa_mandates/ GET previously created SEPA Mandates sepa_mandates
POST /sepa_mandates Create a SEPA Mandate sepa_mandate
PUT /sepa_mandates/:id Update previously created SEPA Mandate sepa_mandate
GET sepa_direct_debits GET previously created SEPA Direct Debit sepa_direct_debits
POST sepa_direct_debits Create new SEPA Direct Debit sepa_direct_debit

Systems

To avoid confusion here’s a list of the Fidor systems and URLs you will be dealing with with:

URL System
www.fidorbank.uk Banking homepage, you can register here
apm.fidorbank.uk Application management environment for developers
aps.fidorbank.uk Sandbox endpoint (test environment)
api.fidorbank.uk Banking production endpoint (live environment)
docs.fidorbank.uk Developer documentation (You are here)
developer.fidor.de Developer community landing page

There are two environments with their respective security services:

Environment Login (Authentication) OAuth (Authorization) API
Testing/Simulation aps.fidorbank.uk (with sandbox accounts/logins) aps.fidorbank.uk aps.fidorbank.uk
Production banking.fidorbank.uk (with real accounts/logins) apm.fidorbank.uk api.fidorbank.uk

Getting Started

Welcome to the Fidor APIs, your direct access to the functions and services of the world’s most innovative Bank: Fidor Bank. To get started all you need is a (free) Fidor Community Account.

Create a Fidor Account

If you already have a Fidor bank account just follow the instructions on how to create an application.

If you do not have a Fidor account yet or would like to create a separate account for development visit Fidor Bank’s webpage Fidor UK and register. Registering for just a “Fidor Community Account” is sufficient for testing the API.

You will have to provide some personal information, a valid e-mail address and a mobile number (to send you a confirmation SMS). Please follow the illustrated step-by-step guide here.

You may extend your Fidor Account to a full blown bank account now, but you do not need to. You can do that at any time later.

Once you created your account you can go to the Application Manager.

Please do not confuse the Fidor Community Account with the Developer Community Account you need if you want to take part in the discussion in Developer Community Forums.

Add an Application (to use the API)

In order to use the API, you have to tell Fidor the name, purpose and some technical information of the your application that will connect to the Fidor API.

Please log in to the Application Manager with your Fidor account credentials and select “New App”. If you log in for the first time you have to accept the Terms of Service first.

You can add as many applications as you like.

Sandbox

Every application is provided with a dedicated test environment (sandbox). The sandbox comes with some test data and a dedicated sandbox user login to simulate an account holder.

Our sandbox offers you the same functionality as the live API, so you can start developing your application without risk of losing money or unintentionally altering data.

Using Starter Kits

We provide you with a set of Fidor Starter Kits. They have been created to help you understand how the API and the authentication works. You also can use the code samples as a starting point for your own application.

They work out of the box - you only have to adjust the URL and callback URL to where you put the program.

Until now we provide example applications for following programming languages/frameworks:

Our starter kits are also available on github . Please feel free to add your own code and libraries.

Develop and Debug

The developer tools Fidor schema, Fidor starter kits, Application Manager, sandbox environment and developer community are provided free of charge. You only pay for API usage once you submit your application for approval and it goes live.

Add and Change Scopes

Fidor APIs provide a wide range of functions and provide access to a wide range of banking services. In the Application Manager you have to decide and define the scope, i.e. the set of functions your application needs in order to work properly. Here your can also select whether your application only needs access to your own account or if you plan to provide the application to other people, so that the application needs access to their data and accounts.

Sandbox

Our sandbox environment offers an account simulation with the most important API functions. So once developed and tested with the sandbox environment, your application should be production ready.

For every new application a dedicated sandbox account is automatically created. The sandbox comes with some test data, so that you can start developing your application against the sandbox immediately.

To connect your application to the sandbox use the following URLs:

Function URL
Sandbox API https://aps.fidorbank.uk
Sandbox OAuth https://aps.fidorbank.uk/oauth

Along with this simulated bank accounts a sandbox user (with login and password) is created. A sandbox user is required during the authentication against the sandbox. You can see the login credential of this sandbox user when you select the sandbox tab in the Application Manager.

There you also find a button to reset the sandbox data if needed, and to retrieve and reset OAuth access tokens (for the sandbox only).

Please note that the sandbox is not (yet) a full CBS simulation. Restrictions include that you cannot create new customers, you cannot create accounts or sub accounts. And you cannot send money from one sandbox to another.

Understand OAuth

The Fidor API offers many functions to retrieve information from your and other people’s bank accounts, community accounts and much more. The extent of access your application needs is configured when you define the scope of your application in the Application Manager.

In order to actually access the account and retrieve the requested data, the account holder needs to authorize your application and allow it to access their account. This is achieved using OAuth 2.

Client facing apps vs. server side connection

Fidor customers have diverse use cases for the Fidor API, ranging from payment automation without any user interaction to situations where consumers will sit in front of the computer every time they use the application. Applications run on PCs, mobile devices, on premise service and in the cloud. All this has implications on time and means of authentication and authorization.

The primarily supported authentication method from Fidor is the 3 legged OAuth2 flow, that is particularly useful for server based client-facing apps and supports 3rd party application providing. The following discussion and documentation is based on that mode.

For applications to simply control your our own bank account via a pure server side connection we soon will provide an improved approval process, OAuth flow and OAuth features. Also mobile applications require special treatment. Please follow the discussion in the Developer Community, get in contact with us via e-mail or leave a message in the approval submission form.

Accountholder perspective

From the accountholder’s perspective the process works as follows:

Afterwards the accountholder is returned to your app which will make calls to the API and display the results.

Application perspective

From the perspective of your application, the OAuth2 process consists of three steps:

  1. you redirect the accountholder’s browser to the request authorization endpoint endpoint
  2. the request authorization endpoint returns an Authorization Code to your server after the accountholder was successfully authenticated
  3. you retrieve the OAuth bearer token from Fidor by sending your client_id and client_secret to the token endpoint along with the Authorization Code received in the previous step.

This bearer token is used to authenticate calls to the API. These three steps are elaborated in detail in the following sections:

Accountholder Redirect

https://apm.fidorbank.uk/oauth/authorize?client_id=<client_id>&redirect_uri=<callback_uri>&state=99MagiCat99&response_type=code

Response with redirect to application if authentication and authorization was successful

Status: 302 Found
Location: <callback_uri>?code=db997fa3aaba429a1a331c3ad36484e1&state=99MagicCat99

In order to retrieve an OAuth token to access an accountholder’s account, first instruct your application to redirect the accountholder’s browser to the request authorization endpoint.

/oauth/authorize?redirect_uri=<redirect_uri>&client_id=<client_id>&state=<state>&response_type=code

you will need to provide the following values:

For more details about this step, see OAUTH2 sec 4.1.1

Extract the Authorization Code

Once the Fidor server has authenticated the user and established authorization, it will redirect the user back to the redirect_uri you provided. Attached to this redirect uri will be the provided state parameter and a code parameter. For example, you would receive a call from the accountholder’s browser to:

<redirect_uri>?code=750c9d02197a2d0a2a37b12155b5c3d8&state=<state>

In this example the value of the Authorization Code is 750c9d02197a2d0a2a37b12155b5c3d8. You MUST check the state parameter to ensure it contains the same value you sent to the authorize endpoint. If not, you must discontinue processing at this point and should contact Fidor as this is likely an attempt to breach security!

In case authorization of your app failed, you will receive an error response from the server as described in OAuth2 sec 4.1.2.1. Authorization typically fails if the accountholder is not willing to allow your app to access their account.

Please refer to OAuth2 sec 4.1.2 for details concerning this step of the OAuth process.

Retrieve the OAuth Token

https://apm.fidorbank.uk/oauth/token?grant_type=authorization_code&code=db997fa3aaba429a1a331c3ad36484e1&redirect_uri=<callback_uri>&client_id=<client_id>

Authorization: Basic 'base64 encoded "<client_id>:<client_secret>"'

Response

{
  "access_token":"2013a0a2c0257fe218cadc67b5b30bcf",
  "token_type":"Bearer",
  "state":"99MagiCat99",
  "refresh_token":"Rc225c256efa3e6fa8e21e3e1ad3573cc"
 }

After you extract the code parameter from the server response, it is send via POST to the Access Token Request endpoint oauth/token as described in OAuth2 sec 4.1.3. This request also contains following parameters in the body of a POST request, using application/x-www-form-urlencoded encoding:

This http request to the token endpoint is authenticated using HTTP Basic Authentication. The client_id and client_secret parameters of your app are used as the basic userid-password credentials.

Access and Refresh Tokens

The server will either return an error (described in OAuth2 sec 5.2 or a JSON response containing the access_token, token information and a refresh_token.

The access token will be of type “Bearer” and needs to be included in the http Authorization header of subsequent requests to the API (see Bearer Token Usage)

Once the access_token has expired, the refresh_token may be used in order to retrieve a new valid access_token. Refresh token requests are addressed to the same endpoint as authorization grant request, but contain the following parameter, as described in OAuth2 §6:

Token Revocation

https://apm.fidorbank.uk/oauth/revoke?token=2013a0a2c0257fe218cadc67b5b30bcf

Authorization: Basic 'base64 encoded "<client_id>:<client_secret>"'

For security reasons, you should revoke a token after you no longer need it to ensure it is not misused. Token Revocation is handled according to RFC 7009. It’s very simple, just post the token you wish to cancel to the revocation endpoint (/oauth/revoke) in a paramter key called token. This request needs to be authorized by client_id and client_secret parameters which are provided via HTTP Basic authentication. Both access tokens and refresh tokens can be canceled in the same manner.

Overview of OAuth Parameters

The required parameters (client_id, client_secret and the redirect_uri) are available in the App Manager:

Setting Value (example)
Client ID 84b199c5b4cd9605
Client Secret 5af2806fd4ee8521250b68d0a6ab1e55
App URL http://localhost:4567
Allowed IP Addresses 84.32.22.12, 84.32.22.13, 84.32.22,14
Callback URLs http://localhost:4567
Terms of service URL http://myapp.com/tos
Customer Service URL http://myapp.com/customer
Customer Service Email [email protected]

More examples

The OAuth process is a bit daunting at first and may take some attempts to get right. In case you hvae problems retrieving a token we’ve provided sample implementations that handle the OAuth process. Have a look at out Starter Kits to see how OAuth can be implemented.

Check Headers

curl --header "Accept: application/vnd.fidor.de; version=1,text/json" --header "Content-Type: application/json" --header "Authorization: Bearer <your token>" https://api.fidorbank.uk/users/current

To successfully communicate with the Fidor API, you must provide 3 headers:

Header Value
Authorization Bearer ca48897797c9275d75e2d7a5bc778721
Accept application/vnd.fidor.de; version=1,text/json
Content-Type application/json

Throttling (Rate Limits)

GET https://api.fidorbank.uk/rate_limit

{
    "limit": 60,
    "remaining": 55,
    "reset": 155
}

In case you exceeded the rate limit:

{
    "code": 429,
    "message": "Rate limit exceeded. Please retry later."
}

We throttle our APIs by default to ensure maximum performance for all developers.

Rate limiting in version 1 of the API is primarily considered on a per-user basis — or more accurately, per access token in your control. Rate limits are determined globally for the entire application.

Rate limits in version 1 of the API are divided into 15 minute intervals. In the version 1 of the API rate limit is 60 calls every 15 minutes, but this value may be adjusted at our discretion.

Rate Limit Headers

For you to make a better prediction about the API rate limit for your application or user, please use the X-RateLimit-* headers.

We provide three context based headers for this purpose:

HTTP Header Description
X-RateLimit-Limit The rate limit ceiling for all requests / 15-min window
X-RateLimit-Remaining The number of requests left for the the 15-min window
X-RateLimit-Reset The remaining window before the rate limit resets in e.g. UTC epoch seconds

When an application exceeds the rate limit, the Fidor API will return an HTTP 429 “Too Many Requests” response code (HTTP Status Code Documentation).

For your convenience we provide an endpoint for requesting the current state of your rate limit GET https://api.fidorbank.uk/rate_limit

Pagination

Not all available data is dumped at once. With pagination you can control the output and navigate through the pages.

https://api.fidorbank.uk/transactions?page=2&per_page=100 https://api.fidorbank.uk/preauths?page=1&per_page=20

Parameter Description
per_page Per page limit of the entries shown. Default is 10, max is 100
page The pagination offset

Collection

Most data you get from the API will have a supplementary collection object to provide information about the pagination and indicate your current place in a collection.

"collection": {
    "current_page": 1,
    "per_page": 10,
    "total_entries": 785,
    "total_pages": 79
}
Parameter Description
current_page Current page of output
per_page Number of entries per page
total_entries Total number of entries found
total_pages Total number of pages based on the given pagination

Manage Teams

To help you develop your apps faster, we’ve built the team management functionality directly into the Application Manager. To invite your fellow developers just open the team management view and enter the email address or the name of the developer you would like to invite to your team. Make sure that he or she logged in to the Application Manager before at least once.

Approval and Operation

Once you have successfully tested your application you can switch from “test-mode” to “live-mode”. Once approved, your application will work with real accounts, real data and real money.

Prerequisites

At the moment only developers that went through the complete bank account registration process and have a bank account (retail or business) with “full KYC status” can start the approval process for their applications. Please (re-)read the section 2 of ToS for additional prerequisites.

Note that only the developer that created (registered) an application initially (application owner) may submit it for approval.

We will introduce an approval concept soon that differentiates between the developer’s account and the full-KYC bank account the application needs access to. If you have such a situation please get in touch with our API support.

Approval Process

Most applications must go through a manual approval process, in particular if you require non-AGB services (e.g. SEPA direct debit) or your application needs access to third party accounts. In some cases you will have to sign additional contracts before your application can be approved and go live. If you are in doubt, please contact our sales team.

There are two basic access modes and approval types:

Approval Type Use Case Application can access …
Team Accounts Only one bank customer may use use the application … only one specific account
All Accounts Everybody may use the application to access their bank account … all bank accounts

After a Fidor admin reviewed your approval request you will receive an e-mail. If the admin requests changes or requires additional information you can re-submit the application as soon as the changes have been made.

Switch to Production

Once your application has been approved you can switch from the sandbox to the production environment.

To connect your application to the production environment use the following URLs:

Function URL
Production API https://api.fidorbank.uk
Production OAuth https://apm.fidorbank.uk/oauth

The Application Client ID and Secret stay the same.

Transport Layer Security (TLS) and Java

The TLS server in the production environment is configured not to allow weak ciphers specifications. Depending on what version of the Java you are using, it may be necessary to install the ‘Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files’ in order to be able to access the system. Please see: http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#importlimits and http://www.oracle.com/technetwork/java/javase/downloads/index.html for more information and download possibilities

Statistics

We will provide you with statistics for your application in the near future.

Check API Logs (soon)

In order to monitor your application, we will offer the ability to see and analyze log files directly in the Application Manager. Every application you create gets an “API Logs” view, where you see your application’s requests, the traffic your application is creating etc.

Changing the Scope of Your Application

If your application is live, changing the scope will result in all issued tokens being revoked. This means that anyone using your application has to go through the rights-granting process (OAuth) again the next they use the application.

Revoking And Deleting Your Application

The developer that submitted the application can revoke and or delete the application. Applications that have been revoked must go through the approval process again.

User view: Manage Installed Applications

All bank customers can see what applications they “installed” or “subscribed to” and get a detailed view of the rights they have granted to those applications. On the same page customers can “uninstall” applications and thus revoke rights. You will not be notified of revoked authorizations and must handle resulting errors during API calls.

Core Resources

Users

GET https://api.fidorbank.uk/users/current

{
    "id": "94070746",
    "email": "[email protected]",
    "last_sign_in_at": "2014-10-22T13:44:52+02:00",
    "created_at": "2014-10-10T17:41:58+02:00",
    "updated_at": "2014-10-23T14:49:21+02:00"
}

After authorization you can query the user data of the authorized account holder. You will only receive high-level user information. The following fields will be delivered upon requesting the user information:

Parameter Description Format
id Unique user identifier String
email The user’s email address that can also be used as login String
last_sign_in_at Last time the user accessed fidor String (date-time) ISO 8601 Date-Time
created_at Creation date-time, never changes String (date-time) ISO 8601 Date-Time
updated_at Last update date-time String (date-time) ISO 8601 Date-Time

HTTP Request

GET https://api.fidorbank.uk/users/current current user

Customers

GET https://api.fidorbank.uk/customers

{
    "data": [
        {
            "id": "71616244",
            "email": "[email protected]",
            "first_name": "John",
            "last_name": "Doe",
            "gender": "m",
            "title": "Herr",
            "nick": "kycfull",
            "maiden_name": null,
            "adr_street": "teststr",
            "adr_street_number": "2",
            "adr_post_code": "50733",
            "adr_city": "Köln",
            "adr_country": "DE",
            "adr_phone": null,
            "adr_mobile": "+49 555 55 55",
            "adr_fax": null,
            "adr_businessphone": null,
            "birthday": "1973-07-02",
            "is_verified": true,
            "nationality": null,
            "marital_status": null,
            "religion": 0,
            "id_card_registration_city": null,
            "id_card_number": null,
            "id_card_valid_until": null,
            "created_at": "2014-10-10T17:41:58+02:00",
            "updated_at": "2015-02-04T04:08:54+01:00",
            "creditor_identifier": ""
        }
    ],
    "collection": {
        "current_page": 1,
        "per_page": 10,
        "total_entries": 1,
        "total_pages": 1
    }
}

Customers gives you all the personal data of the customer

Parameter Description Format
id Unique customer identifier String
email The customer’s email address - same as the user’s email address String
first_name Customer’s first name String
last_name Customer’s last name String
gender Customer’s gender String (enum) - Valid Values: “m”, “f”
title Salutation e.g “Mr.” or “Mrs.” Enum
nick Nickname used in community - can be used as login String
maiden_name Customer’s maiden name String
adr_street Street address of the customer String
adr_street_number House number String
adr_post_code Postal code of the customer String
adr_city City customer lives in String
adr_country Country customer lives in String
adr_phone Customer’s phone number String
adr_mobile Customer’s mobile phone number String
adr_fax Customer’s fax number String
adr_businessphone Customer’s business phone number String
birthday Customer’s birthdate e.g. “1973-07-02” Date
is_verified Indicates whether KYC has been performed Boolean
nationality Customer’s nationality - Country code as defined in ISO3166 alpha2. e.g “DE”, “GB” String
marital_status Customer’s marital status Integer (enum) - 1: single, 2: married, 3: widowed, 4: divorced, 5: separated, 6: de facto
religion Customer’s religion - denomination for tax reasons. 0: no information, 1: no denomination, 2: Protestant, 3: Roman-Catholic, 4-18: Other denominations Integer (enum) - Valid Values “0”, “1”, “2”, “3”, “4”, “5”, “6”, “8”, “9”, “10”, “11”, “12”, “13”, “14”, “15”, “16”, “17”, 18"
id_card_registration_city The String
id_card_number The number of customer’s identity document
id_card_valid_until The expiration date of customer’s identity document String (date)
created_at Creation date-time, never changes. ISO 8601 Date-Time e.g. “2014-10-10T17:41:58+02:00” Datetime
updated_at Last update date-time. ISO 8601 Date-Time e.g. “2015-02-04T04:08:54+01:00” Datetime

Create a Customer

Check MSISDN

POST https://apm.fidorbank.uk/msisdn/check

{
  "msisdn"        : "491666666666",
  "os_type"       : "Android",
  "affiliate_uid" : "1398b666-6666-6666-6666-666666666666"
}

Response

Tm7YvR1ttXvSwWAs0t9Kz1Z6dwY6XcrKzH21gBpgyBRisIzn4R2X8DOAlqEV5Z44aXsN8A

In order to create a customer object the mobile phone number of the customer you’re about to create has to be verified first.

Arguments Description Format
msisdn Mobile phone Number in MSISDN format String in MSISDN format
os_type OS type of the customer’s mobile device String (enum) - “iOS” or “Android”
affiliate_uid Unique identifier of the affiliate for which customer is created String (e.g. "1398b666-6666-6666-6666-666666666666")

Verify MSISDN

POST https://apm.fidorbank.uk/msisdn/verify

{
  "msisdn" : "491666666666",
  "code"   : "Tm7YvR1ttXvSwWAs0t9Kz1Z6dwY6XcrKzH21gBpgyBRisIzn4R2X8DOAlqEV5Z44aXsN8A"
}

Response

rfjjEEwooyf1vYg-5rIu-VZVtIegy9DvsNWSq3pVfDIz9jVmUW3UsPnoARvbbhFFMuBHtg

Once you acquired a token for you mobile phone number verification. You have to assemble a verify request as following:

Arguments Description Format
msisdn Mobile phone Number in MSISDN format String in MSISDN format
code Verification code you acquired in the /msisdn/check step String

Create Customer Object

POST https://api.fidorbank.uk/customers

{
  "affiliate_uid" : "<your affiliate_uid we provide you with>",
  "email":"[email protected]",
  "password":"superDuperSecret",
  "adr_mobile":"4917666666666",
  "title":1,
  "first_name":"Walther",
  "additional_first_name" : "Heisenberg",
  "last_name":"White",
  "occupation" : "1",
  "gender":"m",
  "birthplace" : "Albuquerque",
  "birthday" : "1957-09-07",
  "nationality" : "US",
  "marital_status" : "1",
  "adr_street" : "Negra Arroyo Lane",
  "adr_street_number" : "308",
  "adr_post_code" : "87111",
  "adr_city" : "Albuquerque",
  "adr_country" : "US",
  "tos":true,
  "privacy_policy":true,
  "own_interest":true,
  "us_citizen":true,
  "us_tax_payer":true,
  "newsletter":true,
  "verification_token":"rrfjjEEwooyf1vYg-5rIu-VZVtIegy9DvsNWSq3pVfDIz9jVmUW3UsPnoARvbbhFFMuBHtg"
}

Creates a new customer object.

Arguments Description Format Mandatory
affiliate_uid Unique identifier of the affiliate for which customer is created String (e.g. "1398b666-6666-6666-6666-666666666666") x
email The customer’s email address - same as the user’s email address String
password Try to choose a secure password String x
adr_mobile Tell us your mobile phone number. We won’t call you, promise! :) String in MSISDN format x
tile Salutation Integer (enum), e.g. e.g 1 - "Mr." or 2 - "Mrs."
first_name Customer’s first name String x
last_name Customer’s last name String x
additional_first_name If you have an additional name just put it in here String
occupation Customer’s current occupation Integer (enum) 1 - employee, 2 - executive, 3 - self-employed, 4 - freelancer, 5 - student, 6 - trainee, 7 - retired, 8 - privatier, 9 - unemployed"
gender Customer’s gender String (enum) - Valid Values: “m”, “f” x
birthplace City of customer’s birth String
birthday Customer’s birthdate e.g. “1973-07-02” Date x
nationality Customer’s nationality - Country code as defined in ISO3166 alpha2. e.g “DE”, “GB” String
marital_status Customer’s marital status String (enum) - 1: single, 2: married, 3: widowed, 4: divorced, 5: separated, 6: de facto
adr_street Street address of the customer String
adr_street_number House number String
adr_post_code Postal code of the customer String
adr_city City customer lives in String
adr_country Country customer lives in String
verification_token Verification token from /msisdn/verify call String e.g. "rfjjEEwooyf1vYg-5rIu-VZVtIegy9DvsNWSq3pVfDIz9jVmUW3UsPnoARvbbhFFMuBHtg" x
nick Nickname used in community - can be used as login String
maiden_name Customer’s maiden name String
adr_phone Customer’s phone number String
adr_mobile Customer’s mobile phone number String x
adr_fax Customer’s fax number String
adr_businessphone Customer’s business phone number String
tos Terms of Service Boolean x
privacy_policy Privacy Policy Boolean x
own_interest Identifies if you act in your own interest Boolean x
us_citizen Please tell us if you hold US citizenship Boolean x
us_tax_payer And have to pay the taxes in US Boolean x
newsletter Wanna get Fidor’s newsletter? Boolean

Accounts

GET https://api.fidorbank.uk/accounts

{
    "data": [
                {
                    "id": "71616244",
                    "account_number": "9510260101",
                    "iban": "DE32700222009510260101",
                    "balance": 264398,
                    "balance_available": 264398,
                    "preauth_amount": 0,
                    "cash_flow_per_year": 0,
                    "is_debit_note_enabled": null,
                    "is_trusted": null,
                    "is_locked": false,
                    "currency": "EUR",
                    "overdraft": 0,
                    "created_at": "2014-10-10T17:41:58+02:00",
                    "updated_at": "2015-02-13T04:08:53+01:00",
                    "customers": [
                    {
                      "id": "71616244",
                      "email": "[email protected]",
                      "first_name": "John",
                      "last_name": "Doe",
                      "gender": null,
                      "title": "Herr",
                      "nick": "kycfull",
                      "maiden_name": null,
                      "adr_street": "teststr",
                      "adr_street_number": "2",
                      "adr_post_code": "50733",
                      "adr_city": "Köln",
                      "adr_country": "DE",
                      "adr_phone": null,
                      "adr_mobile": null,
                      "adr_fax": null,
                      "adr_businessphone": null,
                      "birthday": "1973-07-02",
                      "is_verified": true,
                      "nationality": null,
                      "marital_status": null,
                      "religion": 0,
                      "id_card_registration_city": null,
                      "id_card_number": null,
                      "id_card_valid_until": null,
                      "created_at": "2014-10-10T17:41:58+02:00",
                      "updated_at": "2015-02-13T04:08:53+01:00",
                      "creditor_identifier": ""
                    }
                 ]
              }
          ],
    "collection": {
        "current_page": 1,
        "per_page": 10,
        "total_entries": 1,
        "total_pages": 1
    }
}
Parameter Description Format
id Unique account identifier String
account_number The bank account number String
iban IBAN String
balance Account balance in minor units Integer
balance_available Available account balance in minor units Integer
preauth_amount Amount available for pre-authorization in minor units Integer
cash_flow_per_year Amount available for yearly cash flow in minor units. This is the limit of funds an account holder has at their disposal without fulfilling Germany KYC requirements Integer
is_debit_note_enabled Whether this account is authorized to initiate direct debit transactions Boolean
is_trusted Indicates if this is an escrow account Boolean
is_locked Indicates whether the account is locked Boolean
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
overdraft Available account overdraft in minor units Integer
created_at Creation date-time, never changes. ISO 8601 Date-Time e.g. “2014-10-10T17:41:58+02:00” Datetime
updated_at Last update date-time. ISO 8601 Date-Time e.g. “2015-02-04T04:08:54+01:00” Datetime

For your convenience we also include the information about the customers of the account in a response.

HTTP Requests

GET https://api.fidorbank.uk/accounts index

GET https://api.fidorbank.uk/accounts/{id} self

GET https://api.fidorbank.uk/accounts/{id}/transactions account transaction

GET https://api.fidorbank.uk/accounts/{id}/internal_transfers See also: Internal_transfers

GET https://api.fidorbank.uk/accounts/{id}/sepa_credit_transfers account SEPA credit transfers

GET https://api.fidorbank.uk/accounts/{id}/sepa_direct_debits See also: SEPA direct debit

Transactions

Transactions gives you a list of financial transactions that happened on the given account. In most cases not only the obvious transaction related data but also transaction_type_details are provided (see below).

GET https://api.fidorbank.uk/transactions/:id

{
  "id": "666",
  "account_id": "66666666",
  "transaction_type": "fidor_payout",
  "subject": "\"Send money to Friends\" recipient: Walter White: Heisenberg",
  "amount": -100000,
  "booking_code": "725",
  "booking_date": 2015-03-01,
  "value_date": "2015-03-02",
  "return_transaction_id": "",
  "created_at": "2015-03-02T13:58:59+01:00",
  "updated_at": "2015-03-02T13:58:59+01:00",
  "currency": "EUR",
  "transaction_type_details": {
    "internal_transfer_id": "666",
    "remote_account_id": "66666666",
    "remote_bic": "",
    "remote_iban": "",
    "remote_name": "",
    "remote_nick": "Heisenberg",
    "remote_subject": "Thanks for nothing"
}
Parameter Description Format
id Unique customer identifier String
account_id Fidor account the transaction belongs to String
transaction_type Type of the transaction String (enum)
subject Transfer subject (reference) String
amount The transferred amount in account currency, in minor units, e.g. 1EUR is represented as 100. Can be negative e.g. if something was withdrawn from an account. Integer
booking_code Accounting transaction code in the central banking system String
booking_date Date the transaction was booked. ISO 8601 Date String (date)
value_date Date the amount was credited to the account. ISO 8601 Date String (date)
return_transaction_id If the transaction was marked for return, this references the new return transaction String
created_at Creation date-time, never changes. ISO 8601 Date-Time e.g. “2014-10-10T17:41:58+02:00” Datetime
updated_at Last update date-time. ISO 8601 Date-Time e.g. “2015-02-04T04:08:54+01:00” Datetime
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
transaction_type_details Details specific to this transaction type are collected here

Transaction Type Details

Different transaction types contain different details specific for this particular type of the transaction. Some of the transaction types don’t have any specific attributes. In this case the transaction_type_details object remains empty.

Transaction Type Description Transaction Type Details
fidor_payin internal payment (in) internal_transfer_details
fidor_payout internal payment (out) internal_transfer_details
fps_payin FPS payment (in) fps_details
fps_payout FPS payment (out) fps_details
emoney_payin Giropay payment (in) internal_transfer_details
sepa_payin SEPA payment (in) sepa_credit_transfer_details
payout SEPA payment (out) sepa_credit_transfer_details
creditcard_* see below credit_card_details
sepa_core_direct_debit SEPA DD payment (out) standard sepa_credit_transfer_details
sepa_b2b_direct_debit SEPA DD payment (out) business sepa_credit_transfer_details
gmt_payout global money transfer (out) gmt_details
gmt_refund GMT refund (in) gmt_details
gmt_fee fee for GMT gmt_details
bonus Fidor bonus payment (in) bonus_details
prepaid_mobile_topup Topup for prepaid phones (out) mobile_topup_details
credit_interest interest payment (bank gives) -
debit_interest interest payment (bank takes) -
fee general fee (out) -
fee_giropay fee for Giropay usage (out) -
unknown unmapped transaction type -

Let’s take closer look at the transaction types Fidor supports currently.

Internal Transfer

Internal transfers are closed loop transaction (payments) from one Fidor bank account to another. Details of the internal_transfer object contain extensive information about the transaction’s initiator.

fidor_payin

fidor_payin

{
  "internal_transfer_id": "666",
  "remote_account_id": "66666666",
  "remote_bic": "FDDODEMMXXX",
  "remote_iban": "DE73700222000066666666",
  "remote_name": "Walther White",
  "remote_nick": "Heisenberg",
  "remote_subject": "Thanks for nothing"
}

In case of fidor_payin you will receive more information about the initiator of the payment.

Parameter Description Format
internal_transfer_id Unique account identifier of the transfer transaction belongs to. Refunded transactions have no id String
remote_account_id Unique account identifier of the payment’s sender String
remote_bic BIC of the transaction’s sender String
remote_iban IBAN of the transaction’s sender String
remote_name Full name of the transaction’s sender String
remote_nick Community nickname of the transaction’s sender String
remote_subject Subject of the transaction String

fidor_payout

fidor_payout

{
  "internal_transfer_id": "666",
  "remote_account_id": "66666666",
  "remote_bic": "",
  "remote_iban": "",
  "remote_name": "",
  "remote_nick": "Heisenberg",
  "remote_subject": "Thanks for nothing"
}

fidor_payout has the same structure but fewer details because of legal reasons.

Parameter Description Format
internal_transfer_id Unique account identifier of the transfer transaction belongs to. Refunded transactions have no id String
remote_account_id Unique account identifier of the payment’s sender String
remote_bic empty String
remote_iban empty String
remote_name empty String
remote_nick Community nickname of the transaction’s sender String
remote_subject Subject of the transaction String

FPS Transfer

Details of the fps_transfers object contain extensive information about the transaction’s initiator or receiver. We differentiate between the incoming fps_payin and outgoing fps_payout FPS transactions.

fps_payin or fps_payout

fps_payin, fps_payout

{
  "fps_transfer_id": "666",
  "remote_name": "Walther White (Heisenberg)",
  "remote_account": "87654321",
  "remote_sort_code": "654321"
}
Parameter Description Format
fps_transfer_id Unique account identifier of the transfer transaction belongs to. Refunded transactions have no id String
remote_name Full name of the transaction’s sender/receiver String
remote_account Account Number of the transaction’s sender/receiver String
remote_sort_code Sort Code of the transaction’s sender/receiver String

SEPA Credit Transfer

Details of the sepa_credit_transfers object contain extensive information about the transaction’s initiator or receiver. We differentiate between the incoming sepa_payin and outgoing payout SEPA transactions.

sepa_payin or payout

sepa_payin, payout

{
  "sepa_credit_transfer_id": "66666666",
  "remote_name": "Walther White",
  "remote_iban": "DE08100100100666666666",
  "remote_bic": "PBNKDEFFXXX"
}
Parameter Description Format
sepa_credit_transfer_id Unique account identifier of the transfer transaction belongs to. Refunded transactions have no id String
remote_name Full name of the transaction’s sender/receiver String
remote_iban IBAN of the transaction’s sender/receiver String
remote_bic BIC of the transaction’s sender/receiver String

SEPA Direct Debit (Lastschrift)

SDDs are payments that are automatically drawn from an account. There are two kinds: SEPA-Basislastschriften (SEPA Direct Debit CORE/COR1) and SEPA-Firmenlastschrift (SEPA Direct Debit B2B) which result in different transaction types: sepa_core_direct_debit and sepa_b2b_direct_debit. Both use the sepa_credit_transfer details object as described under SEPA Credit Transfer above.

Credit Card

Credit card usage is a complex topic with many different transaction types ranging from preauthentication to fees. All types share use the same credit_card object.

Transaction Type Description
creditcard_preauth Pre-authorize and block amount (depricated, see preauth)
creditcard_release Release pre-authorization and unblock amount (depricated, see preauth)
creditcard_payout Credit card payment (out)
creditcard_payin Credit card payment (in)
creditcard_annual_fee Annual card fee
creditcard_foreign_exchange_fee Fee for using the CC in a foreign country
creditcard_order_fee Fee for card ordering
creditcard_order_cancellation If card order is canceled, fee gets refunded
creditcard_order_withdrawal_fee Fee for cancelling card order
creditcard_atm_fee Fee for using the card at the ATM
creditcard_notification_fee Fee for transaction notification (e-mail, SMS)

credit_card details

{
  "cc_category": "R",
  "cc_merchant_category": "5411",
  "cc_merchant_name": "Metro Cash & Carry",
  "cc_sequence": 6666666,
  "cc_type": "00"
}
Parameter Description Format
cc_category CreditCard category String
cc_merchant_category Category given by the merchant String
cc_merchant_name CreditCard merchant initiating the transaction String
cc_sequence Sequence links all the credit_card related transactions together String
cc_type CreditCard type String

Global Money Transfer (GMT)

GMT payments are payments to countries outside the SEPA area. Details of the gmt_transfer object contain information about the transaction’s target.

gmt_payout, gmt_refund, gmt_fee

gmt_payout, gmt_refund, gmt_fee

{
  "destination_country": "AU",
  "destination_currency": "AUD",
  "amount_in_destination_currency": 12500,
  "exchange_rate": 1.4591,
  "fee_transaction_id": 2452334
}
Parameter Description Format
destination_country Destination country, 2 letter (ISO3166 alpha2) String
destination_currency Destination currency, 3 letter upcase (ISO 4217) String
amount_in_destination_currency Amount transferred in the destination currency Integer
exchange_rate Exchange rate (EUR/dest_curr) valid at the time of transfer Decimal
fee_transaction_id ID of fee transaction of this GMT transaction Integer

Bonus

Some activities in the community lead to bonus payments. The details are stored in the bonus_details object.

bonus

bonus

{
  "affiliate_id" : "16",
  "affiliate_name" : "ficoba_community",
  "affiliate_transaction_type_id" : "46",
  "affiliate_transaction_type_name" : "Geldfrage beantworten",
  "affiliate_transaction_type_category" : "Community"
}
Parameter Description Format
affiliate_id ID of the bonus affiliate String
affiliate_name Name of the bonus affiliate String
affiliate_transaction_type_id Identifier of the transaction type String
affiliate_transaction_type_name name of the transaction type String
affiliate_transaction_type_category category, e.g. Community, Banking, Bonusprogramm String

Mobile Topup

If you use the topup app in the account, transactions will be marked as prepaid_mobile_topup. The details are stored in the mobile_topup_details object.

prepaid_mobile_topup

prepaid_mobile_topup

{
  "provider" : "vodafone",
  "phone_number" : "1234567890123",
  "topup_subject" : "Nada DE Vodafone"
}
Parameter Description Format
provider name of the mobile network operator String
phone_number Mobile phone number user for topup String
topup_subject Subject of the mobile topup String

Transactions Filter

There are many ways to filter the output of transactions.

GET https://api.fidorbank.uk/transactions?filter[transaction_types]=Value&filter[booking_date_from]=Value

Using the filter returns only entries with … (see description)

Name Type Description
filter[id_from] string (integer) … ids >= the given id
filter[id_to] string (integer) … ids <= the given id
filter[booking_date_from] string (date-time) … booking_date >= the given date
filter[booking_date_to] string (date-time) … booking_date <= the given date
filter[transaction_types] string (enum), see transaction_types … the given type

Preauths

Prauths are blocked amounts that have been reserved for future payments. The money has not yet have been deducted from the account but is not available for other spending. This is usually used with credit cards but there are a lot of other use cases as well. The sum of all current preauths can be seen with accounts.preauth_amount.

GET https://api.fidorbank.uk/preauths/:id

{
  "id": "9123",
  "account_id": "1238343434",
  "amount": 2435,
  "currency": "EUR",
  "expires_at": "2015-02-03T13:02:45+01:00",
  "preauth_type": "creditcard_preauth",
  "preauth_type_details": {
    "cc_merchant_name": "Starbucks",
    "cc_merchant_category": "O",
    "cc_type": "IO",
    "cc_category": "C",
    "cc_sequence": "25",
    "pos_code": "POS",
    "financial_network_code": "CAN"
  },
  "created_at": "2015-02-03T06:23:43Z",
  "updated_at": "2015-02-03T06:23:43Z"
}
Parameter Description Format
id Unique preauth identifier String
account_id Fidor account the preauth belongs to String
preauth_type Type of the preauth String (enum)
amount The blocked amount in account currency, in minor units, e.g. 1 EUR is represented as 100. Will be set to 0 once preauth has been cleared. Can be negative e.g. if something was withdrawn from an account. Integer
expires_at Expiration date (if not cleared before). Default expiring time is 30 days. ISO 8601 Date-Time Datetime
created_at Creation date-time, never changes. ISO 8601 Date-Time e.g. “2014-10-10T17:41:58+02:00” Datetime
updated_at Last update date-time. ISO 8601 Date-Time e.g. “2015-02-04T04:08:54+01:00” Datetime
currency Currency of account or amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
preauth_type_details Details specific to this preauth type are collected here

Preauth Type Details

Different preauth types provide different preauth type details.

Preauth Type Description Preauth Type Details
creditcard_preauth credit_card_details
internal_transfer_preauth internal_transfer_details
capital_bond_preauth capital_bond_details
currency_order_preauth currency_order_details
gmt_preauth gmt_details
ripple_preauth ripple_details
unknown unmapped preauth type -

Let’s take closer look at the preauth types Fidor supports currently.

Credit Card

Details of the creditcard_preauth object contain information about the merchant and more.

{
  "cc_category": "R",
  "cc_merchant_category": "5411",
  "cc_merchant_name": "Metro Cash & Carry",
  "cc_sequence": 6666666,
  "cc_type": "00",
  "pos_code": "COD",
  "financial_network_code": "IXC23"
}
Parameter Description Format
cc_category CreditCard category String
cc_merchant_category Category given by the merchant String
cc_merchant_name CreditCard merchant initiating the transaction String
cc_sequence Sequence links all the credit_card related transactions together String
cc_type CreditCard type String
pos_code Code for point of service where card was used String
financial_network_code empty String

Internal Transfer

If internal money transfers cannot be completed (e.g. because the receiver does not have a Fidor account yet), the amount is blocked until the money is collected or the preauth expires. Details of the internal_transfer_preauth object contain information about the receiver of the payment.

{
  "internal_transfer_id": "666",
  "remote_account_id": "66666666",
  "remote_bic": "",
  "remote_iban": "",
  "remote_name": "",
  "remote_nick": "Heisenberg",
  "remote_subject": "Thanks for nothing"
}
Parameter Description Format
internal_transfer_id Unique account identifier of the transfer transaction belongs to. Refunded transactions have no id String
remote_account_id Unique account identifier of the payment’s sender String
remote_bic empty String
remote_iban empty String
remote_name empty String
remote_nick Community nickname of the transaction’s sender String
remote_subject Subject of the transaction String

Capital Bond

If you order a Fidor capital bond the amount gets blocked until the bond gets approved by Fidor. Details of the capital_bond_preauth object contain information about the bought capital bond.

Currency Order

If you buy foreign currencies with the in-account app in the web interface of your Fidor Smart Account, the amount of the purchase will be blocked until the payment process is completed. There is no API for currency order yet. Details of the currency_order_preauth object contain information about the currency order.

Global Money Transfer (GMT)

If you use Global Money Transfer (Auslandsüberweisung) the amount will be blocked until the transfer process is completed. Details of the gmt_preauth object contain information about the transaction’s target.

{
  "destination_country": "AU",
  "destination_currency": "AUD",
  "amount_in_destination_currency": 12500,
  "exchange_rate": 1.4591,
  "fee_transaction_id": 2452334
}
Parameter Description Format
destination_country Destination country, 2 letter (ISO3166 alpha2) String
destination_currency Destination currency, 3 letter upcase (ISO 4217) String
amount_in_destination_currency Amount transferred in the destination currency Integer
exchange_rate Exchange rate (EUR/dest_curr) valid at the time of transfer Decimal
fee_transaction_id ID of fee transaction of this GMT transaction Integer

Ripple details

If you send money via Ripple the amount will be blocked until the transfer has been completed. Details of the ripple_preauth object contain information about the transaction’s target.

Preauth Filter

There are many ways to filter the output of preauth.

GET https://api.fidorbank.uk/preauth?filter[transaction_types]=Value&filter[booking_date_from]=Value

Using the filter returns only entries with … (see description)

Name Type Description
filter[id_from] string (integer) … ids >= the given id
filter[id_to] string (integer) … ids <= the given id
filter[booking_date_from] string (date-time) … booking_date >= the given date
filter[booking_date_to] string (date-time) … booking_date <= the given date
filter[transaction_types] string (enum), see transaction_types … the given type

Money Transfer

We differentiate between different types of money transfers. In general we distinguish between the Fidor internal transfers (Fidor to Fidor money transfer) and external transfers (SEPA, GMT, FPS, BACS etc.).

Internal Transfer - Fidor to Fidor

Request body

{
  "account_id" : "37635844",
  "receiver": "[email protected]",
  "external_uid" : "0f25a5f8f",
  "amount" : 1500,
  "subject" : "Lunch, Monday. Thank you"
}

Response body

{
  "id": "940879",
  "subject": "Lunch, Monday. Thank you",
  "account_id": "37635844",
  "user_id": "7027",
  "receiver": "[email protected]",
  "amount": 1500,
  "state": "pending_receiver",
  "created_at": "2015-08-27T21:33:20Z",
  "updated_at": "2015-08-27T21:33:20Z",
  "currency": "EUR",
  "transaction_id": "940879",
  "external_uid": "0f25a5f8"
}

If you try to send a transfer twice

{
  "code": 409,
  "errors": [
  {
    "field": "external_uid",
    "message": "must be unique"
  }
  ],
  "message": "An order with this external_uid has already been placed"
}

Fidor offers you the possibility to transfer money to other Fidor users without even knowing their account number (“Freunden Geld senden”). To transfer the money you can use one of the following:

You can also initiate an internal transfer to the person, who doesn’t yet have an account at Fidor bank. In this case the amount will be blocked (see /preauths) and the recipient will be notified about the transferred amount and that they can open an account at Fidor bank to collect the money. The amount will be blocked for 14 days. After that time, the money will be credited back to the sender’s account.

POST Parameter

Parameter Description Format Mandatory
account_id Account identifier of the sender (/accounts/id) String x
receiver Recipient of the transfer. Possible values are: Fidor nickname, Fidor account identifier, twitter nickname, email address, mobile phone number String x
external_uid Unique ID given by the creator of the transfer. In case a uid is reused for a transfer, it is not executed, this mechanism can be used to prevent double bookings in case of network failure or similar event where transfer status is unknown String x
amount Amount of money you would like to send in account currency, in minor units, e.g. 1 EUR is represented as 100. Must be greater than 0 e.g. at least one cent in EUR Integer x
subject Subject of the transfer String

Response Parameter

Parameter Description Format
id ID of transfer Integer
subject Subject of the transfer as stated String
account_id Account identifier of the sender as stated String
user_id Customer ID of the sender Integer
receiver Recipient of the transfer as stated String
amount Amount as stated Integer
state State of transfer String
created_at Timestamp of creation String
updated_at Timestamp of last update String
currency Currency of transfer String
transaction_id ID of the corresponding transaction Integer
external_uid Unique external ID as stated String
Transfer states
State Description
success Transfer was successful
pending_receiver Transfer needs to be collected by receiver
expired Transfer expired and the money was returned

HTTP Request

GET https://api.fidorbank.uk/internal_transfers index

GET https://api.fidorbank.uk/internal_transfers/{id} self

POST https://api.fidorbank.uk/internal_transfers create

Example:

POST https://api.fidorbank.uk/internal_transfers

Request on /internal_transfers with the method POST.

FPS Transfer

Request body

{
  "account_id": "123456789",
  "external_uid": "666",
  "remote_account": "87654321",
  "remote_sort_code": "654321",
  "remote_name": "Walter White (Heisenberg)",
  "amount": "100000",
  "subject": "Here is your dirty money, Walter!"
}

Response body

{
  "id": "1",
  "external_uid": "666",
  "account_id": "123456789",
  "user_id": "4",
  "transaction_id": "840",
  "subject": "Hello World",
  "amount": 2342,
  "currency": "GBP",
  "fee": null,
  "remote_name": "Here is your dirty money, Walter!",
  "remote_account": "87654321",
  "remote_sort_code": "654321",
  "state": "received",
  "created_at": "2016-04-12T12:37:15Z",
  "updated_at": "2016-04-12T12:37:15Z"
}

If you try to send a transfer twice

{
  "code": 409,
  "errors": [
  {
    "field": "external_uid",
    "message": "must be unique"
  }
  ],
  "message": "An order with this external_uid has already been placed"
}

To transfer money to any recipient in the UK using Faster Payments use the fps_transfers endpoint.

Parameter Description Format Mandatory
account_id Account identifier of the sender (/accounts/id) String x
external_uid Unique ID given by the creator of the transfer. In case a uid is reused for a transfer, it is not executed, this mechanism can be used to prevent double bookings in case of network failure or similar event where transfer status is unknown String x
remote_account Account Number of the recipient’s bank account String x
remote_sort_code Sort Code of the recipient’s bank account. String x
remote_name Recipient’s full name String x
amount Amount of money you would like to send in in account currency, in minor units, e.g. 1EUR is represented as 100. Integer x
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
subject Subject of the transfer String
created_at Creation date-time, never changes String (date-time) ISO 8601 Date-Time
updated_at Last update date-time String (date-time) ISO 8601 Date-Time

HTTP Request

GET https://api.fidorbank.uk/fps_transfers index

GET https://api.fidorbank.uk/fps_transfers/{id} self

POST https://api.fidorbank.uk/fps_transfers create

SEPA Credit Transfer

Request body

{
  "account_id" : "123456789",
  "external_uid" : "666",
  "remote_iban": "AT131490022010010999",
  "remote_bic": "SPADATW1XXX",
  "remote_name" : "Walter White (Heisenberg)",
  "amount" : 100000,
  "subject" : "Here is your dirty money, Walter!"
}

Response body

{
  "id": "49",
  "account_id": "123456789",
  "user_id": "4",
  "subject": "Here is your dirty money, Walter!",
  "amount": 100000,
  "remote_name": "Walter White (Heisenberg)",
  "remote_iban": "AT131490022010010999",
  "remote_bic": "SPADATW1XXX",
  "state": "success",
  "created_at": "2015-03-04T13:47:48+01:00",
  "updated_at": "2015-03-04T13:47:48+01:00",
  "currency": "EUR",
  "transaction_id": "840",
  "external_uid": "666"
}

If you try to send a transfer twice

{
  "code": 409,
  "errors": [
  {
    "field": "external_uid",
    "message": "must be unique"
  }
  ],
  "message": "An order with this external_uid has already been placed"
}

To transfer money to any country participating in the SEPA (Single Euro Payments Area) initiative use the sepa_credit_transfers endpoint. If you want to send money to another bank account in Germany, you don’t even have to provide the BIC. IBAN is enough in that case.

Parameter Description Format Mandatory
account_id Account identifier of the sender (/accounts/id) String x
external_uid Unique ID given by the creator of the transfer. In case a uid is reused for a transfer, it is not executed, this mechanism can be used to prevent double bookings in case of network failure or similar event where transfer status is unknown String x
remote_iban IBAN of the recipient’s bank account String x
remote_bic BIC of the recipient’s bank account. Optional for transfers between two German bank accounts String (11 characters!)
remote_name Recipient’s full name String x
amount Amount of money you would like to send in in account currency, in minor units, e.g. 1EUR is represented as 100. Integer x
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
subject Subject of the transfer String
created_at Creation date-time, never changes String (date-time) ISO 8601 Date-Time
updated_at Last update date-time String (date-time) ISO 8601 Date-Time

HTTP Request

GET https://api.fidorbank.uk/sepa_credit_transfers index

GET https://api.fidorbank.uk/sepa_credit_transfers/{id} self

POST https://api.fidorbank.uk/sepa_credit_transfers create

Batch Transfer

GET https://api.fidorbank.uk/batch_transfers

{
    "data": [
        {
            "account_id": "71616244",
            "created_at": "2015-02-03T12:18:45+01:00",
            "external_uid": "216762",
            "id": "2",
            "internal_transfer_errors": [],
            "internal_transfer_ids": [
                "275"
            ],
            "sepa_credit_transfer_errors": [],
            "sepa_credit_transfer_ids": [
                "38"
            ],
            "state": "success",
            "success_url": "",
            "transfers_count": 2,
            "updated_at": "2015-02-03T12:18:45+01:00",
            "user_id": "4",
            "sepa_credit_transfers": [
                {
                    "id": "38",
                    "account_id": "71616244",
                    "user_id": "4",
                    "subject": "object",
                    "amount": 1,
                    "remote_name": "Walter Yoplack",
                    "remote_iban": "DE49140520002640025972",
                    "remote_bic": "",
                    "state": "received",
                    "created_at": "2015-02-03T12:18:42+01:00",
                    "updated_at": "2015-02-03T12:18:42+01:00",
                    "currency": "EUR",
                    "transaction_id": "",
                    "external_uid": "978991"
                }
            ],
            "internal_transfers": [
                {
                    "id": "275",
                    "subject": "object",
                    "account_id": "71616244",
                    "user_id": "4",
                    "receiver": "71616244",
                    "amount": 1,
                    "state": "success",
                    "created_at": "2015-02-03T12:18:42+01:00",
                    "updated_at": "2015-02-03T12:18:44+01:00",
                    "currency": "EUR",
                    "transaction_id": "275",
                    "external_uid": "494972"
                }
            ]
        },
        {
            "account_id": "71616244",
            "created_at": "2015-02-12T14:22:38+01:00",
            "external_uid": "595177",
            "id": "3",
            "internal_transfer_errors": [],
            "internal_transfer_ids": [
                "277"
            ],
            "sepa_credit_transfer_errors": [],
            "sepa_credit_transfer_ids": [
                "40"
            ],
            "state": "success",
            "success_url": "",
            "transfers_count": 2,
            "updated_at": "2015-02-12T14:22:38+01:00",
            "user_id": "4",
            "sepa_credit_transfers": [
                {
                    "id": "40",
                    "account_id": "71616244",
                    "user_id": "4",
                    "subject": "object",
                    "amount": 1,
                    "remote_name": "Walter Yoplack",
                    "remote_iban": "DE49140520002640025972",
                    "remote_bic": "",
                    "state": "success",
                    "created_at": "2015-02-12T14:22:37+01:00",
                    "updated_at": "2015-02-12T14:22:37+01:00",
                    "currency": "EUR",
                    "transaction_id": "800",
                    "external_uid": "835003"
                }
            ],
            "internal_transfers": [
                {
                    "id": "277",
                    "subject": "object",
                    "account_id": "71616244",
                    "user_id": "4",
                    "receiver": "71616244",
                    "amount": 1,
                    "state": "success",
                    "created_at": "2015-02-12T14:22:37+01:00",
                    "updated_at": "2015-02-12T14:22:38+01:00",
                    "currency": "EUR",
                    "transaction_id": "277",
                    "external_uid": "624437"
                }
            ]
        }
    ],
    "collection": {
        "current_page": 1,
        "per_page": 10,
        "total_entries": 4,
        "total_pages": 1
    }
}

PREVIEW: A batch transfer can contain multiple transfers which are processed asynchronously. You can include both internal_transfers and sepa_credit_transfers in your batch.

HTTP Request

GET https://api.fidorbank.uk/batch_transfers index

GET https://api.fidorbank.uk/batch_transfers/{id} self

POST https://api.fidorbank.uk/batch_transfers create

Global Money Transfers (coming soon)

Fidor provides worldwide transfers in different currencies.

In order to create one the user will need to accomplish the following steps:

  1. GET /options will give you the available countries, with their respective currencies.

  2. GET /new in order to retrieve the required fields for a transfer on the selected country.

  3. Proceeding with POST and the filled form, will provide the fee and the exchange_rate.

  4. Once that everything is agreed just PUT in order to execute the transfer.

Properties

Parameter Description Format Mandatory
beneficiary_name Beneficiary’s full name String
iban IBAN of the recipient’s bank account String
bic_swift BIC of the recipient’s bank String x
bank_account_type BIC of the recipient’s bank account. Optional for transfers between two German bank accounts String (enum) - checking or savings
beneficiary_entity_type Recipient’s full name String (enum) - individual or company x
beneficiary_company_name Company name of the recipient String
beneficiary_first_name Beneficiary’s first name String
beneficiary_last_name Beneficiary’s last name String
beneficiary_address Beneficiary’s address String
beneficiary_city City of the beneficiary String
beneficiary_postcode Beneficiary’s postal code String
beneficiary_state_or_province State or province beneficiary is living in String
subject Subject of the transfer String x
beneficiary_notification Indicates whether the recipient should be notified about the payment or not Boolean
beneficiary_email Beneficiary’s email address String
amount Amount of money you would like to send in in account currency, in minor units, e.g. 1EUR is represented as 100. Integer x
country Beneficiary’s country of residence, 2 letters (ISO3166 alpha2), e.g “DE”, “GB” String x
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter uppercase e.g “EUR” String (enum) x
created_at Creation date-time, never changes String (date-time) ISO 8601 Date-Time
updated_at Last update date-time String (date-time) ISO 8601 Date-Time

GET existent Global Money Transfers

List all the global money transfers for the current account.

GET http://api.fidorbank.uk/global_money_transfers

Show a specific one.

GET http://api.fidorbank.uk/global_money_transfers/{id}

GET avaliable countries and their currencies

GET http://api.fidorbank.uk/global_money_transfers/options

{
  "country_currency": [
    {
      "country": "AU",
      "currency": "AUD"
    },
    {
      "country": "CA",
      "currency": "CAD"
    },
    {
      "country": "CH",
      "currency": "CHF"
    },
    {
      "country": "DK",
      "currency": "DKK"
    },
    {
      "country": "GB",
      "currency": "GBP"
    },
    {
      "country": "NO",
      "currency": "NOK"
    },
    {
      "country": "PL",
      "currency": "PLN"
    },
    {
      "country": "SE",
      "currency": "SEK"
    },
    {
      "country": "US",
      "currency": "USD"
    }
  ]
}

Will retrieve all the pairs country-currency available.

GET http://api.fidorbank.uk/global_money_transfers/options

GET required fields for a specific country

It returns the required fields for the selected pair country-currency.

GET https://api.fidorbank.uk/global_money_transfers/new?country={country}¤cy={currency}

GET https://api.fidorbank.uk/global_money_transfers/new?country=PL¤cy=PLN

{
  "country": "PL",
  "currency": "PLN",
  "required_attributes": [
    "aba",
    "account_number",
    "amount",
    "bank_account_type",
    "beneficiary_address",
    "beneficiary_city",
    "beneficiary_company_name",
    "beneficiary_email",
    "beneficiary_first_name",
    "beneficiary_last_name",
    "beneficiary_notification",
    "beneficiary_postcode",
    "beneficiary_state_or_province",
    "beneficiary_type",
    "subject"
  ]
}

Create a Global Money Transfer

Creates a global money transfer. Calculates the fee. Calculates the exchange rate. Calculates the transferred amount in the destination currency.

POST http://api.fidorbank.uk/global_money_transfers

Request body

{
  "iban" : "PL61109010140000071219812874",
  "country" : "PL",
  "currency" : "PLN",
  "bic_swift" : "ALBPPLPW",
  "bank_account_type" : "checking",
  "beneficiary_entity_type" : "individual",
  "beneficiary_company_name" : "hola hola",
  "beneficiary_first_name" : "hola",
  "beneficiary_last_name" : "adios",
  "beneficiary_address" : "Unicorn Street 7",
  "beneficiary_city" : "Pontevedra",
  "beneficiary_postcode" : "80805",
  "beneficiary_state_or_province" : "Ohio",
  "subject" : "pay that",
  "beneficiary_notification" : "what a joke",
  "beneficiary_email" : "[email protected]",
  "amount" : "130"
}

Response body

{
  "aba": null,
  "account_id": "16820650",
  "account_number": null,
  "amount": 13000,
  "amount_in_euro": false,
  "bank_code": null,
  "bank_account_type": "test",
  "beneficiary_address": "Unicorn Street 7",
  "beneficiary_city": "Pontevedra",
  "beneficiary_company_name": "hola hola",
  "beneficiary_email": "[email protected]",
  "beneficiary_first_name": "hola",
  "beneficiary_last_name": "adios",
  "beneficiary_name": "hola adios",
  "beneficiary_notification": false,
  "beneficiary_postcode": "80805",
  "beneficiary_state_or_province": "Ohio",
  "beneficiary_type": "individual",
  "bic_swift": "ALBPPLPW",
  "branch_code": null,
  "country": "PL",
  "created_at": "2015-07-13T14:49:07Z",
  "destination_currency": "PLN",
  "exchange_rate": "4.0486",
  "external_uid": null,
  "failure_reason": null,
  "fee": 500,
  "iban": "PL61109010140000071219812874",
  "id": 4038,
  "refund_payment_subject": null,
  "refunded_amount": null,
  "refunded_amount_in_destination_currency": null,
  "refunded_exchange_rate": null,
  "state": "pending",
  "subject": "pay that",
  "transfered_amount": null,
  "transfered_amount_in_destination_currency": null,
  "updated_at": "2015-07-13T14:49:07Z"
}

PUT Executes the Transfer

To confirm the execution of the previously created global money transfer.

PUT http://api.fidorbank.uk/global_money_transfers/{id}/confirmation

Sepa Mandates and Direct Debits

In order to create a SEPA Direct Debit you have to create a SEPA Mandate first. Not every Fidor customer is eligible to create SEPA Mandates. If you are interested in SEPA Direct Debits and do not have a required account for creating SEPA Mandates you will need to contact Fidor first.

To be able to create mandates you have to acquire a Unique Creditor Identifier.

The Creditor Identifier for Germany is precisely 18 characters in length and is structured as follows

You can find more information about how to acquire a UCI (Unique Creditor Identifier) by following this link: Creditor Identifier

HTTP Requests

GET http://api.fidorbank.uk/creditor_identities index

GET http://api.fidorbank.uk/sepa_mandates index

GET http://api.fidorbank.uk/sepa_mandates/{id} self

POST http://api.fidorbank.uk/sepa_mandates create

PUT http://api.fidorbank.uk/sepa_mandates/{id} update

GET https://api.fidorbank.uk/sepa_direct_debits index

GET https://api.fidorbank.uk/sepa_direct_debits/{id} self

POST https://api.fidorbank.uk/sepa_direct_debits create

Creditor Identifiers

GET http://api.fidorbank.uk/creditor_identities

{
  "data": [
    {
      "id": "GB56ZZZDFFGFFO00000020150006",
      "account_id": "12345678",
      "created_at": "2015-04-07T13:33:59Z",
      "updated_at": "2015-04-07T15:54:48Z"
    },
    {
      "id": "DE37ZZZ08000000001",
      "account_id": "12345678",
      "created_at": "2015-04-07T13:46:08Z",
      "updated_at": "2015-04-08T08:45:33Z"
    }
  ],
  "collection": {
    "current_page": 1,
    "per_page": 10,
    "total_entries": 3,
    "total_pages": 1
  }
}

Once you acquired one or multiple UCIs (Unique Creditor Identifiers) you have to contact Fidor. We will store your UCIs related credentials in our system. To get the information about Creditor Identifiers available for your use, you have to call the /creditor_identities endpoint.

You will have to use one of the available creditor_identities to create sepa_mandates.

Parameter Description Format
id Unique Creditor Identifier String
account_id Account identifier of the sender (/accounts/id) String
created_at Creation date-time, never changes String (date-time) ISO 8601 Date-Time
updated_at Last update date-time String (date-time) ISO 8601 Date-Time

Creating SEPA Mandate

Once the SEPA mandate is stored successfully, you have the possibility to change the mandate by issuing a PUT request to /sepa_mandates/:id.

POST http://api.fidorbank.uk/sepa_mandates

{       
  "creditor_identity_id" : "DE37ZZZ08000000001",
  "external_uid" : "666",
  "mandate_reference": "666",
  "sequence": "RCUR",
  "cor1_option": "1",
  "remote_title": "Mr.",
  "remote_name": "Walter White",
  "remote_email": "[email protected]",
  "remote_address_line1": "308 Negra Arroyo Lane",
  "remote_address_line2": "Albuquerque, New Mexico, 87104",
  "remote_country": "US",
  "remote_iban": "DE08100100100666666666",
  "remote_bic": "FDDODEMMXXX",
  "signature_date": "2015-04-07",
  "valid_from_date": "2015-11-18"
}

GET http://api.fidorbank.uk/sepa_mandates/:id

{
  "id" : "66666",
  "customer_id" : "66666666",
  "creditor_identity_id" : "DE37ZZZ08000000001",
  "external_uid" : "666",
  "mandate_reference": "666",
  "sequence": "RCUR",
  "cor1_option": "1",
  "remote_title": "Mr.",
  "remote_name": "Walter White",
  "remote_email": "[email protected]",
  "remote_address_line1": "308 Negra Arroyo Lane",
  "remote_address_line2": "Albuquerque, New Mexico, 87104",
  "remote_country": "US",
  "remote_iban": "DE08100100100666666666",
  "remote_bic": "FDDODEMMXXX",
  "remote_ultimate_name": null,
  "remote_signature_location": null,
  "signature_date": "2015-04-07",
  "valid_from_date": "2015-11-18",
  "created_at": "2015-11-25T12:43:55Z",
  "updated_at": "2015-11-25T12:43:55Z"
}

PUT http://api.fidorbank.uk/sepa_mandates/:id

{
  "remote_title": "Mr.",
  "remote_name": "Walter Black",
  "remote_email": "[email protected]",
  "remote_address_line1": "545 Fifth Avenue",
  "remote_address_line2": "New York, New York, 10021",
  "remote_country": "US"
}
Parameter Description Format
creditor_identity_id Unique Creditor Identifier String
external_uid Unique ID of the creator of the transfer. In case a uid is reused for a transfer, it is not executed, this mechanism can be used to prevent double bookings in case of network failure or similar event where transfer status is unknown String
mandate_reference Unique Reference of the Mandate String
sequence Recurring or One-Time String (“RCUR” or “OOFF”)
cor1_option Use COR-1 Option String (“0” or “1”)
remote_title Title / Salutation of Debtor String (“Mr., "Mrs.”)
remote_name Full name of the debtor String
remote_email Email Address of the debtor String
remote_address_line1 Street and street number of the debtor String
remote_address_line2 ZIP and City of the debtor String
remote_country Country of the String (Country Code)
remote_iban IBAN of the transaction’s debtor String
remote_bic BIC of the transaction’s debtor String
signature_date Date of mandate signature String (Date)
valid_from_date Date, mandate is valid from String (Date)

Creating SEPA Direct Debit

POST https://api.fidorbank.uk/sepa_direct_debits

{
    "external_uid" : "666",
    "mandate_id": "666",
    "account_id" : "66666666",
    "eref" : "6",
    "amount" : "10000",
    "subject" : "We're taking your money back, Walter!",
    "collection_date" : "2015-04-27"
}

Once you created a sepa_mandate you can go on and create a corresponding sepa_direct_debit. In order to do so you have to make a POST request to /sepa_direct_debits endpoint with following request body.

Parameter Description Format
external_uid Unique ID of the creator of the transfer. In case a uid is reused for a transfer, it is not executed, this mechanism can be used to prevent double bookings in case of network failure or similar event where transfer status is unknown String
mandate_id Unique Reference of the Mandate String
account_id Account identifier of the sender String
amount Amount of money you would like to debit from the debtor, in minor units, e.g. 1EUR is represented as 100. Integer
currency Currency of Account or Amount. ISO 4217 alpha-3 - 3 letter upcase e.g EUR String (enum)
subject Subject of the direct debit String
collection_date Date of the money collection String (Date)

Batch Direct Debit

PREVIEW: A direct debit batch contains multiple direct debits which are processed asynchronously.

GET https://api.fidorbank.uk/batch_direct_debits/{id} self

GET https://api.fidorbank.uk/batch_direct_debits instances

POST https://api.fidorbank.uk/batch_direct_debits create

Transfer Approvals - Trust Account

Response body

{
  "transfer_approval_id": "39",
  "transfer_type": "sepa_credit_transfer",
  "message": "Your transfer has been received and is waiting for approval."
}

GET https://api.fidorbank.uk/transfer_approvals

{
  "data": [
    {
      "id": "38",
      "transfer_id": "666",
      "transfer_type": "internal_transfer",
      "state": "approved",
      "created_at": "2015-06-10T08:10:33Z",
      "updated_at": "2015-06-10T08:10:33Z"
    },
    {
      "id": "39",
      "transfer_id": "",
      "transfer_type": "sepa_credit_transfer",
      "state": "rejected",
      "created_at": "2015-06-10T10:25:32Z",
      "updated_at": "2015-06-10T10:29:42Z"
    },
    {
      "id": "40",
      "transfer_id": "",
      "transfer_type": "sepa_credit_transfer",
      "state": "pending",
      "created_at": "2015-06-10T10:25:32Z",
      "updated_at": "2015-06-10T10:29:42Z"
    }
  ],
  "collection": {
    "current_page": 1,
    "per_page": 10,
    "total_entries": 2,
    "total_pages": 1
  }
}
Parameter Description Format
id Unique identifier of the transfer approval String
transfer_id Unique identifier of the created transfer String
transfer_type Type of the transfer you tried to execute String
state State of the transfer approval String, e.g. “pending”, “approved”, “rejected”
created_at Creation date-time, never changes. ISO 8601 Date-Time e.g. “2014-10-10T17:41:58+02:00” Datetime
updated_at Last update date-time. ISO 8601 Date-Time e.g. “2015-02-04T04:08:54+01:00” Datetime

In case you’re using Fidor’s trust account e.g. for your crowdfunding platfom, legally every trust account belongs to the Fidor Bank - it means that you cannot get the money from the account without Fidor’s approval.

When you try to initiate an internal_transfer or a sepa_credit_transfer we will create a so called transfer_approval for you and block the transferred amount. After a POST to internal_transfers or a sepa_credit_transfers you will get the body of the transfer_approval created for you and the http status code 204.

Once this transfer_approval has been approved, we will create and execute the transfer for you. If the transfer_approval was rejected the money will be credited back to the trust account.

You can retrieve information about the approvals by calling the transfer_approvals endpoint. You will see the state of the approval and the transfer_id if your transfer has been approved.

HTTP REQUESTS

GET https://api.fidorbank.uk/transfer_approvals index

GET https://api.fidorbank.uk/transfer_approvals/{id} self

Errors

   /\___/\
   \ -.- /
   `-.^.-'
     /"\

The Fidor API uses following error codes:

Status Codes Meaning
204 We accepted your request but didn’t create any transfers yet
400 Bad Request
401 Unauthorized – Your API key is wrong
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
409 The request was unsuccessful due to a conflict in the state of the resource
410 Gone – The resource requested has been removed from our servers
422 Unprocessable Entity – Your request is malformed
429 Too Many Requests – You exceeded the rate limit
500 Internal Server Error
503 Service Unavailable