Post

Investment Obligation

Posted
Preview Image
By Martijn Bruitsman , Peter Disselkoen
17 min read
Investment Obligation

Business Requirements Document (BRD)

🧩 Investment Obligation
🔖 1.2
📅 25 March 2025
👤 Martijn Bruitsman, Peter Disselkoen
⚙️ Cor van Dooorn

This Epic automates the management of Investment Obligations, including the detection and handling of Collection Failures. Introducing Configurable Intervals, Retries, and Thresholds, allowing to tailor automation behavior to operational requirements. Combining automation with Full Insights for Users, the system ensures efficiency without compromising control. Users can define Failure Handling Logic, monitor Automated Actions, and intervene when necessary, achieving a balance between reliability, flexibility, and governance.

1️⃣ PURPOSE

The purpose of this Epic is to ensure accurate and efficient handling of Investment Obligations:

  • Configurable Investment Obligation.
  • Automatic Collection of Obligated Investment Amount.
  • Collection Failure Handling.
  • Manage Investment- and Payment Arrears.
  • Investment- and Payment Arrear Overviews.

It provides Users full visibility of Investment- and Payment Balances and functionality to process them, while minimizing manual effort through automation. By enabling Configurable Parameters, this Epic supports different Business Rules per Label and/or Product, ensuring compliance, transparency, and operational efficiency.

2️⃣ SCOPE

Key functionalities and objectives included in the delivery of Investment Obligation.

  • Create and manage Investment Obligations.
  • Full insights and functionality to manage Payment- and Investment Arrears.
  • Automated handling of Default Scenarios.
  • Configurable Parameters for non-standard Scenarios.
  • Investment Obligation cannot be combined with Periodical Buy within same Product.

3️⃣ GLOSSARY

TermDefinition
Investment ObligationLegal or contractual duty to Invest into the Investor Account,
with pre-defined conditions.
Obligated Investment AmountAmount that is Obligated to Invest by the Investment Obligation.
UserLabel Employee authorized to manage the process.
InvestorHolder of the Investor Account; cannot create or modify Investment Obligations.
InvestmentTransferring Cash into the Investor Account, for Investment purposes.
Investment ArrearMissed Investments due to Failed Collection.
Investment Arrear (Ledger)Investor Account TO-INVEST-LEDGER holding total missed Investments.
Payment ArrearCash withdrawn from the Investor Account after it was invested into Assets.
Payment Arrear (Balance)Total negative Cash balance of the Investor Account Cash Ledgers.
ReimbursementRetry of Failed Collection.
Maximum Collection AmountMaximum amount, including Reimbursement, collected in one Collection run.

4️⃣ BUSINESS REQUIREMENTS

GiroPro will track and manage Investment Obligations including:

  • Investment Arrears (before processing Orders).
  • Payment Arrears (after processing Orders).
4️⃣1️⃣ FUNCTIONAL REQUIREMENTS
  • Reversal (🇳🇱 stornering)
    • Collection is Reversed after Collection is processed.
    • Create Pro Rata Sell Order to return Cash Balance to 0.
      Unless overridden by Investment Obligation parameters.
    • Possibly creates Payment Arrear.
  • Refusal (insufficient funds)
    • Collection could not be processed.
    • Creates Investment Arrear, and possibly Payment Arrear.
    • Buy Order is Cancelled (if not Processed yet).
  • Inactive Status
    • Will Suspend Collections and creates Investment Arrear.
    • Missed Collections are not Reimbursed.
    • Maximum Collection Amount is set to 0.
  • Collections only according configured Interval
    • No extra automated or manual Retries of Collections.
  • Approval on creation and changes of Investment Obligations
    • Configurable approval of actions by an User.

