# Open Banking Platform (XS2A.api) In cases where a regular update of the account information is required without the need to ask the user to log in again every time, this product provides access to account data of a bank account, with the aim of obtaining or retrieving an electronic account statement, in order to be able to use this data e.g. in a PFM tool. This enables the possibility to have several bank connections of the same authorized person to be combined under one Tink Germany user. Within the scope of the synchronisation, repeated access to the bank data can be granted as long as valid consent for each bank connection was given by the user. With the introduction of the PSD2, the end customer must re-issue the Consent at least every 90 days by means of a bank login via Tink Germany. ## Important ### Synchronization status {% tabs %} {% tab title="Full" %} If a bank connections `sync_mode` is set to `full`, the bank credentials are stored in XS2A and the connection will be synced automatically once a day. {% hint style="warning" %} A bank connection with `sync_mode` set to `full` can also fall back to `none` in case of any failures. If this happens the bank connection needs to be synced manually, after this is successful the connection can switch to `full` again. {% endhint %} {% endtab %} {% tab title="None" %} The connection will not be synced automatically, there are no credentials or tokens that we save to synchronize the bank connection again without user activity. {% hint style="warning" %} Every time sync is initiated via the API, the user has to provide his bank credentials. {% endhint %} {% endtab %} {% tab title="Shared" %} If `sync_mode` is set to `shared`, XS2A will collect the credentials, encrypt them, cut the cipher in half and make one-half of the credentials available at the end of the session. This way neither XS2A, nor the client has access to the full set of credentials. The sync of a bank connection has then to be done via API, providing the other half of the credential cipher as an argument to the sync call. {% endtab %} {% endtabs %} ## Basic integration {% hint style="info" %} View the full technical documentation of this product [here](https://docs.fintecsystems.com/swagger/#tag/XS2A.api-General-Information). {% endhint %} ### Authentication *(*[*Documentation*](https://docs.fintecsystems.com/swagger/#section/Authentication)*)* All authentication in our API is done via HTTP basic authentication. {% tabs %} {% tab title="HTTP" %} ```http POST /v1/api/users HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_API_KEY_GOES_HERE") Cache-Control: no-cache ``` {% endtab %} {% tab title="cURL" %} ```bash curl --user api: https://api.xs2a.com/v1/payments ``` {% endtab %} {% endtabs %} ### Create a bank user *(*[*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.users/paths/~1api~1users/put)*)* The first step is to create a bank user, this bank user will store all bank connections for a user. {% tabs %} {% tab title="HTTP" %} ```http PUT /v1/api/users HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_API_KEY_GOES_HERE") Cache-Control: no-cache { "name": "Max Mustermann", "email": "user@example.com" } ``` {% endtab %} {% tab title="cURL" %} ``` ``` {% endtab %} {% endtabs %} As result, you will get information about the created bank user. {% tabs %} {% tab title="JSON" %} ```javascript { "id": "bus_NIB48H6IiB57ySH1", "name": "Max Mustermann", "email": "user@example.com", "testmode": true, "created_at": "2017-12-14 16:52:44", "object": "bank_user" } ``` {% endtab %} {% endtabs %} We need to use the `id` value in the next request. ### Create an access token for a bank user *(*[*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.users/paths/~1api~1users~1{user-id}~1accesstokens/put)*)* All communication to the API for a specific bank user needs to be done with the access token. The access token replaces the API key at the authentication. {% tabs %} {% tab title="HTML" %} ```http PUT /v1/api/users/{user-id}/accesstokens HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_API_KEY_GOES_HERE") Cache-Control: no-cache { "valid_until": "2022-03-22 12:14:58" } ``` {% endtab %} {% tab title="cURL" %} ``` ``` {% endtab %} {% endtabs %} The result will include additional information on the generated token and the token itself. {% tabs %} {% tab title="JSON" %} ```javascript { "id": "uat_MEYAT0R7Gm2vkZtU", "token": "4K9JaNOhnCknZJyAXHKkrS6g0Ik7V0CX", "valid_until": "2018-03-22 12:14:58", "created_at": "2018-03-16 11:14:58", "object": "bank_user" } ``` {% endtab %} {% endtabs %} The `token` value is now used as the password for all following requests at the authentication. ### Create a bank connection ([*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.connections/paths/~1api~1connections/put)) To retrieve information about bank accounts we first need to create a bank connection to a bank. This bank connection will then work as a parent for all fetched bank accounts. {% tabs %} {% tab title="HTTP" %} ```http PUT /v1/api/users/{user-id}/accesstokens HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_ACCESS_TOKEN_GOES_HERE") Cache-Control: no-cache { "sync_mode": "full", "bic": "TESTDE88XXX", "country_id": "DE", "days": 60, "limit_days": 60, "account_selection": "all", "language": "de", "fints_product_id": "" } ``` {% endtab %} {% tab title="cURL" %} ``` ``` {% endtab %} {% endtabs %} As result, you will get a `wizard_session_key` and a `transaction` value. {% tabs %} {% tab title="JSON" %} ```javascript { "wizard_session_key": "m5A65Cy2lwI1rOXxuvwU4MM47b4tDaV0ME9By6It", "transaction": "10001-xv-LEz8-oct7" } ``` {% endtab %} {% endtabs %} You need to use these values in the next steps so you should store them in your system related to the user. ### Show the created session to the customer This step depends on the integration variant you want to use. In all variants, the `wizard_session_key` and the `transaction` value is used later. {% content-ref url="../integration-variants/javascript-widget" %} [javascript-widget](https://guide.xs2a.com/xs2a/integration-cs/integration-variants/javascript-widget) {% endcontent-ref %} {% content-ref url="../integration-variants/wizard-api" %} [wizard-api](https://guide.xs2a.com/xs2a/integration-cs/integration-variants/wizard-api) {% endcontent-ref %} {% content-ref url="../integration-variants/easyonboarding" %} [easyonboarding](https://guide.xs2a.com/xs2a/integration-cs/integration-variants/easyonboarding) {% endcontent-ref %} ### Retrieve the list of bank accounts for a bank user ([*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.accounts/paths/~1api~1accounts/get)) A bank connection can contain multiple bank accounts. Each bank account is unique. Bank accounts will be created via the creation of a bank connection or during synchronization of a bank connection. {% tabs %} {% tab title="HTTP" %} ```http GET /v1/api/accounts HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_ACCESS_TOKEN_GOES_HERE") Cache-Control: no-cache ``` {% endtab %} {% endtabs %} The response will contain a paginated list of all bank accounts that belong to the bank user. {% tabs %} {% tab title="JSON" %} ```javascript { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1, "next_page_url": "https://api.xs2a.com/v1/accounts?page=2", "prev_page_url": "https://api.xs2a.com/v1/accounts?page=1", "from": 1, "to": 1, "data": [ { "id": "bac_c8KYwjexO2iO5AE9", "bank_connection_id": "bcn_xxxxxxxxxxxxxxxx", "holder": "MUSTERMANN, HARTMUT", "iban": "DE62888888880012345678", "description": "Girokonto", "bic": "TESTDE88XXX", "account_number": "1234567890", "bank_code": "88888888", "bank_name": "Testbank", "country_id": "DE", "type": "Giro", "joint_account": false, "transaction_possible": true, "created_at": "2018-03-16 11:14:58", "object": "bank_account" } ] } ``` {% endtab %} {% endtabs %} ### Retrieve the turnovers for a specific bank account ([*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.accounts/paths/~1api~1accounts~1{bank-account-id}~1turnovers/get)) Read the full technical documentation for more information about how to filter the turnovers. {% tabs %} {% tab title="HTTP" %} ```http GET /v1/api/accounts/{bank-account-id}/turnovers HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_ACCESS_TOKEN_GOES_HERE") Cache-Control: no-cache ``` {% endtab %} {% endtabs %} The response will contain all matching turnovers for the bank account. {% tabs %} {% tab title="JSON" %} ```javascript { "id": "bac_c8KYwjexO2iO5AE9", "turnovers": [ { "booking_date": "2017-10-08T00:00:00Z", "amount": -962, "currency_id": "EUR", "purpose": [ "SEPA-DAUERAUFTRAG EMPFAENGER HAUSVERWALTUNG" ], "counter_iban": "DE18701693100100029394", "counter_bic": "GENODEF1ALX", "counter_holder": "MUSTERMANN, HARTMUT", "prebooked": false, "canceled": true, "tags": [ "expenditure" ], "category_id": "K.1.2", "creditor_id": "LU96ZZZ0000000000000000058", "new": true } ], "days": 59, "date": "2017-12-06T00:00:00Z", "created_at": "2018-03-16 11:14:58", "object": "bank_account_turnovers" } ``` {% endtab %} {% endtabs %} ### Retrieve the balance for a specific bank account ([*Documentation*](https://docs.fintecsystems.com/swagger/#tag/XS2A.api.accounts/paths/~1api~1accounts~1{bank-account-id}~1balance/get)) {% tabs %} {% tab title="HTTP" %} ```http GET /v1/api/accounts/{bank-account-id}/balance HTTP/1.1 Host: api.xs2a.com Content-Type: application/json Authorization: Basic base64("api:YOUR_ACCESS_TOKEN_GOES_HERE") Cache-Control: no-cache ``` {% endtab %} {% endtabs %} The response will contain the balance information for the bank account. {% tabs %} {% tab title="JSON" %} ```javascript { "id": "bac_c8KYwjexO2iO5AE9", "available": 3123, "limit": 1000, "balance": 2123, "currency_id": "EUR", "date": "2017-12-06T00:00:00Z", "created_at": "2018-03-16 11:14:58", "object": "bank_account" } ``` {% endtab %} {% endtabs %}