SudoSOS Back-end API / transfers

Transfers

A Transfer is an explicit money movement on or off a SudoSOS account. Where a Transaction records products bought at a point of sale, a transfer is the raw "X amount moves from A to B" record with no product line. Every deposit, fine, payout, write-off, and invoice settlement becomes a Transfer.

Open-ended endpoints

Both from and to are nullable, because some movements have no SudoSOS-side counterparty. A Stripe top-up enters money from outside SudoSOS, so from is null and to is the user being credited. A payout sends money out of SudoSOS, so from is the user being debited and to is null. Internal movements (waiving fines, ad-hoc corrections) have both sides set.

Who creates a transfer

Transfers are not usually written by hand. Each domain that moves money creates its own record and keeps a OneToOne back-reference to the transfer it produced:

• StripeDeposit -- after a successful Stripe PaymentIntent.
• PayoutRequest -- when a user-initiated payout is approved.
• SellerPayout -- periodic settlement to a container owner for sales made on their behalf.
• Invoice -- the debit that settles an invoice, plus an optional creditTransfer if the invoice is credit-noted.
• Fine -- a single fine debit.
• UserFineGroup -- as waivedTransfer, the credit that cancels a fine group.
• WriteOff -- the debit that zeroes an irrecoverable balance.
• InactiveAdministrativeCost -- the recurring charge applied to inactive accounts.

If none of those fit, an admin can create a transfer directly with a free-text description.

VAT

Some transfers carry a VatGroup (e.g. invoice settlements, inactive administrative costs). Most do not -- topping up balance is not a VAT-bearing event, and neither is moving money between SudoSOS users.

Balance impact

amountInclVat is credited to to and debited from from. If a side is null, only the other side moves. Balance treats transfers and transactions symmetrically when computing a user's running total.

PDF

Transfer is PdfAble. Some kinds (payouts, invoice settlements) produce a PDF receipt via GET /transfers/{id}/pdf using TransferPdfService.

Enumerations

Enumeration	Description
TransferCategory	-

Classes

Class	Description
Transfer	TypeORM entity for the transfer table. A single money movement on or off SudoSOS; one of from or to may be null when the counterparty lives outside the system (a Stripe deposit, a bank payout). The domain that originated the movement keeps a OneToOne back-reference, which is how the type of a transfer (deposit, fine, payout, ...) is identified at read time.
TransferController	Controller for the transfers module. Exposes CRUD over transfers, aggregate and per-category summary endpoints used by treasurer dashboards, and a PDF receipt. Direct POST is reserved for privileged users; most transfers are created indirectly by the domain that owns the movement (deposits, payouts, fines, invoices, write-offs). See the module page for the full list of back-references.
TransferService	-

Interfaces

Interface	Description
PaginatedTransferResponse	-
TransferAggregateFilterParameters	-
TransferAggregateResponse	-
TransferAggregateResult	-
TransferFilterParameters	-
TransferRequest	-
TransferResponse	-
TransferSummaryResponse	-
TransferSummaryResult	-

Functions

Function	Description
parseGetTransferAggregateFilters	-
parseGetTransferFilters	-
parseGetTransferSummaryFilters	-