Refunds are not fully implemented: refunded amounts are not tracked as negative earnings for P/L

[v0l]

Problem

VM refunds are only partially implemented. The admin API already exposes:

• GET /api/admin/v1/vms/{id}/refund — calculates the pro-rated refund amount via PricingEngine::calculate_vm_refund_amount_from_date
• POST /api/admin/v1/vms/{id}/refund — queues a WorkJob::ProcessVmRefund job

But the worker-side handler is a stub that just bails:

// lnvps_api/src/worker.rs
WorkJob::ProcessVmRefund { .. } => {
    // TODO: Implement the actual refund processing logic
    bail!("Refund processing is not yet implemented");
}

Even once the money is actually returned to the customer, there is currently no way to represent a refund in accounting/reporting. All payments live in the subscription_payment table (the legacy vm_payment table was dropped in migration 20260716130000_drop_vm_payment.sql):

• SubscriptionPaymentType (lnvps_db/src/model.rs) only has Purchase, Renewal, and Upgrade — no Refund variant.
• subscription_payment.amount (and tax) are BIGINT UNSIGNED / u64, so a refund cannot be stored as a negative amount.
• The admin time-series/company reports (lnvps_api_admin/src/admin/reports.rs) sum paid payment amounts, so refunded money would still show up as revenue, overstating earnings.

Requirements

When a VM is (partially) refunded, we need to track that the money was returned to the customer so that P/L is correct — i.e. the refund must appear as a minus on the earnings:

1. Implement the actual refund processing in the ProcessVmRefund worker job (Lightning invoice payout, and/or manual refund recording for fiat methods).
2. Represent the refund as an accounting record, e.g.:
   • add a SubscriptionPaymentType::Refund variant, and
   • either store a signed amount or treat Refund-type payment rows as negative when aggregating; link the refund to the original payment(s)/subscription/VM.
3. Update reports (time-series report, company earnings) to subtract refunds from net/tax totals for the period in which the refund happened.
4. Delete/deprovision the refunded VM as part of the flow — a refunded VM is deleted, so no expires adjustment is needed; refund_from_date only drives the pro-rata amount calculation.
5. Migration for any schema changes (new enum value, optional link column to the refunded payment).

Acceptance criteria

• Processing a refund records a payment row (or equivalent) that reduces reported earnings by the refunded amount (incl. tax handling).
• Reports for the refund period show the reduced net/tax totals.
• Refund job no longer bails; failures are surfaced via job feedback.

[v0l]

Gap analysis: sending funds out & downstream payment impacts

Outbound funds — current capability vs. gaps

Lightning — mostly plumbed, not wired:

• payments-rs LightningNode::pay_invoice() exists (LND + Bitvora impls) and is already used by ReferralPayoutHandler (lnvps_api/src/referral/mod.rs), so outbound LN payments are proven in production.
• WorkJob::ProcessVmRefund already carries a lightning_invoice field (customer-supplied BOLT11), but nothing pays it.
• Worker::new() receives the node handle but moves it into the referral handler without keeping a copy — the refund job handler has no way to pay anything.
• No validation of the customer invoice amount vs. the approved refund amount, no invoice-expiry handling.
• No reserve-then-pay idempotency. Referral payouts already implement this pattern (reserve unpaid record → pay → mark paid with preimage, delete reservation on failure); refunds need the same or a crash mid-payment can double-refund.

Fiat — nothing exists (upstream gap in payments-rs):

• Revolut: payments-rs only has RefundValidated / RefundStarted webhook event enums; there is no API to issue a refund (Merchant API POST /api/1.0/orders/{id}/refund).
• Stripe: no refund support at all (POST /v1/refunds against the original PaymentIntent).
• Refunds issued manually from the Revolut/Stripe dashboards produce webhooks we receive but never reconcile into any local record.

On-chain — impossible today:

• OnChainProvider trait is receive-only (new_address + subscribe_payments); no send/withdraw capability exists.

Downstream impacts — every consumer of payment data

Consumer	Impact
Time-series report (admin_time_series_report)	Sums admin_get_payments_with_company_info; refunds must appear as negatives in period net/tax totals
P/L report (admin_profit_loss_report)	Revenue side sums paid payments; refunds must reduce revenue in the refund period
OSS VAT report (admin_oss_report)	EU OSS returns must net refunds against VAT owed per country/rate/period. A refund row needs its own frozen negative tax breakdown matching the original payment's country/rate, or VAT is over-declared
Referral commission	Commission accrues on the referred VM's first paid payment (list_referral_usage SQL, is_paid = 1). Decision: no clawback — a refund is not the referrer's fault; they keep the commission for making the referral. The refund flow must therefore ensure the refund payment row does not disturb referral usage/payout accrual (the refund row must not match the first-paid-payment SQL or double-count), and the referral reports intentionally stay unchanged. The kept commission is simply a business cost absorbed in P/L
VM lifecycle	A refunded VM is deleted, not extended/shortened — so no expires adjustment is needed. The refund flow must instead trigger deletion/deprovisioning (and the deletion must not be blocked if the payout leg fails)
vm_history	Has PaymentReceived; needs a Refunded/RefundIssued action type for the audit trail
User payment history	list_vm_subscription_payments* and user API models must render refund rows sensibly (otherwise they appear as never-paid pending invoices)
Tax on refund row	Must be derived pro-rata from the original payment using its frozen rate/tax_rate, never recalculated at live rates
processing_fee	Payment processor fees are generally not returned on refund — decide whether refund rows carry zero fee (fee remains a sunk cost in P/L) or a negative value

Suggested phasing

1. Accounting first (schema + Refund payment type + report aggregation + VM deletion) — makes manual out-of-band refunds recordable immediately.
2. Lightning payout in ProcessVmRefund (reserve-then-pay, amount validation, preimage stored as proof).
3. Fiat refunds (requires payments-rs additions for Stripe/Revolut refund APIs + webhook reconciliation).
4. On-chain refunds are out of scope until OnChainProvider gains a send capability.