The general investment lifecycle

An investment is a customer handing you money for a fixed term in exchange for a promised return. Three things decide what they are owed at the end of it: the ROI recorded when they bought, the outcome you set on the plan or the row, and the arithmetic below. None of the three is visible on the screens where you configure them, which is why this page exists.

This is the general investment product that ships with core — plans, durations and history under Finance → Investment Management. The AI Investments and Forex addons are separate products with their own plans, their own rows and their own settlement crons. Their payout arithmetic happens to match this one; nothing else about them does.

The three admin screens:

Screen	Path	What you decide there
Investment Plans	/admin/finance/investment/plan	Currency, wallet type, min/max, profit percentage, default outcome
Investment Durations	/admin/finance/investment/duration	A number and a timeframe — HOUR, DAY, WEEK or MONTH
Investment History	/admin/finance/investment/history	Nothing — it is a read-only register of individual investments. You can open a record or delete it; there is no edit action on the row

Buying

The body is { type, planId, durationId, amount }, where type is "general" or "forex". A "forex" purchase through this same endpoint creates a forexInvestment row that the Forex addon's own cron settles — everything below about settlement applies to "general" only. Any other type is a 400.

Two gates run before anything else:

• The investment setting — Admin → System → Platform Settings → Features → Investment. Off, and the route answers 403 Investment feature is currently disabled. This is a server-side refusal, not just a hidden menu.
• The KYC feature gate. Per-feature enforcement needs both switches on, under Features → Verification: KYC Verification (kycStatus), the platform-wide master switch, and Enforce KYC Feature Access (kycFeatureEnforcement), which is off by default. With both on, the customer's approved verification level must list invest_general — or invest_forex for a forex purchase. An unverified customer is refused with "KYC verification is required to invest."; a verified one whose level omits the feature gets "Your verification level does not include this feature (invest)." If either switch is off the gate returns immediately, nobody is checked, and no level needs to list the feature at all.

Then the ordinary validation: the plan and duration must exist, the amount must be a finite number above zero and within the plan's minAmount and maxAmount where those are set, and the customer must already hold a wallet of the plan's walletType in the plan's currency with enough balance. A customer with no such wallet gets 404 Wallet not found — the route does not create one.

One active investment per plan

There is no such rule across plans. A customer can hold one active investment in every plan you publish.

What the purchase writes

The investment row and the wallet debit are written in one database transaction, so a failed debit leaves no orphan investment behind.

Field	Value at purchase
status	ACTIVE
amount	What the customer paid
profit	The promised ROI as an absolute amount — plan.profitPercentage / 100 × amount
endDate	Computed once, at purchase, and stored (see below)
result	Null. It is decided at settlement

The debit goes through the wallet service under idempotency key investment_<investment id>, and the resulting transaction row carries referenceId = the bare investment id, type INVESTMENT (or FOREX_INVESTMENT), and a metadata blob naming the plan, duration and ROI. Keying on the freshly created investment id — rather than on user, plan and amount — is what lets the same customer buy the same plan again for the same figure after a cancellation without the second debit being silently swallowed as a duplicate.

A confirmation email is sent, and affiliate rewards are processed for the customer's referrer. A failure in either is logged and does not undo the purchase.

The maturity date

endDate is calculated once, at purchase, and stored on the row. The cron reads the stored value. It never recomputes it.

The calculation adds the duration to the moment of purchase:

Timeframe	Added
HOUR	that many hours
DAY	that many days
WEEK	that many × 7 days
MONTH	that many calendar months

A MONTH is added with JavaScript's setMonth, which overflows rather than clamping to the end of the month. A 1-month term bought on 31 January does not mature on 28 February: the 31st of February rolls forward, so it matures on 3 March (2 March in a leap year). Whatever that arithmetic produces is the date the customer was shown, and because it is persisted it is also the date that settles.

