Refund an acompte / caution as store credit (avoir)

Refunds a subject the customer paid into — an acompte on a special order, a caution — by minting a REDEEMABLE avoir (store_credit instrument) for the amount, and records the refund. The avoir and the refund record are written in ONE transaction, so a refund can never exist without the spendable instrument it promises. The response carries the instrumentCode to hand to the customer.

This is NOT a return: a refunded acompte has no article, no reason code and no stock impact, so it is deliberately absent from the return statistics — use POST /returns to send goods back.

The CALLER supplies the refund id; it is the idempotency anchor, so replaying a request returns the SAME refund and mints nothing further. Money is integer cents. The amount is REFUSED (422), never trimmed, when it exceeds what is still refundable — read GET /refunds/refundable/{subjectKind}/{subjectId} first to know the bound.

MANAGER ELEVATION. Minting the avoir asserts giftcard:issue, which pos.returns.manage does not imply: a cashier must present a manager’s single-use x-elevation-token (obtained from POST /elevation for the refund.storeCredit operation, whose approver holds pos.giftcard.manage) or the call is refused 403. Every other refusal is evaluated BEFORE the token is consumed, so a rejected request never costs a manager their PIN.

MODALITY. Whether refunds go back as store credit or to the original payment method is a platform setting (refund.modality in PUT /settings). This route serves the store_credit modality; when the merchant has configured original_method it refuses 422 rather than silently handing out an avoir.

Failure conditions: 400 on a malformed body; 403 without sale:refund or without the elevation the mint requires; 404 when the subject is unknown; 422 when the amount exceeds the refundable balance or the configured modality is not store credit.