fin_api_access

FinApiAccess - JavaScript client for fin_api_access RESTful API for Account Information Services (AIS) and Payment Initiation Services (PIS) The following pages give you some general information on how to use our APIs. The actual API services documentation then follows further below. You can use the menu to jump between API sections. This page has a built-in HTTP(S) client, so you can test the services directly from within this page, by filling in the request parameters and/or body in the respective services, and then hitting the TRY button. Note that you need to be authorized to make a successful API call. To authorize, refer to the 'Authorization' section of the API, or just use the OAUTH button that can be found near the TRY button. You should also check out the <a href="https://finapi.zendesk.com/hc/en-us" target="_blank">Developer Portal for more information. If you need any help with the API, contact [email protected]. General information Error Responses When an API call returns with an error, then in general it has the structure shown in the following example: { "errors": [ { "message": "Interface 'FINTS_SERVER' is not supported for this operation.", "code": "BAD_REQUEST", "type": "TECHNICAL" } ], "date": "2020-11-19 16:54:06.854", "requestId": "selfgen-312042e7-df55-47e4-bffd-956a68ef37b5", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/21", "bank": "DEMO0002 - finAPI Test Redirect Bank" } If an API call requires an additional authentication by the user, HTTP code 510 is returned and the error response contains the additional "multiStepAuthentication" object, see the following example: { "errors": [ { "message": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "678b13f4be9ed7d981a840af8131223a", "status": "CHALLENGE_RESPONSE_REQUIRED", "challengeMessage": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "answerFieldLabel": "TAN", "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-29 09:51:55.931", "requestId": "selfgen-45059c99-1b14-4df7-9bd3-9d5f126df294", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "DEMO0001 - finAPI Test Bank" } An exception to this error format are API authentication errors, where the following structure is returned: { "error": "invalid_token", "error_description": "Invalid access token: cccbce46-xxxx-xxxx-xxxx-xxxxxxxxxx" } Paging API services that may potentially return a lot of data implement paging. They return a limited number of entries within a "page". Further entries must be fetched with subsequent calls. Any API service that implements paging provides the following input parameters: • "page": the number of the page to be retrieved (starting with 1). • "perPage": the number of entries within a page. The default and maximum value is stated in the documentation of the respective services. A paged response contains an additional "paging" object with the following structure: { ... , "paging": { "page": 1, "perPage": 20, "pageCount": 234, "totalCount": 4662 } } Internationalization The finAPI services support internationalization which means you can define the language you prefer for API service responses. The following languages are available: German, English, Czech, Slovak. The preferred language can be defined by providing the official HTTP Accept-Language header. For web form request issued in a web browser, the Accept-Language header is automatically set by the browser based on the browser's or operation system's language settings. For direct API calls, the Accept-Language header must be set explicity. finAPI reacts on the official iso language codes "de", "en", "cs" and "sk" for the named languages. Additional subtags supported by the Accept-Language header may be provided, e.g. "en-US", but are ignored. If no Accept-Language header is given, German is used as the default language. Exceptions: • Bank login hints and login fields are only available in the language of the bank and not being translated. • Direct messages from the bank systems typically returned as BUSINESS errors will not be translated. • BUSINESS errors created by finAPI directly are available in German and English. • TECHNICAL errors messages meant for developers are mostly in English, but also may be translated. Request IDs With any API call, you can pass a request ID via a header with name "X-REQUEST-ID". The request ID can be an arbitrary string with up to 255 characters. Passing a longer string will result in an error. If you don't pass a request ID for a call, finAPI will generate a random ID internally. The request ID is always returned back in the response of a service, as a header with name "X-REQUEST-ID". We highly recommend to always pass a (preferably unique) request ID, and include it into your client application logs whenever you make a request or receive a response (especially in the case of an error response). finAPI is also logging request IDs on its end. Having a request ID can help the finAPI support team to work more efficiently and solve tickets faster. Overriding HTTP methods Some HTTP clients do not support the HTTP methods PATCH or DELETE. If you are using such a client in your application, you can use a POST request instead with a special HTTP header indicating the originally intended HTTP method. The header's name is X-HTTP-Method-Override. Set its value to either PATCH or DELETE. POST Requests having this header set will be treated either as PATCH or DELETE by the finAPI servers. Example: X-HTTP-Method-Override: PATCH POST /api/v1/label/51 {"name": "changed label"} will be interpreted by finAPI as: PATCH /api/v1/label/51 {"name": "changed label"} User metadata With the migration to PSD2 APIs, a new term called "User metadata" (also known as "PSU metadata") has been introduced to the API. This user metadata aims to inform the banking API if there was a real end-user behind an HTTP request or if the request was triggered by a system (e.g. by an automatic batch update). In the latter case, the bank may apply some restrictions such as limiting the number of HTTP requests for a single consent. Also, some operations may be forbidden entirely by the banking API. For example, some banks do not allow issuing a new consent without the end-user being involved. Therefore, the PSU metadata must always be provided for such operations. As finAPI does not have direct interaction with the end-user, it is the client application's responsibility to provide all the necessary information about the end-user. This must be done by sending additional headers with every request triggered on behalf of the end-user. At the moment, the following headers are supported by the API: • "PSU-IP-Address" - the IP address of the user's device. • "PSU-Device-OS" - the user's device and/or operating system identification. • "PSU-User-Agent" - the user's web browser or other client device identification. Web-form customers (or unlicensed customers) must send the PSU headers from their client application to finAPI. It will not take effect if web form is triggered for the workflow. In this case Values for the PSU-Device-OS and PSU-User-Agent headers are identified by the JS platform detection and the PSU-IP-Address is obtained from a public Cloudflare service: https://www.cloudflare.com/cdn-cgi/trace. But it is certainly necessary and obligatory to have the true PSU header data for API calls which don't trigger a web form (like "Update a bank connection"). FAQ Is there a finAPI SDK? Currently we do not offer a native SDK, but there is the option to generate a SDK for almost any target language via Swagger. Use the 'Download SDK' button on this page for SDK generation. How can I enable finAPI's automatic batch update? Currently there is no way to set up the batch update via the API. Please contact [email protected] for this. Why do I need to keep authorizing when calling services on this page? This page is a "one-page-app". Reloading the page resets the OAuth authorization context. There is generally no need to reload the page, so just don't do it and your authorization will persist. This SDK is automatically generated by the Swagger Codegen project:

• API version: 1.117.0
• Package version: 1.117.0
• Build package: io.swagger.codegen.languages.JavascriptClientCodegen

Installation

For Node.js

npm

To publish the library as a npm, please follow the procedure in "Publishing npm packages".

Then install it via:

npm install fin_api_access --save

Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

Finally, switch to the directory you want to use your fin_api_access from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

You should now be able to require('fin_api_access') in javascript files from the directory you ran the last command above from.

git

If the library is hosted at a git repository, e.g. https://github.com/YOUR_USERNAME/fin_api_access then install it via:

    npm install YOUR_USERNAME/fin_api_access --save

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file, that's to say your javascript file where you actually use this library):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Getting Started

Please follow the installation instruction and execute the following JS code:

var FinApiAccess = require('fin_api_access');

var defaultClient = FinApiAccess.ApiClient.instance;

// Configure OAuth2 access token for authorization: finapi_auth
var finapi_auth = defaultClient.authentications['finapi_auth'];
finapi_auth.accessToken = "YOUR ACCESS TOKEN"

var api = new FinApiAccess.AccountsApi()

var id = 789; // {Number} Identifier of the account to delete


var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
};
api.deleteAccount(id, callback);

