Fetching Account & Transaction Data
Authorisation
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
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": "A998944684550094849.1",
"access_id": "X998944684550094849.1",
"name": "Etihad Alguwaee",
"owner": "Etihad Alguwaee",
"auto_sync": true,
"account_number": "3200000001",
"bank_code": "10000109010101",
"bank_name": "SAMA Modelbank/ بنك نموذج الهيئة السعودية للرقابة المالية",
"currency": "SAR",
"bic": "SAMASARIXXX",
"type": "Giro account",
"icon": {
"url": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default.png",
"resolutions": {
"48x48": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_48.png",
"60x60": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_60.png",
"72x72": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_72.png",
"84x84": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_84.png",
"96x96": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_96.png",
"120x120": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_120.png",
"144x144": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_144.png",
"192x192": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_192.png",
"256x256": "https://api.ob-finx-s.misconnect.co/assets/images/accounts/default_256.png"
}
},
"save_pin": false,
"supported_payments": {},
"status": {
"synced_at": "2024-08-29T09:36:33.079349+00:00",
"succeeded_at": "2024-08-29T09:36:33.079349+00:00"
},
"balance": {
"balance": 1367.39,
"balance_date": "2022-11-21T00:00:00.000Z"
},
"is_jointly_managed": false,
"regional_data": {
"nickname": "Etihad Alguwaee",
"status": "Active",
"account_type": "KSAOB.Retail",
"account_sub_type": "CurrentAccount",
"identification_type": "KSAOB.BICFI",
"identification": "10000109010101",
"status_update_date_time": "2023-02-01T16:37:04.892Z",
"description": "Account sub-type description",
"opening_date": "2022-04-08T16:37:04.892Z",
"maturity_date": "2023-11-29T16:37:04.892Z",
"balance": {
"credit_debit_indicator": "KSAOB.Credit",
"type": "KSAOB.ClosingAvailable",
"credit_line": [
{
"amount": "500.00",
"included": true,
"type": "KSAOB.Temporary",
"currency": "SAR"
}
]
}
}
},
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.
Response Example
{
"transactions": [
{
"account_id": "A12345.6",
"transaction_id": "T12345.6",
"amount": 23.99,
"currency": "EUR",
"account_number": "0013441006",
"bank_code": "30030880",
"iban": "SA0380000000608010167519",
"bic": "NCBKSAJE101",
"name": "AMAZON EU S.A R.L.",
"purpose": "EREF+5B5U3FFS9EA2LS0O MREF+xJbwAFja+X58H3w,CTnl.ascP,WtKe CRED+SA24ZZZ00000561652 SVWZ+306-7405387-3384342 Amazon.de",
"regional_data": {
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"index": 0,
"transaction_date_time": "2024-08-29T09:25:46.606Z",
"local_time_zone": "2024-08-29T09:25:46.606Z",
"transaction_reference": "string",
"statement_reference": "string",
"transaction_type": "POS",
"sub_transaction_type": "PURCHASE",
"terminal_id": "string",
"flags": [
"string"
],
"payment_modes": "ONLINE",
"credit_debit_indicator": "CREDIT",
"status": "BOOKED",
"transaction_mutability": "IMMUTABLE",
"booking_date_time": "2024-08-29T09:25:46.606Z",
"value_date_time": "2024-08-29T09:25:46.606Z",
"transaction_information": "string",
"amount": {
"amount": 0,
"currency": "string"
},
"charge_amount": {
"amount": 0,
"currency": "string",
"charge_included": true
},
"charge_amount_vat": {
"amount": 0,
"currency": "string"
},
"currency_exchange": {
"source_currency": "string",
"target_currency": "string",
"unit_currency": "string",
"exchange_rate": 0,
"contract_identification": "string",
"quotation_date": "2024-08-29T09:25:46.606Z",
"instructed_amount": {
"amount": 0,
"currency": "string"
}
},
"bank_transaction_code": {
"domain": "string",
"domain_code": "string",
"family": "string",
"family_code": "string",
"sub_family": "string",
"sub_family_code": "string"
},
"proprietary_bank_transaction_code": {
"code": "string",
"issuer": "string"
},
"balance": {
"credit_debit_indicator": "CREDIT",
"type": "CLOSING_AVAILABLE",
"amount": {
"amount": 0,
"currency": "string"
}
},
"merchant_details": {
"merchant_id": 0,
"merchant_name": "string",
"merchant_category_code": "string"
},
"creditor_agent": {
"identification_type": "BICFI",
"identification": "string",
"name": "string",
"postal_address": {
"address_type": "BUSINESS",
"short_address": "string",
"building_number": "string",
"unit_number": "string",
"street_name": "string",
"secondary_number": "string",
"district": "string",
"postal_code": "string",
"city": "string",
"country": "string"
}
},
"creditor_account": [
{
"identification_type": "IBAN",
"identification": "string",
"name": "string"
}
],
"debtor_agent": {
"identification_type": "BICFI",
"identification": "string",
"name": "string",
"postal_address": {
"address_type": "BUSINESS",
"short_address": "string",
"building_number": "string",
"unit_number": "string",
"street_name": "string",
"secondary_number": "string",
"district": "string",
"postal_code": "string",
"city": "string",
"country": "string"
}
},
"debtor_account": {
"identification_type": "IBAN",
"identification": "string",
"name": "string"
},
"card_instrument": {
"card_scheme_name": "AMERICAN_EXPRESS",
"instrument_type": "APPLE_PAY",
"identification": "string",
"name": "string"
},
"bill_details": {
"biller_id": 0,
"bill_number": "string",
"bill_payment_type": "POST_PAID"
},
"supplementary_data": {
"additionalProp": "string"
}
},
"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",
"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": "Qwist GmbH",
"website_url": "https://qwist.com",
"logo_url": "https://qwist.com/wp-content/uploads/2024/04/qwist_logo.svg",
"latitude": 52.508099,
"longitude": 13.329611
},
"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"
},
"statistics": {
"deposit_sum": 27560,
"deposit_max": 5250,
"expense_max": -1200,
"expense_sum": -10821.02
}
}
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.
Updated 5 months ago