Authorization

In order to fetch the accounts and transactions of a user customers require the access token that has been obtained in the previous steps. Use this token to make requests to the accounts and transactions endpoints.

Endpoints Overview

List Accounts

The List Accounts endpoint serves as the gateway to retrieve detailed information about a user's financial accounts. This encompasses various account types.

Request Example:

GET {baseUrl}/rest/accounts/

Response Example:

{
  "accounts": [
    {
      "account_id": "A12345.6",
      "account_number": "0013441006",
      "bank_code": "30030880",
      "iban": "DE93300308800013441006",
      "bic": "TUBDDEDD",
      "access_id": "X12345.6",
      "bank_name": "Bank XYZ",
      "icon": {...},
      "currency": "EUR",
      "balance": {
        "balance": 13.37,
        "balance_date": "2018-04-01T00:00:00.000Z",
        "status": {
          "synced_at": "2023-02-28T00:00:00.000Z",
          "succeeded_at": "2023-02-28T00:00:00.000Z",
          "message": "string"
        }
      },
      "type": "Giro account",
      "name": "Giro account",
      "owner": "John Doe",
      "auto_sync": false,
      "save_pin": true,
      "supported_payments": {
        "SEPA transfer": {
          "allowed_recipients": [],
          "can_be_recurring": false,
          "can_be_scheduled": false,
          "max_purpose_length": 140,
          "supported_text_keys": [
            51,
            53
          ]
        },
      "is_jointly_managed": true,
      "status": {
        "synced_at": "2023-02-28T00:00:00.000Z",
        "succeeded_at": "2023-02-28T00:00:00.000Z",
        "message": "string"
      }
    }
  ]
}

List Transactions

The List Transactions endpoint provides access to comprehensive transaction data. This data includes transaction histories for the user's selected accounts, allowing you to delve into real-time financial insights and transaction details.

Request Example:

GET {baseUrl}/rest/transactions

Response Example:

{
  "transactions": [
    {
      "account_id": "A12345.6",
      "transaction_id": "T12345.6",
      "amount": 23.99,
      "currency": "EUR",
      "account_number": "0013441006",
      "bank_code": "30030880",
      "iban": "DE93300308800013441006",
      "bic": "TUBDDEDD",
      "name": "AMAZON EU S.A R.L.",
      "purpose": "EREF+5B5U3FFS9EA2LS0O MREF+xJbwAFja+X58H3w,CTnl.ascP,WtKe CRED+DE24ZZZ00000561652 SVWZ+306-7405387-3384342 Amazon.de",
      "sepa_remittance_info": "306-7405387-3384342 Amazon.de",
      "sepa_purpose_code": "GDDS",
      "booking_text": "Basislastschrift",
      "booking_key": "NMSC",
      "creditor_id": "DE24ZZZ00000561652",
      "mandate_reference": "xJbwAFja+X58H3w,CTnl.ascP,WtKe",
      "end_to_end_reference": "5B5U3FFS9EA2LS0O",
      "type": "Transfer",
      "prima_nota_number": "931",
      "transaction_code": 117,
      "additional_info": {
        "fee": 0.5,
        "gross_amount": 12.5
      },
      "categories": [
        {
          "parent_id": null,
          "id": 123,
          "name": "Online-Shopping"
        }
      ],
      "payment_partner": {
        "id": "6702b891-b8e6-4892-8615-5440e39d3d0e",
        "name": "Some Supermarket GmbH"
      },
      "contract_id": "C12345.6",
      "booked": true,
      "booked_at": "2023-02-28T00:00:00.000Z",
      "settled_at": "2023-02-28T00:00:00.000Z",
      "created_at": "2023-01-30T00:00:00.000Z",
      "modified_at": "2023-01-31T00:00:00.000Z"
    }
  ],
  "status": {
    "synced_at": "2023-02-28T00:00:00.000Z",
    "succeeded_at": "2023-02-28T00:00:00.000Z",
    "message": "string"
  },
}

For detailed technical information on request parameters, response formats, and implementation specifics, please refer to our API Reference linked above.

Error Handling

The finX API employs HTTP status codes to indicate the outcome of each API request. Familiarity with these codes is essential for understanding the response.

200 OK: This status code indicates a successful request, typically returned when retrieving account or transaction data.

400 Bad Request: If the request is malformed, contains missing or invalid parameters, or violates validation rules, the API responds with a 400 status code.

401 Unauthorized: When the provided authorization is insufficient or invalid, the API responds with a 401 status code, indicating the need for proper user authentication.

403 Forbidden: This status code signifies that the user's authorization is valid, but they lack access to the requested resource. Further permissions or consent may be required.