Documentation for API Endpoints

All URIs are relative to https://localhost

Class | Method | HTTP request | Description ------------ | ------------- | ------------- | ------------- FinApiAccess.AccountsApi | deleteAccount | DELETE /api/v1/accounts/{id} | Delete an account FinApiAccess.AccountsApi | deleteAllAccounts | DELETE /api/v1/accounts | Delete all accounts FinApiAccess.AccountsApi | editAccount | PATCH /api/v1/accounts/{id} | Edit an account FinApiAccess.AccountsApi | getAccount | GET /api/v1/accounts/{id} | Get an account FinApiAccess.AccountsApi | getAndSearchAllAccounts | GET /api/v1/accounts | Get and search all accounts FinApiAccess.AccountsApi | getDailyBalances | GET /api/v1/accounts/dailyBalances | Get daily balances FinApiAccess.AuthorizationApi | getToken | POST /oauth/token | Get tokens FinApiAccess.AuthorizationApi | revokeToken | POST /oauth/revoke | Revoke a token FinApiAccess.BankConnectionsApi | connectInterface | POST /api/v1/bankConnections/connectInterface | Connect a new interface FinApiAccess.BankConnectionsApi | deleteAccessData | DELETE /api/v1/bankConnections/{id}/aisConsent | Delete a consent FinApiAccess.BankConnectionsApi | deleteAllBankConnections | DELETE /api/v1/bankConnections | Delete all bank connections FinApiAccess.BankConnectionsApi | deleteBankConnection | DELETE /api/v1/bankConnections/{id} | Delete a bank connection FinApiAccess.BankConnectionsApi | editBankConnection | PATCH /api/v1/bankConnections/{id} | Edit a bank connection FinApiAccess.BankConnectionsApi | getAllBankConnections | GET /api/v1/bankConnections | Get all bank connections FinApiAccess.BankConnectionsApi | getBankConnection | GET /api/v1/bankConnections/{id} | Get a bank connection FinApiAccess.BankConnectionsApi | importBankConnection | POST /api/v1/bankConnections/import | Import a new bank connection FinApiAccess.BankConnectionsApi | removeInterface | POST /api/v1/bankConnections/removeInterface | Remove an interface FinApiAccess.BankConnectionsApi | updateBankConnection | POST /api/v1/bankConnections/update | Update a bank connection FinApiAccess.BanksApi | getAndSearchAllBanks | GET /api/v1/banks | Get and search all banks FinApiAccess.BanksApi | getBank | GET /api/v1/banks/{id} | Get a bank FinApiAccess.CategoriesApi | createCategory | POST /api/v1/categories | Create a new category FinApiAccess.CategoriesApi | deleteAllCategories | DELETE /api/v1/categories | Delete all categories FinApiAccess.CategoriesApi | deleteCategory | DELETE /api/v1/categories/{id} | Delete a category FinApiAccess.CategoriesApi | editCategory | PATCH /api/v1/categories/{id} | Edit a category FinApiAccess.CategoriesApi | getAndSearchAllCategories | GET /api/v1/categories | Get and search all categories FinApiAccess.CategoriesApi | getCashFlows | GET /api/v1/categories/cashFlows | Get cash flows FinApiAccess.CategoriesApi | getCategory | GET /api/v1/categories/{id} | Get a category FinApiAccess.CategoriesApi | trainCategorization | POST /api/v1/categories/trainCategorization | Train categorization FinApiAccess.ClientConfigurationApi | editClientConfiguration | PATCH /api/v1/clientConfiguration | Edit client configuration FinApiAccess.ClientConfigurationApi | getClientConfiguration | GET /api/v1/clientConfiguration | Get client configuration FinApiAccess.LabelsApi | createLabel | POST /api/v1/labels | Create a new label FinApiAccess.LabelsApi | deleteAllLabels | DELETE /api/v1/labels | Delete all labels FinApiAccess.LabelsApi | deleteLabel | DELETE /api/v1/labels/{id} | Delete a label FinApiAccess.LabelsApi | editLabel | PATCH /api/v1/labels/{id} | Edit a label FinApiAccess.LabelsApi | getAndSearchAllLabels | GET /api/v1/labels | Get and search all labels FinApiAccess.LabelsApi | getLabel | GET /api/v1/labels/{id} | Get a label FinApiAccess.MandatorAdministrationApi | changeClientCredentials | POST /api/v1/mandatorAdmin/changeClientCredentials | Change client credentials FinApiAccess.MandatorAdministrationApi | createIbanRules | POST /api/v1/mandatorAdmin/ibanRules | Create IBAN rules FinApiAccess.MandatorAdministrationApi | createKeywordRules | POST /api/v1/mandatorAdmin/keywordRules | Create keyword rules FinApiAccess.MandatorAdministrationApi | deleteIbanRules | POST /api/v1/mandatorAdmin/ibanRules/delete | Delete IBAN rules FinApiAccess.MandatorAdministrationApi | deleteKeywordRules | POST /api/v1/mandatorAdmin/keywordRules/delete | Delete keyword rules FinApiAccess.MandatorAdministrationApi | deleteUsers | POST /api/v1/mandatorAdmin/deleteUsers | Delete users FinApiAccess.MandatorAdministrationApi | getIbanRuleList | GET /api/v1/mandatorAdmin/ibanRules | Get IBAN rules FinApiAccess.MandatorAdministrationApi | getKeywordRuleList | GET /api/v1/mandatorAdmin/keywordRules | Get keyword rules FinApiAccess.MandatorAdministrationApi | getUserList | GET /api/v1/mandatorAdmin/getUserList | Get user list FinApiAccess.MocksAndTestsApi | checkCategorization | POST /api/v1/tests/checkCategorization | Check categorization FinApiAccess.MocksAndTestsApi | mockBatchUpdate | POST /api/v1/tests/mockBatchUpdate | Mock batch update FinApiAccess.NotificationRulesApi | createNotificationRule | POST /api/v1/notificationRules | Create a new notification rule FinApiAccess.NotificationRulesApi | deleteAllNotificationRules | DELETE /api/v1/notificationRules | Delete all notification rules FinApiAccess.NotificationRulesApi | deleteNotificationRule | DELETE /api/v1/notificationRules/{id} | Delete a notification rule FinApiAccess.NotificationRulesApi | getAndSearchAllNotificationRules | GET /api/v1/notificationRules | Get and search all notification rules FinApiAccess.NotificationRulesApi | getNotificationRule | GET /api/v1/notificationRules/{id} | Get a notification rule FinApiAccess.PaymentsApi | createDirectDebit | POST /api/v1/payments/directDebits | Create direct debit FinApiAccess.PaymentsApi | createMoneyTransfer | POST /api/v1/payments/moneyTransfers | Create money transfer FinApiAccess.PaymentsApi | getPayments | GET /api/v1/payments | Get payments FinApiAccess.PaymentsApi | submitPayment | POST /api/v1/payments/submit | Submit payment FinApiAccess.SecuritiesApi | getAndSearchAllSecurities | GET /api/v1/securities | Get and search all securities FinApiAccess.SecuritiesApi | getSecurity | GET /api/v1/securities/{id} | Get a security FinApiAccess.TPPCertificatesApi | createNewCertificate | POST /api/v1/tppCertificates | Create a new certificate FinApiAccess.TPPCertificatesApi | deleteCertificate | DELETE /api/v1/tppCertificates/{id} | Delete a certificate FinApiAccess.TPPCertificatesApi | getAllCertificates | GET /api/v1/tppCertificates | Get all certificates FinApiAccess.TPPCertificatesApi | getCertificate | GET /api/v1/tppCertificates/{id} | Get a certificate FinApiAccess.TPPCredentialsApi | createTppCredential | POST /api/v1/tppCredentials | Create new TPP credentials FinApiAccess.TPPCredentialsApi | deleteTppCredential | DELETE /api/v1/tppCredentials/{id} | Delete a set of TPP credentials FinApiAccess.TPPCredentialsApi | editTppCredential | PATCH /api/v1/tppCredentials/{id} | Edit a set of TPP credentials FinApiAccess.TPPCredentialsApi | getAllTppCredentials | GET /api/v1/tppCredentials | Get all TPP credentials FinApiAccess.TPPCredentialsApi | getAndSearchTppAuthenticationGroups | GET /api/v1/tppCredentials/tppAuthenticationGroups | Get all TPP Authentication Groups FinApiAccess.TPPCredentialsApi | getTppCredential | GET /api/v1/tppCredentials/{id} | Get a set of TPP credentials FinApiAccess.TransactionsApi | deleteAllTransactions | DELETE /api/v1/transactions | Delete all transactions FinApiAccess.TransactionsApi | deleteTransaction | DELETE /api/v1/transactions/{id} | Delete a transaction FinApiAccess.TransactionsApi | editMultipleTransactions | PATCH /api/v1/transactions | Edit multiple transactions FinApiAccess.TransactionsApi | editTransaction | PATCH /api/v1/transactions/{id} | Edit a transaction FinApiAccess.TransactionsApi | getAndSearchAllTransactions | GET /api/v1/transactions | Get and search all transactions FinApiAccess.TransactionsApi | getTransaction | GET /api/v1/transactions/{id} | Get a transaction FinApiAccess.TransactionsApi | restoreTransaction | POST /api/v1/transactions/{id}/restore | Restore a transaction FinApiAccess.TransactionsApi | splitTransaction | POST /api/v1/transactions/{id}/split | Split a transaction FinApiAccess.TransactionsApi | triggerCategorization | POST /api/v1/transactions/triggerCategorization | Trigger categorization FinApiAccess.UsersApi | createUser | POST /api/v1/users | Create a new user FinApiAccess.UsersApi | deleteAuthorizedUser | DELETE /api/v1/users | Delete the authorized user FinApiAccess.UsersApi | deleteUnverifiedUser | DELETE /api/v1/users/{userId} | Delete an unverified user FinApiAccess.UsersApi | editAuthorizedUser | PATCH /api/v1/users | Edit the authorized user FinApiAccess.UsersApi | executePasswordChange | POST /api/v1/users/executePasswordChange | Execute password change FinApiAccess.UsersApi | getAuthorizedUser | GET /api/v1/users | Get the authorized user FinApiAccess.UsersApi | getVerificationStatus | GET /api/v1/users/verificationStatus | Get a user's verification status FinApiAccess.UsersApi | requestPasswordChange | POST /api/v1/users/requestPasswordChange | Request password change FinApiAccess.UsersApi | verifyUser | POST /api/v1/users/verify/{userId} | Verify a user FinApiAccess.WebFormsApi | getWebForm | GET /api/v1/webForms/{id} | Get a web form

