Refund line allocation is skipped when the payment driver returns no transaction

[wychoong]

When refunding order lines, RefundOrder only writes refund_lines and increments order_line.refunded_quantity if the driver returns the refund Transaction on PaymentRefund.

// packages/core/src/Actions/Orders/RefundOrder.php
/**
 * Persist the line-level allocation and bump each line's
 * refunded_quantity rollup. Best-effort: a driver that doesn't hand back
 * the refund transaction it created (see {@see PaymentRefund}) means the
 * money still refunds correctly, it just isn't attributable to lines.
 */
protected function recordLineAllocations(PaymentRefund $refund, array $allocations): void
{
    if (! $allocations || ! $refund->transaction) {
        return;
    }

PaymentRefund::$transaction is nullable on purpose:

// packages/core/src/DataObjects/PaymentRefund.php
@param  ?Transaction  $transaction  The refund transaction the driver created, when it creates one. Nullable — not every driver records the money movement as a transaction row (e.g. the offline driver); callers that need to attribute a refund to line-level bookkeeping should treat a null transaction as "recorded, but not attributable".

Spec 0028 still says that on success the action does persist line allocation:

4. In a transaction: dispatch to the driver ($transaction->refund($minor, $note)); on success persist refund_lines rows and bump each order_line.refunded_quantity; dispatch OrderRefunded.

The money refund can succeed, OrderRefunded still fires, but:

• no refund_lines
• refunded_quantity stays 0
• the items table / next refund can over-allocate the same qty
• history of what was refunded is missing

refund_lines.transaction_id is a required FK, so the current code has nowhere to hang the rows without a transaction:

// packages/core/database/migrations/2026_01_01_000072_create_refund_lines_table.php
$table->foreignId('transaction_id')->constrained($this->prefix.'transactions')->cascadeOnDelete();

The rollup column itself is not an FK to the transaction — it's a denormalised count. Those two facts are being tied together.

Why this is an issue

Line refund history should not depend on the driver returning a transaction. If the driver moved the money, Lunar should still record quantities. A driver that refunds without a Transaction is already an incomplete ledger; making line bookkeeping best-effort on top of that hides it.

Directions to discuss

1. Require a transaction from a successful refund. If success === true, transaction must be set. Offline/first-party drivers already create one. Third-party drivers that don't are non-compliant. Line allocation always runs.

2. Record lines even without a transaction. Make refund_lines.transaction_id nullable (or add another parent) and always bump refunded_quantity on success. Quantity history doesn't wait on the money row.

3. Keep best-effort, but fail loudly. e.g. don't treat the refund as fully successful for line-aware callers, or log/error so operators see that quantities weren't stored.

I lean toward (1): a successful driver refund should always create a Transaction, and line allocation should always run. (2) if some drivers must stay transaction-less.

Not about a specific gateway — it's the RefundOrder + PaymentRefund contract.

Refs:

• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/Actions/Orders/RefundOrder.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/DataObjects/PaymentRefund.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/database/migrations/2026_01_01_000072_create_refund_lines_table.php
• https://github.com/lunarphp/lunar/blob/2.x/specs/completed/0028-line-item-refunds.md