Only legacy rows with no endDate fall back to recomputing from createdAt, and that fallback treats a month as 30 days rather than a calendar month. Rows created by the current purchase route always have an endDate, so the two only differ on data that predates the column.

Settlement

The processGeneralInvestments job runs every hour from the cron process. You can see its state and trigger it by hand on System → System Monitoring → Scheduled Tasks.

Each run loads every investment with status: ACTIVE, oldest first, and skips any whose stored endDate has not passed. It also skips — with an error in the log, but without failing the run — rows whose plan, duration or user has been deleted underneath them.

Which ROI is paid

Four sources, in strict order. The first one that has a value wins:

The practical consequence: editing a plan's profit percentage does not re-price investments already sold. They carry their promised figure in profit and settle on that.

Which outcome is applied

investment.result if it has been set on the row, otherwise plan.defaultResult. There is no market, no price feed and no model behind this — the outcome is an operator decision. In the admin panel that decision is only available per plan, as defaultResult: the History screen cannot edit a row, so a per-row override has to go through PUT /api/admin/finance/investment/history/{id}.

The payout

Result	Credited to the customer's wallet
WIN	principal + ROI
LOSS	principal − ROI, floored at zero
DRAW	principal, unchanged

What the credit looks like in the ledger

The payout is credited under idempotency key investment_roi_<investment id>_<result> — the result is part of the key so that if an outcome is ever changed between runs the two differing payouts cannot collapse into one deduplicated credit.

The resulting transaction row has type INVESTMENT_ROI and referenceId <investment id>_roi.

Alongside the customer's credit, recordInvestmentOutcome books the platform's own leg against adminProfit under type INVESTMENT:

• a WIN is recorded as money the platform paid out (a negative entry, with the treasury debited best-effort up to its available balance — a house with no reserves never blocks a customer's winnings);
• a LOSS records the forfeited slice as platform revenue;
• a DRAW books nothing, because nothing changed hands.

Without that leg, Finance → Revenue Analytics reported fees collected while the ROI funded against them was invisible, so a positive number could be a losing month. It never throws; a failure to book the platform's side does not block the customer's payout.

Finally the row is updated to status: COMPLETED with the result, the roiPercentage and the absolute profit written back, and the customer gets an email plus an in-app notification linking to /investment/<id>.

When settlement fails

So a green run on Scheduled Tasks is not evidence that every customer was paid — only a failure of the whole job, such as the query that loads the active investments, shows up as failed. The evidence for a single stranded settlement is the run's own log lines (Error processing investment id …) and the backend cron log. Find the investment id there, fix the underlying cause — almost always a missing wallet in the plan's currency and wallet type — and the next hourly run settles it.

Cancelling

Cancellation is customer-initiated, from the investment's own page. It:

• refuses anything that is not ACTIVE with 400 Only active investments can be cancelled;
• credits the full principal back to the wallet it came from, under idempotency key investment_refund_<id>, as a REFUND transaction. No ROI is paid and no fee is taken;
• leaves the original debit row in place and merges cancelled, cancelledAt and refundTransactionId into its metadata, so the audit trail survives;
• soft-deletes the investment row (the table is paranoid, so it is recoverable);
• frees the plan for a repeat purchase.

The type query parameter is required. An unrecognised value is now a 400 Invalid investment type — it used to fall through to a 500, which read as a transient fault and invited a retry.

Status reference

Status	Meaning
ACTIVE	Running, or past its maturity date and waiting for the next cron run
COMPLETED	Settled — result and profit are final
CANCELLED	Reserved on the model; the customer cancel path soft-deletes instead
REJECTED	Reserved on the model

Result	Meaning
WIN	Principal plus ROI was paid
LOSS	Principal minus ROI was paid, floored at zero
DRAW	Principal only was returned

Related

• Settings reference — the investment switch and the KYC feature-enforcement switch.
• The admin panel — where Investment Management sits, and how Scheduled Tasks reports a failed run.