FinqTreasury API

## Sections
• [About FinqTreasury API](https://treasury-docs.finqware.com/about-finqtreasury-api.md): FinqTreasury APIs are a way of retrieving or pushing data from/to the existing customer tenant database for https://treasury.finqware.com In order to be able to use these APIs, you need to have your bank accounts connected in the FinqTreasury web app. You will also find your API keys (ClientId and ClientKey) in the Setup menu of the FinqTreasury web app.
• [Transactions](https://treasury-docs.finqware.com/transactions.md): The Transactions section allows you to retrieve and filter transaction records within your bank accounts connected in FinqTreasury. Use these capabilities to import your bank statements into your accounting or reconciliation processes. Versioning and transactions references Transaction status: pending, booked, cancelled. A transaction can go from status pending to status cancelled or booked. We are currently providing only booked transactions Transaction id: a transaction receives a unique id that remains stable over time. If the status changes, only this feature of the transaction will change, its id remaining unchanged. MaxRowVersion - represents the id of the last available record in the database. Every data import from the FinqTreasury API stops at a certain record/row. At the next data call, it will start from maxrowversion of the previous call, to bring only the incremental records that have appeared in the database by refreshing from the bank. RowVersion – an updated transaction will receive a new row version, but will keep the same transaction id Transaction uniqueness: we provide a mechanism for deduplicating transactions. In case the transaction records come already duplicated from the bank, we are not going to automatically remove the duplicates but we’ll make it easy for you to identify them by providing a groupId. Bank statement reference: the bankReferenceId field can be used to refer back the transaction to the bank source, representing the id provided by the bank. In case this reference is different from the one provided by the bank in other channels (online banking or host to host) there’s also a bankStatementId field intented to capture the same id as in those channels and help in deduplicating records already imported through those channels. Transaction category Finqware aggregates and normalizes transactions data, also labeling recurring transaction types in a homogeneous way across all banks. The current transaction categories catalog includes the following labels: Title Description Category Description Deposit creation Any kind of bank deposit creation Deposit closing Any kind of bank deposit maturity Bank fee Any kind of bank commission Card payment Online, POS or ATM payment/ withdrawal Card payment Refund Card payment reversed to card account Bank interest charges Paid interests Bank interest deposits Collected interests Bank fees POS Commission for POS collection POS collection Collection through card payment in POS account Cash collect ATM money collect Credit cover Repayment of credit line Credit grant Disbursment of credit line Internal transfers Transfers between two accounts where creditor name is included in debtor name Refund Payment reversed to customer account Reimbursement Compensation paid to customer account Direct debit collection Incoming payment collected through direct debit Currency exchange Money transfer from one currency to another Split VAT Payment in which the VAT is automatically allocated to a dedicated VAT account Detection and parsing of transaction details by “rules” The descriptive fields that accompany the transactions and which contain important information in the bank reconciliation process come from the bank in bulk text format. In order to manage them more easily in the client system, we have implemented a parsing mechanism according to flexible rules that can be defined by the client. Thus, we can identify an invoice/ proforma number information from a field that may contain more data of this type or incompletely written data or with extra characters and we can transmit it in a separate, differentiated field. In order to fully implement those rules, they need to be defined according to your data structure. Reponse structure for a transaction - example Plain text { "id": "e337c059-18db-4055-bd6f-0302290daf89", "iban": "RO12RNCB0857108717970001", "organisationId": "96460047-36dc-4d57-982a-0d01c0167c91", "rowVersion": 184028228, "bookingDateTime": "2023-07-23T00:00:00", "finqTimestamp": "2023-07-24T00:00:19", "bankReferenceId": "10740320034", "bankStatementId": "2023072378315029", "endToEndId": " ", "creditDebit": "C", "amount": "40", "creditorIBAN": "RO12RNCB0857108717970001", "creditorName": "Cosma Adrian-Cosmin", "debtorIBAN": "RO21RNCB0070108717970001", "debtorName": "Cosma Adrian-Cosmin", "currency": "RON", "status": "booked", "info": "Tranzactie efectuata prin George Banking BCR Referinta 230723S003899089, data valutei 23-07-2023, Decontare -Platitor: Cosma Adrian-Cosmin; ", "rules": [ { "name": "InvoiceNumber", "priority": 1, "values": [ "003899089" ], "matchStrength": 100 } ], "groupId": -799731844 }, { "id": "e81d9e98-c62c-48ac-b075-a6a725a3dbbe", "iban": "RO12RNCB0857108717970001", "organisationId": "96460047-36dc-4d57-982a-0d01c0167c91", "rowVersion": 184344697, "bookingDateTime": "2023-07-24T00:00:00", "finqTimestamp": "2023-07-24T10:31:13", "bankReferenceId": "10741780992", "creditDebit": "D", "amount": "-8.4", "debtorIBAN": "RO12RNCB0857108717970001", "currency": "RON", "status": "booked", "details": "{\"attach\":null,\"category\":\"POS purchase\",\"location\":null,\"merchant\":null,\"tags\":null,\"refs\":null, \"bktxcd\":null}", "info": "Apple Pay, Tranzactie comerciant - Tranz: Nr card 546805XXXXXX6289, token XX6233, device Finqware Iphone (2), Ref 551730683015, Suma platita", "rules": [], "category": "POS purchase", "groupId": 2116095691 }, "totalCount": 0, "offset": 0, "limit": 0, "maxRowVersion": 0, "totalActive": 0, - ignore "totalInactive": 0, - ignore "timestamp": "2022-11-17T15:17:31.006Z" } { "id": "e337c059-18db-4055-bd6f-0302290daf89", "iban": "RO12RNCB0857108717970001", "organisationId": "96460047-36dc-4d57-982a-0d01c0167c91", "rowVersion": 184028228, "bookingDateTime": "2023-07-23T00:00:00", "finqTimestamp": "2023-07-24T00:00:19", "bankReferenceId": "10740320034", "bankStatementId": "2023072378315029", "endToEndId": " ", "creditDebit": "C", "amount": "40", "creditorIBAN": "RO12RNCB0857108717970001", "creditorName": "Cosma Adrian-Cosmin", "debtorIBAN": "RO21RNCB0070108717970001", "debtorName": "Cosma Adrian-Cosmin", "currency": "RON", "status": "booked", "info": "Tranzactie efectuata prin George Banking BCR Referinta 230723S003899089, data valutei 23-07-2023, Decontare -Platitor: Cosma Adrian-Cosmin; ", "rules": [ { "name": "InvoiceNumber", "priority": 1, "values": [ "003899089" ], "matchStrength": 100 } ], "groupId": -799731844 }, { "id": "e81d9e98-c62c-48ac-b075-a6a725a3dbbe", "iban": "RO12RNCB0857108717970001", "organisationId": "96460047-36dc-4d57-982a-0d01c0167c91", "rowVersion": 184344697, "bookingDateTime": "2023-07-24T00:00:00", "finqTimestamp": "2023-07-24T10:31:13", "bankReferenceId": "10741780992", "creditDebit": "D", "amount": "-8.4", "debtorIBAN": "RO12RNCB0857108717970001", "currency": "RON", "status": "booked", "details": "{\"attach\":null,\"category\":\"POS purchase\",\"location\":null,\"merchant\":null,\"tags\":null,\"refs\":null, \"bktxcd\":null}", "info": "Apple Pay, Tranzactie comerciant - Tranz: Nr card 546805XXXXXX6289, token XX6233, device Finqware Iphone (2), Ref 551730683015, Suma platita", "rules": [], "category": "POS purchase", "groupId": 2116095691 }, "totalCount": 0, "offset": 0, "limit": 0, "maxRowVersion": 0, "totalActive": 0, - ignore "totalInactive": 0, - ignore "timestamp": "2022-11-17T15:17:31.006Z" }
  • [Unfiltered](https://treasury-docs.finqware.com/transactions/unfiltered.md): The Unfiltered section enables users to create and retrieve transaction records within the FinqTreasury system. It provides full access to manage transaction data, allowing seamless tracking and processing of financial activities in real time.
    • [GetTransactions](https://treasury-docs.finqware.com/transactions/unfiltered/gettransactions.md): Retrieve a list of transactions filtered by your specified criteria, enabling you to efficiently access and review financial activity within your account. Use this section to paginate through transaction records and obtain detailed information tailored to your reporting needs.
  • [Filtered](https://treasury-docs.finqware.com/transactions/filtered.md): Retrieve a customized list of transactions that match specific criteria to streamline financial analysis and reporting. This section enables you to apply detailed filters for precise transaction data retrieval, helping you gain targeted insights into your account activity.
    • [GetFilteredTxByIban](https://treasury-docs.finqware.com/transactions/filtered/getfilteredtxbyiban.md): Retrieve a customized list of transactions associated with a specific IBAN by applying detailed filter criteria. This section enables users to efficiently search and analyze transaction data tailored to their reporting or reconciliation needs.
    • [GetFilteredTxByDateAndIban](https://treasury-docs.finqware.com/transactions/filtered/getfilteredtxbydateandiban.md): Retrieve a customized list of transactions filtered by date range and IBAN details to streamline reconciliation and reporting. This section enables users to efficiently query transaction records that match specific criteria, helping to gain precise insights into account activity.
    • [GetFilteredTxByIbanAndAccountId_IgnoresIban](https://treasury-docs.finqware.com/transactions/filtered/getfilteredtxbyibanandaccountid_ignoresiban.md): Retrieve a list of transactions filtered by account ID while intentionally excluding the IBAN from the filtering criteria. This allows users to focus on account-specific activity without limiting results based on IBAN values. Use this to efficiently access targeted transaction data for a given account.
    • [GetFilteredTxByOrganisationUnitId](https://treasury-docs.finqware.com/transactions/filtered/getfilteredtxbyorganisationunitid.md): Retrieve a customized list of transactions filtered by a specific organisational unit to streamline financial oversight and reporting. This section enables users to apply detailed criteria for precise transaction queries, helping to efficiently manage and analyze treasury activities within their organisational structure.
• [Balances](https://treasury-docs.finqware.com/balances.md): The Balances section allows you to retrieve detailed information about your account’s current and historical balances. Use it to access real-time or filtered balance data, enabling accurate financial tracking and reconciliation within your bank accounts. The API returns the closing/ last balance per day for each historical date stored in the DB as well as the latest balance withdrawn from the bank API for today. In case the connection to the bank was down for a certain date in the past, the API will return the same value as for the last connected date, with a “fake” flag.
  • [Unfiltered](https://treasury-docs.finqware.com/balances/unfiltered.md): The Unfiltered section allows to retrieve continuous balance data for the connected bank accounts. Response fields: Balance id: a balance receives a unique id that remains stable over time. IBAN Currency Balance amount NativeDataTime = the booking date received from the bank IsFake = a flag indicating that the balance is filled in by Finqware, not obtained from the bank MaxRowVersion - represents the id of the last available record in the database. Every data import from the FinqTreasury API stops at a certain record/row. At the next data call, it will start from maxrowversion of the previous call, to bring only the incremental records that have appeared in the database by refreshing from the bank. FinqTimestamp: the date and time of the moment the balance amount was obtained from the bank
    • [GetBalances](https://treasury-docs.finqware.com/balances/unfiltered/getbalances.md): Retrieve detailed balance information for your authorized clients, enabling you to monitor and manage financial positions effectively. This section allows you to access current balances with customizable pagination to handle large datasets efficiently.
  • [Filtered](https://treasury-docs.finqware.com/balances/filtered.md): The Filtered section enables retrieval of balance information based on specific criteria, allowing for tailored queries that match custom filtering parameters. This functionality helps streamline data access by returning only relevant balance records for specific entities or periods. Filters : Start Date, End Date, IBANs, Account IDs, Organisation Unit IDs Response fields: Balance id: a balance receives a unique id that remains stable over time. IBAN Currency Balance amount NativeDataTime = the booking date received from the bank IsFake = a flag indicating that the balance is filled in by Finqware, not obtained from the bank MaxRowVersion - represents the id of the last available record in the database. Every data import from the FinqTreasury API stops at a certain record/row. At the next data call, it will start from maxrowversion of the previous call, to bring only the incremental records that have appeared in the database by refreshing from the bank. FinqTimestamp: the date and time of the moment the balance amount was obtained from the bank
    • [GetFilteredBalByIbanAndDate](https://treasury-docs.finqware.com/balances/filtered/getfilteredbalbyibananddate.md): Retrieve detailed balance information filtered by specific IBANs and date ranges to help you monitor and reconcile account activity accurately. This section enables you to obtain targeted financial data, empowering precise analysis and reporting within your treasury operations.
    • [GetFilteredBalByOrganisationUnitId](https://treasury-docs.finqware.com/balances/filtered/getfilteredbalbyorganisationunitid.md): Retrieve detailed balance information filtered by organization unit, enabling precise insights into financial allocations across different segments. This section allows users to specify criteria to obtain tailored balance data, supporting granular financial analysis and reporting within the FinqTreasury system.
• [Payments](https://treasury-docs.finqware.com/payments.md): The Payments section enables you to initiate and monitor payments for suppliers, payroll or taxes, directly from your ERP. Use this functionality to create new payments, retrieve details of existing transactions, and get the status of authorised payments. The Payments API will only work as a way of automatically importing payment orders into your FinqTreasury account, from where they will be sent to your banks and signed. Once signed, the Payments API will retrieve the status per payment id.
  • [CreatePayments](https://treasury-docs.finqware.com/payments/createpayments-one.md): Create a single or multiple payment sby submitting the necessary payment details in a raw format. Users will process them within the FinqTreasury platform. The API receives payment descriptions for validation and creation (if valid). One or more payments can be created at the same time. The API will respond with a list which describes if a payment was created (so it received an id), or a payment had validation errors. Payment validation rules may differ between payment types (automatically detected based on Debtor IBAN, Creditor IBAN, Currency, Country of Creditor). Input fields: "paymentRefNumber": "string", //your internal Id for this payment (mandatory) "amount": 0.00, //amount (mandatory) "currencyCode": "str", //currency (RON, EUR, USD,…) (mandatory) "details": "string", //description of payment (mandatory) "dueDate": "2024-10-01", //date on which the payment is planed for execution (mandatory) "creditorName": "string", //name of destination person or company (mandatory) "creditorIban": "string", //destination IBAN (no spaces) (mandatory) "creditorCurrencyCode": "str", //currency (RON, EUR, USD,…)(optional) "debtorName": "string", //name of source person or company (mandatory) "debtorIban": "string", //source IBAN (no spaces) (mandatory) "debtorCurrencyCode": "str", //currency (RON, EUR, USD,…) (optional) "creditorCountry": "string", //two letter country code (optional) "creditorTown": "string", //creditor address – town (optional) "creditorAddress": "string", //creditor address – street (optional) "creditorPostcode": "string", //creditor post code (optional) "creditorContacts": "string", //creditor contacts (optional) "creditorContactDetails": "string" //creditor contact details (optional) "taxIDNumber": "string", //payer VAT number (optional) "creditorTaxIdNumber": "string", //beneficiary VAT number (mandatory for tax payments) "endToEndId": "string", //should be unique, can be the same as paymentRefNumber (optional) Response fields: " paymentRefNumber": "string", //your internal id reflected back "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", //FinqTreasury id if payment created "paymentDataValidationStatus": 0 //no errors; multiple error codes possible "paymentDataValidationBrokenRules": "rowIndex": 0, "brokenRules": "errorCode": 0, "errorMessage": "string", //English description of error "paymentFieldSystemName": "string" //Field name "paymentStatus": 0,//0=NotCreated, 1=Created, 2=InvalidDataError, 3=InternalError "createdDate": "2024-10-01T19:29:19.665Z" //Timestamp from FinqTreasury server
  • [CreatePayments - validations](https://treasury-docs.finqware.com/payments/createpayments-force-errors.md): Simulate payment creation failures to test your error handling and integration workflows. This section allows you to intentionally trigger specific error scenarios, helping ensure your application responds correctly under various failure conditions. PaymentDataValidationStatusEnum { Other = -1, Success = 0, InvalidDebtorInformation = 1, InvalidDebtorIBAN = 2, InvalidDebtorCurrency = 3, DebtorBankNotSupported = 4, InvalidCreditorInformation = 5, InvalidCreditorIBAN = 6, InvalidCreditorCurrency = 7, InvalidPaymentAmount = 8, InvalidPaymentCurrency = 9, InvalidCharactersInPaymentDetails = 10 }
  • [GetPaymentsById - One](https://treasury-docs.finqware.com/payments/getpaymentsbyid-one.md): Retrieve detailed information about a specific payment by providing its unique identifier. Response structure: "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentStatus": 1, "paymentStatusName": "string", "debtorName": "string", "debtorIban": "string", "debtorCurrencyCode": "string", "amount": 0.0, "details": "string", "currencyCode": "string", "creditorName": "string", "creditorIban": "string", "creditorCurrencyCode": "string", "dueDate": "2024-10-01T20:12:18.130Z", "completedOn": "2024-10-01T20:12:18.130Z", "initiatedOn": "2024-10-01T20:12:18.130Z", "createdBy": "string", "currencyFxRate": 0, "tenantCurrencyFxRate": 0, "paymentTemplateName": "string", "creditorCountry": "string", "creditorTown": "string", "creditorAddress": "string", "creditorPostcode": "string", "endToEndId": "string", "rowVersion": 0 Payment statuses New = 1, Submitted = 2 InApproval = 3 Approved = 4 Failed = 5 Completed = 6 Deleted = 8 WaitingApprovalInTreasury = 9, for payments with Approval step required in FinqTreasury WaitingSigning = 10, for payments waiting for second signature in the bank RejectedInTreasury = 11, for payments rejected in FinqTreasury with a reason
  • [GetPaymentsById - Multiple](https://treasury-docs.finqware.com/payments/getpaymentsbyid-multiple.md): Retrieve detailed information for multiple payment records by providing their unique identifiers.