Within the User Interface the Users can:

  • View Arrears in the applicable Ledgers.
  • Allocate Manual Deposits.
  • Reduce Payment Arrears.
    • Investor Account Main Cash Ledger is the Payment Arrear.
    • Manual Deposit Allocation reduces negative balance of Investor Account Main Cash Ledger.
  • Create Buy Orders from Manual Deposits linked to Investment Arrear.
    • Reduces Investment Arrear.
  • View all Collections, including the Status.
    • Per Label and per Investor Account.
    • Export Collections, which include Reimbursements, as SEPA Transactions.
    • Individually or in Groups.
    • SEPA Transaction Descriptions can be Manually Updated.
    • SEPA Transactions can be Cancelled and Arrears are updated through journal entries.
  • Enable Approval for Investment Obligations.

All Intervals, Retries, and Thresholds will be configurable by Parameters, examples include:

  • RFC 5545 (RRULE) Collection Interval (e.g. weekly, monthly).
  • Obligated Investment Amount (Amount that is Obligated to Invest).
  • Maximum Collection Amount (Obligated Investment Amount + Reimbursement Amount).
    • Reimbursement Amount is optional.
    • Per Product and per Investor Account.
    • The Investor Account’s Value must be within the defined Product Value Range.
    • Can be less than Obligated Investment Amount, to serve custom Payment Arrangements.
    • Can be set to 0 to suspend Collections.
    • Actual Collection Amount is (TO-INVEST-LEDGER - MAIN-CASH-LEDGER) or Maximum Collection Amount.
      • the lowest of the two amounts is collected
  • Thresholds (Max Failed Collections, min/max Obligated Investment Amount).
  • Collection Description (e.g. text that is visible on Banking Statement).
    • Optional Variables: Investor Acccount Number, Month, Year.
  • Reimbursement Description (e.g. text that is visible on Banking Statement).
    • Optional Variables: Investor Acccount Number, Month, Year, Reimbursement Amount.
  • Journal Entry Description (e.g. text that is visible on Journal Entries in GiroPro UI)
    • *INVESTOR ACCOUNT NUMBERORDER NUMBEROBLIGATIED BUYAsset Name*
    • *INVESTOR ACCOUNT NUMBERINVESTMENT OBLIGATIONAsset Name*
4️⃣2️⃣ PERIODICITY
  • Collections for Investment Obligations occur on a Configurable Interval.
    • RFC 5545 (RRULE) Collection Interval (e.g. weekly, monthly).
  • Reimbursements are executed together with Regular Collections.
    • Configurable via Investor Account’s Maximum Collection Amount.
    • First Payment Arrear Ledger and then Investment Arrear Ledger is Reduced.
4️⃣3️⃣ DATA REQUIREMENTS
  • Label- and Product Configuration with Investment Obligation.
  • Investor Account with Investment Obligation Contraction.
  • Current Investment- and Payment Arrears.
    ⚠️ Must be available through Transaction History and balances ⚠️
4️⃣4️⃣ DATA MIGRATION
  • Migrate all required Label-* and *Product Configuration.
    • Data that is required for GiroPro.
  • Migrate all Existing Investment Obligations per Investor Account.
  • Migrate Historical- and Current Investment- and Payment Arrears.
    ⚠️ Must be available through Transaction History ⚠️
1

Data needs to be available in Source System and supplied with a Data Dump.

5️⃣ BUSINESS RULES

Conditions and/or logic that govern Investment Obligations.

  • Reimbursements are combined with Regualar Collections.
    • The two Amounts together are one Collection.
    • Investor Account Maximum Collection Amount determines how much will be Collected.
    • This ensures full flexibility and handling of all Scenarios.
  • Each Collection must use the Collection- and Reimbursements Description.
    • e.g. Mortgage Investment 11-2025.
    • e.g. Mortgage Investment 11-2025 and Reimbursment € 250.
  • After Maximum Collection Retry the Investment Obligation becomes Inactive.
    • Every failed Collection increases the Retry Count of the Investor Account by 1.
    • Every successful Collection resets the Retry Count of the Investor Account to 0.
    • Every successful Collection sets the Investment Obligation to Active.
    • Maximum Collection Amount can be changed to any Amount.
    • Incoming Collections will Reduce possible Payment Arrear.
    • Automatic Buy Order Creation stops.
    • No more Creation of Payment Arrear.
    • Reimbursement first Reduce Payment Arrear and then Investment Arrear.
    • Buy Order Creation will Reduce Investment Arrear.
  • Manual Deposits will Reduce Payment Arrear first and then Investment Arrear.
    • Manual Deposits are not Automatically Allocated.
    • After Manual Allocation no Automatic Order Creation.
    • Any Amount can be Manually Invested or Refunded.