Documentation for Models

• FinApiAccess.AccessToken
• FinApiAccess.Account
• FinApiAccess.AccountInterface
• FinApiAccess.AccountList
• FinApiAccess.AccountParams
• FinApiAccess.AccountReference
• FinApiAccess.BadCredentialsError
• FinApiAccess.Bank
• FinApiAccess.BankConnection
• FinApiAccess.BankConnectionInterface
• FinApiAccess.BankConnectionList
• FinApiAccess.BankConnectionOwner
• FinApiAccess.BankConsent
• FinApiAccess.BankGroup
• FinApiAccess.BankInterface
• FinApiAccess.BankInterfaceLoginField
• FinApiAccess.CashFlow
• FinApiAccess.CashFlowList
• FinApiAccess.CategorizationCheckResult
• FinApiAccess.CategorizationCheckResults
• FinApiAccess.Category
• FinApiAccess.CategoryParams
• FinApiAccess.ChangeClientCredentialsParams
• FinApiAccess.CheckCategorizationData
• FinApiAccess.CheckCategorizationTransactionData
• FinApiAccess.ClientConfiguration
• FinApiAccess.ClientConfigurationParams
• FinApiAccess.ConnectInterfaceParams
• FinApiAccess.CreateDirectDebitParams
• FinApiAccess.CreateMoneyTransferParams
• FinApiAccess.DailyBalance
• FinApiAccess.DailyBalanceList
• FinApiAccess.DeleteConsent
• FinApiAccess.DirectDebitOrderParams
• FinApiAccess.EditBankConnectionParams
• FinApiAccess.EditCategoryParams
• FinApiAccess.EditTppCredentialParams
• FinApiAccess.ErrorDetails
• FinApiAccess.ErrorMessage
• FinApiAccess.ExecutePasswordChangeParams
• FinApiAccess.IbanRule
• FinApiAccess.IbanRuleIdentifiersParams
• FinApiAccess.IbanRuleList
• FinApiAccess.IbanRuleParams
• FinApiAccess.IbanRulesParams
• FinApiAccess.IdentifierList
• FinApiAccess.ImportBankConnectionParams
• FinApiAccess.KeywordRule
• FinApiAccess.KeywordRuleIdentifiersParams
• FinApiAccess.KeywordRuleList
• FinApiAccess.KeywordRuleParams
• FinApiAccess.KeywordRulesParams
• FinApiAccess.Label
• FinApiAccess.LabelParams
• FinApiAccess.LoginCredential
• FinApiAccess.LoginCredentialResource
• FinApiAccess.MockAccountData
• FinApiAccess.MockBankConnectionUpdate
• FinApiAccess.MockBatchUpdateParams
• FinApiAccess.MoneyTransferOrderParams
• FinApiAccess.MonthlyUserStats
• FinApiAccess.MultiStepAuthenticationCallback
• FinApiAccess.MultiStepAuthenticationChallenge
• FinApiAccess.NewTransaction
• FinApiAccess.NotificationRule
• FinApiAccess.NotificationRuleList
• FinApiAccess.NotificationRuleParams
• FinApiAccess.PageableBankList
• FinApiAccess.PageableCategoryList
• FinApiAccess.PageableIbanRuleList
• FinApiAccess.PageableKeywordRuleList
• FinApiAccess.PageableLabelList
• FinApiAccess.PageablePaymentResources
• FinApiAccess.PageableSecurityList
• FinApiAccess.PageableTppAuthenticationGroupResources
• FinApiAccess.PageableTppCertificateList
• FinApiAccess.PageableTppCredentialResources
• FinApiAccess.PageableTransactionList
• FinApiAccess.PageableUserInfoList
• FinApiAccess.Paging
• FinApiAccess.PasswordChangingResource
• FinApiAccess.Payment
• FinApiAccess.RemoveInterfaceParams
• FinApiAccess.RequestPasswordChangeParams
• FinApiAccess.Security
• FinApiAccess.SplitTransactionsParams
• FinApiAccess.SubTransactionParams
• FinApiAccess.SubmitPaymentParams
• FinApiAccess.TppAuthenticationGroup
• FinApiAccess.TppCertificate
• FinApiAccess.TppCertificateParams
• FinApiAccess.TppCredentials
• FinApiAccess.TppCredentialsParams
• FinApiAccess.TrainCategorizationData
• FinApiAccess.TrainCategorizationTransactionData
• FinApiAccess.Transaction
• FinApiAccess.TriggerCategorizationParams
• FinApiAccess.TwoStepProcedure
• FinApiAccess.UpdateBankConnectionParams
• FinApiAccess.UpdateMultipleTransactionsParams
• FinApiAccess.UpdateResult
• FinApiAccess.UpdateTransactionsParams
• FinApiAccess.User
• FinApiAccess.UserCreateParams
• FinApiAccess.UserIdentifiersList
• FinApiAccess.UserIdentifiersParams
• FinApiAccess.UserInfo
• FinApiAccess.UserUpdateParams
• FinApiAccess.VerificationStatusResource
• FinApiAccess.WebForm

Documentation for Authorization

finapi_auth

• Type: OAuth
• Flow: accessCode
• Authorization URL: /oauth/authorize
• Scopes:
  • all: modify any sources