Return customer money with accountable refunds

Purpose

Staff return eligible value while keeping its source, approval and outcome inspectable.

How It Works

Staff identify available receipt value, invoice applications or credit to return. Requesting reserves the selected value so it cannot be spent elsewhere. Where approval is enabled, another person must authorize the request. Offline execution records the payment back immediately. Processor execution can complete, fail definitely or remain uncertain. Failed refunds restore the local position and uncertain ones continue holding money. Returning applied value either credits the original charge or reopens its debt according to the chosen treatment.

Relationships

Record receipts collected outside Rhythm supplies or continues the related financial work.
Collect processor payments and resolve uncertainty supplies or continues the related financial work.
Provide and spend customer credit supplies or continues the related financial work.
Unwind billed purchases and their collected value supplies or continues the related financial work.
Coordinate financial commands across applications supplies or continues the related financial work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Staff return eligible value while keeping its source, approval and outcome inspectable.Failed refunds restore the local position and uncertain ones continue holding money. Returning applied value either credits the original charge or reopens its debt according to the chosen treatment.
Surfaces: consoleapijob
Intent sources: services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D7services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D8services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-5services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-5

Controls

31 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-AI-005 TC-VEN-001 TC-VEN-002 TC-VEN-003 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`accounting.refunds.create`	api	tenant
`accounting.refunds.read`	api	tenant
`accounting.refunds.approve`	api	tenant
`accounting.refunds.execute`	api	tenant

Business Rules