🥒 Gherkin Use Cases

Expand to view all Scenarios ```gherkin Feature: EPIC - Investment Obligation This Epic automates and governs Investment Obligations, including scheduled collections, failure handling, configurable parameters, and user-visible insights for managing investment- and payment arrears. Background: Given a Label and Product are configured to support Investment Obligations And an Investor Account exists under the Label and Product And the Investor Account has an Investment Obligation contracted with an obligated investment amount @TC-01 Scenario: 01 - Create an Investment Obligation for an Investor Account When a User creates an Investment Obligation for the Investor Account Then the Investor Account is marked as having an active Investment Obligation And the obligated investment amount is stored and visible to the User And the configured collection interval is stored and visible to the User @TC-02 Scenario: 02 - Manage an existing Investment Obligation Given the Investor Account has an active Investment Obligation When a User updates the Investment Obligation parameters Then the updated parameters are saved And the updated parameters are visible to the User @TC-03 Scenario: 03 - Investment Obligation cannot be combined with Periodical Buy within the same Product Given the Product supports Periodical Buy When a User attempts to enable Investment Obligation and Periodical Buy within the same Product for the Investor Account Then the system prevents the combination And the User is informed that Investment Obligation cannot be combined with Periodical Buy within the same Product @TC-04 Scenario: 04 - Run collections only on the configured interval Given the Investment Obligation collection interval is configured as When the system evaluates whether a collection should run at Then a collection is due Examples: | interval | evaluation_time | due_result | | weekly (RRULE) | a scheduled weekly occurrence | yes | | weekly (RRULE) | a non-scheduled day | no | | monthly (RRULE) | a scheduled monthly occurrence | yes | | monthly (RRULE) | a non-scheduled day | no | @TC-05 Scenario: 05 - Calculate the actual collection amount using Maximum Collection Amount and current arrears Given the Investment Arrear Ledger (TO-INVEST-LEDGER) balance is And the Main Cash Ledger balance is And the Maximum Collection Amount is When a scheduled collection run is executed Then the actual collection amount is And the collection reduces possible payment arrear first and then investment arrear according to the balances Examples: | to_invest_ledger | main_cash_ledger | max_collection_amount | expected_collection_amount | | 500 | -200 | 1000 | 700 | | 500 | -200 | 600 | 600 | | 500 | 0 | 1000 | 500 | | 500 | 100 | 1000 | 400 | | 500 | -200 | 0 | 0 | @TC-06 Scenario: 06 - Reimbursements are combined with regular collections in one collection run Given the Investor Account is eligible for reimbursement due to prior missed collections And the Maximum Collection Amount allows reimbursement to be included When a scheduled collection run is executed Then the system combines the regular obligated investment amount and reimbursement into one collection And the collection is shown as a single collection entry to the User And the collection description is shown as 'collection description + reimbursement description' @TC-07 Scenario: 07 - Collection descriptions use configured templates with optional variables Given the collection description template includes optional variables for account number, month, and year When a scheduled collection run is created for the Investor Account for Then the collection entry description includes the configured text populated with the applicable variables Examples: | month | year | | January | 2026 | | December | 2025 | | | 2025 | @TC-08 Scenario: 08 - Reimbursement descriptions use configured templates with optional variables Given the reimbursement description template includes optional variables for account number, month, year, and reimbursement amount When a scheduled collection run includes reimbursement for Then the collection entry description includes the reimbursement text populated with the applicable variables Examples: | month | year | | January | 2026 | | December | 2025 | | December | | @TC-09 Scenario: 09 - Reversal is handled after a collection is processed Given a collection has been processed for the Investor Account When the collection is reversed Then the system records the reversal And a pro rata sell order is created to return the cash balance to 0 unless overridden by Investment Obligation parameters And the Investor Account balances reflect any resulting payment arrear @TC-10 Scenario: 10 - Refusal due to insufficient funds creates investment arrear and cancels the pending obligated buy order Given a scheduled collection is due for the Investor Account And the collection cannot be processed due to insufficient funds And the obligated buy order is not yet locked for processing or processed When the collection attempt is processed Then the system records the collection as refused And the system increases the Investment Arrear Ledger (TO-INVEST-LEDGER) And the system updates the Main Cash Ledger to reflect any resulting payment arrear And any obligated buy order linked to this collection is cancelled @TC-11 Scenario: 11 - Refusal due to insufficient funds creates paymemt arrear and creates refund order Given a scheduled collection is due for the Investor Account And the collection is processed but refunded by the bank And the obligated buy order is locked for processing or processed When the collection refund is processed Then the system records the collection as refused And the system increases the Payment Arrear Ledger (MAIN-CASH-LEDGER) And the system creates a refund order to reduce the Payment Arrear (MAIN-CASH-LEDGER) And the system increases the Investment Arrear Ledger (TO-INVEST-LEDGER) @TC-12 Scenario: 12 - Inactive status suspends collections and prevents reimbursement of missed collections Given the Investment Obligation becomes inactive for the Investor Account When a scheduled collection occurrence is reached Then the system does not execute a collection And the missed obligated investment is recorded as investment arrear And missed collections are not reimbursed And the Maximum Collection Amount is treated as 0 while inactive @TC-13 Scenario: 13 - Retry count increments on failed collections and resets on success Given the Investor Account retry count is When a collection attempt results in Then the Investor Account retry count becomes Examples: | starting_retry_count | collection_result | ending_retry_count | | 0 | failure | 1 | | 1 | failure | 2 | | 2 | success | 0 | @TC-14 Scenario: 14 - Investment Obligation becomes inactive after maximum collection retries are reached Given the maximum failed collections threshold is configured as And the Investor Account retry count is When the next collection attempt fails Then the Investment Obligation status becomes inactive And automatic obligated buy order creation stops And no new payment arrear is created due to automated obligated buy order creation Examples: | max_failed_collections | | 0 | | 1 | | 3 | @TC-15 Scenario: 15 - A successful collection reactivates the Investment Obligation Given the Investment Obligation is inactive for the Investor Account When a collection is successfully processed for the Investor Account Then the Investment Obligation status becomes active And the Investor Account retry count is reset to 0 @TC-16 Scenario: 16 - Users can view arrears in applicable ledgers When a User views the Investor Account applicable ledgers Then the User can see the current Investment Arrear Ledger (TO-INVEST-LEDGER) balance And the User can see the current Payment Arrear Ledger (MAIN-CASH) balance @TC-17 Scenario: 17 - Users can view all collections including status per Label and per Investor Account Given collections exist for multiple Investor Accounts under the Label When a User views collections for the Label Then the User can see collections for each Investor Account And each collection shows its status including processed, refused, or reversed @TC-18 Scenario: 18 - Export collections as SEPA transactions individually or in groups Given collections exist with the status eligible for export When a User exports collections as SEPA transactions Then the exported SEPA transactions include collections and reimbursements as applicable And each exported SEPA transaction is visible to the User Examples: | export_mode | | individually | | in groups | @TC-19 Scenario: 19 - A User can manually update SEPA transaction descriptions Given a SEPA transaction has been created from exported collections When a User updates the SEPA transaction description Then the updated description is saved And the updated description is visible to the User @TC-20 Scenario: 20 - A User can cancel SEPA transactions and arrears are updated through journal entries Given a SEPA transaction has been created from exported collections And the SEPA transaction has not been settled When a User cancels the SEPA transaction Then the system records the cancellation And the Investor Account arrear balances are updated accordingly And the updated balances are visible in the Investor Account balances and transaction history @TC-21 Scenario: 21 - Manual deposits are not automatically allocated Given a manual deposit is received for the Investor Account When the deposit is recorded Then the system does not automatically allocate the deposit to arrears And the deposit remains available for a User to allocate @TC-22 Scenario: 22 - Manual deposit allocation reduces payment arrear first and then investment arrear Given a manual deposit of is available for allocation And the Payment Arrear Ledger (MAIN-CASH) balance is And the Investment Arrear Ledger (TO-INVEST-LEDGER) balance is When a User allocates the manual deposit Then the allocation reduces the payment arrear first And any remaining amount can be used to create a obligated buy order to reduce the investment arrear????? Examples: | deposit_amount | main_cash_ledger | to_invest_ledger | | 300 | -200 | 500 | | 150 | -200 | 500 | | 300 | 0 | 500 | @TC-23 Scenario: 23 - After manual allocation, no automatic order creation occurs for the allocated amount Given a manual deposit has been allocated by a User When the next scheduled collection run is evaluated Then the system does not create automatic obligated buy orders for the manually allocated amount @TC-24 Scenario: 24 - Create obligated buy orders from manual deposits linked to investment arrear???? Given a manual deposit is available And an investment arrear exists for the Investor Account When a User creates a obligated buy order from the manual deposit linked to the investment arrear Then the obligated buy order is created And the investment arrear is reduced by the invested amount when the obligated buy order is processed @TC-25 Scenario: 25 - Users can manually invest or refund any amount Given a manual deposit is available When a User chooses to manually invest an amount Then the selected amount is invested by creating an obligated buy order????? And the investment arrear is updated as invested amount with the selected amount When a User chooses to manually refund a deposit Then the deposit is refunded @TC-26 Scenario: 26 - Investment- and payment arrears are available through transaction history and balances When a User views the Investor Account transaction history and balances Then the User can identify historical and current changes to investment arrears And the User can identify historical and current changes to payment arrears @TC-27 Scenario: 27 - Migrated Investment Obligations and arrears are available and visible after migration Given existing Investment Obligations and historical arrears were migrated for the Investor Account When a User views the Investor Account configuration and transaction history Then the migrated Investment Obligation is visible and usable for ongoing collections And the migrated historical and current investment arrears are visible And the migrated historical and current payment arrears are visible @TC-28 Scenario: 28 - Enforce configurable thresholds for obligated investment amount Given the minimum obligated investment amount is And the maximum obligated investment amount is When a User attempts to set an obligated investment amount to Then the system Examples: | min_amount | max_amount | attempt_amount | result | | 10 | 1000 | 10 | accepts | | 10 | 1000 | 1000 | accepts | | 10 | 1000 | 9 | rejects | | 10 | 1000 | 1001 | rejects | @TC-29 Scenario: 29 - Maximum Collection Amount can be configured per Product and per Investor Account Given the Product defines a default Maximum Collection Amount When a User overrides the Maximum Collection Amount for a specific Investor Account Then the Investor Account uses the overridden Maximum Collection Amount for future collections And the effective Maximum Collection Amount is visible to the User @TC-30 Scenario: 30 - Maximum Collection Amount applies only when Investor Account value is within the Product value range Given the Product defines a value range for applying a Maximum Collection Amount When the Investor Account value is outside the Product value range Then the system does not apply the Product's Maximum Collection Amount rules And the system indicates that the Investor Account is outside the eligible value range for those rules ``` </details>
business-requirements
INVESTOR ACCOUNT INVESTMENT OBLIGATION
This post is licensed under CC BY 4.0 by the author.