closedhumanPR #182Payments

payments/prepaid_credits: report REFUNDED status and burn refunded refs

Layer 7, Payments — the prepaid_credits reference plugin.

Author

Status
Closed without merging
Opened on
Jul 10
Branch
hackathon/aryan-prepaid-refund-status

Description

The pitch.

## Building block

Layer 7, Payments — the `prepaid_credits` reference plugin.

## Problem

`refund()` deleted the receipt from the ledger. Two real defects follow:

1. **Refunds are invisible.** `verify_payment()` on a refunded payment returns `FAILED` — indistinguishable from a payment that never happened. `PaymentStatus.REFUNDED` already exists in `nest_core.types`, and the escrow plugin already reports it as a terminal state; `prepaid_credits` was inconsistent with both.
2. **Refunded refs are replayable.** Deleting the receipt frees the `PaymentRef`, so the same ref can be paid again after a refund — silently bypassing the duplicate-reference protection that `pay()` otherwise enforces.

## Fix

- Keep the receipt in the (shareable) `payments` dict after refund, so the ref stays burned and duplicate protection keeps working across a shared ledger.
- Track refunded refs in a new `refunds: set[PaymentRef]` constructor parameter that mirrors the existing `balances`/`payments` shared-ledger pattern.
- `verify_payment()` now returns `PaymentStatus.REFUNDED` for refunded refs.
- A second `refund()` of the same ref raises `ValueError("Payment already refunded")` instead of the misleading "Payment not found".

Backwards compatible: the new parameter defaults to a fresh set, and all pre-existing tests pass unchanged.

## Tests

Four new tests in `TestPrepaidCredits`, each of which **fails on main and passes with this change** (verified by stashing the plugin change and re-running):

- `test_verify_refunded_payment_reports_refunded`
- `test_refunded_ref_cannot_be_reused`
- `test_double_refund_rejected`
- `test_shared_ledger_refund_visible_to_all_parties`

## CI

`make ci-local` passes end to end: `uv sync`, `ruff check`, `ruff format --check`, `pyright`, `pytest -v` (1154 passed, 1 skipped).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/182/head:pr-182
git checkout pr-182