Account Statements API Catalogue

Overview:

The Statements feature of the Fileactive API allows businesses to generate detailed transaction statements, providing a comprehensive view of financial activities. This capability supports various reporting needs, including reconciliation, auditing, and financial analysis, by offering accurate and timely access to transaction data. The API ensures secure access through OAuth 2.0 and JWT encryption, making it a reliable solution for managing financial records.

Key Features:

  • Detailed Transaction Data: Retrieve statements with detailed information on individual transactions, including amounts, dates, fees, and other relevant data.

  • Customizable Reports: Generate statements based on specific criteria such as date ranges, transaction types, or account details, allowing for tailored financial reporting.

  • On-Demand and Scheduled Statements: Access statements on demand or set up scheduled generation to keep financial records up to date automatically.

  • Secure Access: Statements are securely generated and accessed using OAuth 2.0 authentication and JWT encryption, safeguarding sensitive financial information.

Technical Details:

  • API Endpoints: Provides endpoints for requesting statements, specifying filters, and retrieving completed reports.

  • JSON-Based Responses: Statements are delivered in JSON format for easy parsing and integration into your systems.

  • Error Handling: Detailed error codes and responses to assist in managing requests and resolving issues efficiently.

Use Cases:

  • Financial Reporting: Generate accurate and detailed financial statements for auditing, tax preparation, or internal reporting.

  • Account Reconciliation: Use statements to match payments with invoices, helping to identify discrepancies and ensure financial accuracy.

  • Business Analytics: Leverage transaction data from statements to perform financial analysis, aiding in decision-making and strategy development.

sequenceDiagram participant Customer participant Fileactive %% Authentication Flow Customer->>Fileactive: POST /v1.0/auth (OAuth Client Assertion) Fileactive-->>Customer: 200 OK (Bearer Token) %% Statement Request Flow Customer->>Fileactive: POST /accounts/v2.0/statement (Request Statement, JSON Payload) Fileactive-->>Customer: 202 Accepted (Statement Request Received) %% Statement Generation and Status Check Note right of Fileactive: Fileactive processes the request
and generates the statement Customer->>Fileactive: GET /accounts/v2.0/statement/{requestKey} (Check Statement Status) alt Statement Ready Fileactive-->>Customer: 200 OK (Statement Ready, CAMT.053 XML) else Statement Not Ready Fileactive-->>Customer: 204 No Content (Statement Not Ready) end %% Statement Download Flow Customer->>Fileactive: GET /accounts/v2.0/statement/{requestKey}/download (Download Statement) Fileactive-->>Customer: 200 OK (Statement File, CAMT.053 XML)

Key Points for Developers:

  • Consistent API Design: The API follows a uniform structure, making it easier to integrate with other Fileactive APIs and reducing the learning curve for developers.

  • Real-Time Access: Utilize the API to fetch the most recent financial data, supporting applications that require up-to-date transaction information.

  • Secure Data Handling: Implement secure data handling practices, including validating OAuth tokens and verifying JWT signatures to ensure the integrity and confidentiality of your data.

  • Scalability: The API is designed to handle high-volume requests, making it suitable for large-scale applications and high-frequency data retrieval needs.

  • Efficient Error Management: Use the detailed error responses provided by the API to implement robust error handling, ensuring smooth operation even when issues arise.

Rate limits and throttling:

By default the following rate limits are applied.

Type TPH (Transactions Per Hour) TPM (Transactions Per Minute) TPS (Transactions Per Second)
Authorisation 10 n/a 2
Statement / BTR 25 n/a n/a

Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

Fixed Window The system uses a window size of n seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

Sliding Window Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

Sliding window example:

Given a limit of 100 transactions per hour.

  • Window 1 (13:00 - 14:00)
    Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

  • Window 2 (14:00 - 15:00)
    By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

    Request rate: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.
    The request rate is still within the 100 tph maximum.

    By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

    Request rate: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.
    This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

    By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

    Request rate: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.
    As this is below the 100 tph limit, further requests will be accepted.