13 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Refund requests identify positive refundable value and cannot exceed available unapplied money, remaining application value or credit balance. proved by `ATS-ACC-TRX-011-10`, `ATS-ACC-TRX-012-01`, `TST-ACC-TRX-109`	validation	service, database	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it refuses more than an allocation holds (over_refund) and more than the unapplied money (over_refund)
`02`must prove Proposed	A request reserves its unapplied source money until success, cancellation or failure, preventing concurrent application, credit creation or another refund from using it. proved by `ATS-ACC-TRX-011-10`, `ATS-ACC-TRX-012-02`, `ATS-ACC-TRX-012-12`, `TST-ACC-TRX-107`	invariant	service, database	test services-accounting:modules/transactions/tests/integration/services/refunds/refund-reservation.integration.spec.js#it refuses allocating the reserved money (over_application) but allocates money beyond it
`03`must prove Proposed	Processor money returns through its original merchant account unless the source lacks a processor reference or a processor refund has already been declined. proved by `ATS-ACC-TRX-003-12`, `ATS-ACC-TRX-012-03`, `ATS-ACC-TRX-013-10`, `ATS-ACC-TRX-014-09`, `TST-ACC-TRX-105`	policy	service	test services-accounting:modules/transactions/tests/integration/services/refunds/refund-card-original-method.integration.spec.js#it refuses a check refund of the card’s unapplied money, saying the money goes back to the card
`04`must prove Proposed	Refunding an application removes its paid value; a default credit memo preserves settlement, while an explicit reopen choice restores the debt. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-5 proved by `ATS-ACC-TRX-012-04`, `TST-ACC-TRX-109`, `TST-ACC-TRX-249`	calculation	service	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it keeps the invoice settled for the credited 2000 (a credit memo line) and reopens the 1000: the line owes 1000
`05`must prove Proposed	Where workspace approval is enabled, requests wait and only a different person can approve them. proved by `ATS-ACC-TRX-012-05`, `TST-ACC-TRX-109`, `TST-ACC-TRX-250`	permission	service	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it requests it pending_approval, refusing to execute it (refund_not_requested) or to let the requester approve it (self_approval)
`06`must prove Proposed	Execution requires requested status, cancellation requires an unpaid refund and a reason, and paid or cancelled refunds are final. proved by `ATS-ACC-TRX-012-06`, `TST-ACC-TRX-109`	lifecycle	service, database	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it refuses executing it again (refund_not_requested) and cancelling it (refund_not_cancellable)
`07`must prove Proposed	Offline execution moves money immediately and derives partially refunded or refunded payment status from the accumulated amount. proved by `ATS-ACC-TRX-012-07`, `TST-ACC-TRX-109`, `TST-ACC-TRX-248`	calculation	service, database	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it records it offline: executed, the payment partially_refunded with 1000 refunded (FC-11, FC-14)
`08`must prove Proposed	Processor refunds are recorded before the external call; definite rejection or nonreceipt fails the refund and restores applications and reservations. proved by `ATS-ACC-TRX-007-12`, `ATS-ACC-TRX-012-08`, `ATS-ACC-TRX-012-12`, `ATS-ACC-TRX-020-09`, `TST-ACC-TRX-108`, `TST-ACC-TRX-109`, `TST-ACC-TRX-251`	lifecycle	service	test services-accounting:modules/transactions/tests/integration/services/refunds/refunds.integration.spec.js#it leaves the payment as it was: nothing unapplied, refunded or pending, its facts unchanged
`09`must prove Proposed	Unknown or pending processor outcomes keep the refund processing with money held until confirmed by lookup, event or human resolution, without abandonment. proved by `ATS-ACC-TRX-007-12`, `ATS-ACC-TRX-009-12`, `ATS-ACC-TRX-012-09`, `ATS-ACC-TRX-012-12`, `ATS-ACC-TRX-013-10`, `ATS-ACC-TRX-014-09`, `ATS-ACC-TRX-020-09`, `TST-ACC-TRX-042`, `TST-ACC-TRX-108`, `TST-ACC-TRX-109`, `TST-ACC-TRX-264`	lifecycle	service	test services-accounting:modules/transactions/tests/integration/services/refunds/refund-timeout-before-send.integration.spec.js#it leaves the refund processing a day on, never failed as never received and never abandoned
`10` Proposed	Only check refunds can carry a check number.	validation	service, database	test services-accounting:modules/transactions/tests/integration/services/refunds/refund-check-number.integration.spec.js#it is refused in plain words, naming the method, and stores no refund
`11`must prove Proposed	Refunding card-paid value also returns its proportional processing fee rounded downward and credits the fee invoice. proved by `ATS-ACC-TRX-012-10`, `TST-ACC-TRX-122`	calculation	service	test services-accounting:modules/transactions/tests/integration/services/settlements/card-fees.integration.spec.js#it takes the fee’s share back with the line: 2000 of 4000 refunded is 2065, the fee invoice credited 65
`12`must prove Proposed	Request and cancellation require create authority, approval and execution require their distinct sensitive authorities, and immediate execution requires both create and execute. proved by `ATS-ACC-TRX-012-11`, `TST-ACC-TRX-013`	permission	api	test services-accounting:modules/transactions/tests/e2e/refunds.e2e.spec.js#it is refused approve without .approve, execute without .execute and cancel without .create, as a reader (403)
`13` Proposed	The product should expose the workspace’s refund-approval setting in the console; only the service currently provides it.	policy	console	unknown FND-ACC-TRX-007

Scenarios

Id	Given	When	Then	Provenance
`01`	A check overpayment is available and the member requests part back.	Request a check refund and record its execution.	Offline refund completion reduces available money and derives partially refunded payment standing.	test react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0311.spec.ts#ACT-ACC-0311
`02`	A payment has allocations on two lines.	Refund both, choosing credit treatment for one and reopening for the other.	A memo maintains the first line’s settlement while the second regains its debt.	test react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0312.spec.ts#ACT-ACC-0312
`03`	The requested card refund concerns an allocated invoice line.	Execute a refund that the processor definitely declines.	Failure leaves the source application and money at their original position.	test react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0314.spec.ts#ACT-ACC-0314

Planning

Implementation

Return customer money with accountable refunds ​

Purpose ​

How It Works ​

Relationships ​