This specification has two kinds of notes.
System side: why it takes this shape, given the data and the implementation's constraints.
User's side
User's side: where people tend to get stuck, and how the screen should handle it.
API contract
The five endpoints below are a draft contract, limited to what the design needs to show. Recording inspections, taking over a return and the not-received check come across through the screen design, so they are not listed. Notifications from the payment provider (webhooks) are assumed to exist on the server side.
The front end first sets out what data each screen needs and when. The back end proposes what it can return, and the front end decides how to handle it. Each endpoint records that exchange.
All amounts are integers in cents (€184 is 18400), to avoid rounding errors.
1What the front end asked for
2What the back end proposed
3What was decided
1. Get a return
GET /api/returns/R-1042
1The status and who acts next, the support agent for the return, the deadline (including whether it is on hold), the inspection result and suggested amount for each item, whether approval is needed, and any amount already refunded through the payment provider. Which actions to offer depends on status, role and assignment, and that rule should not live in the screen. When a refund ID never arrived, it should still be possible to check whether a request exists for this return.
2The server can decide which actions are available. Querying the provider on every open would be slow, so the server returns the refund record it keeps updated from provider notifications, with the time of the last update. Refund requests and approval requests linked to the return can be included.
3Available actions come with a reason code for those that are not available. The approval conditions come in the response and are used while amounts are being edited (P1). While the screen is open, this endpoint is fetched regularly to update status, who acts next and available actions (H6).
Request and response formats
{
"returnId": "R-1042",
"version": 7,
"status": "awaiting_decision",
"nextActor": { "role": "support", "userId": "u_mia", "name": "Mia Keller" },
"stalled": false,
"deadline": { "date": "2026-10-28", "state": "active" },
"returnProof": null,
"items": [
{ "itemId": "it_1", "name": "Electric kettle", "paid": 8900, "arrival": "received", "grade": "no_issue", "suggestedRefund": 8900, "refund": 8900 },
{ "itemId": "it_2", "name": "Coffee grinder", "paid": 11900, "arrival": "received", "grade": "signs_of_use", "suggestedRefund": 9500, "refund": 9500 }
],
"providerRefunds": { "total": 0, "syncedAt": "2026-10-26T09:12:00Z" },
"approvalRules": { "amountThreshold": 15000, "uninspected": true, "aboveSuggested": true, "destinationChange": true },
"availableActions": [
{ "action": "request_approval" },
{ "action": "edit_amounts" },
{ "action": "request_refund", "enabled": false, "reason": "APPROVAL_REQUIRED" }
],
"refunds": [],
"approvalRequest": null,
"followUps": []
}The server decides who acts next and whether the return has stalled (H2). The shared rule is not rebuilt in the screen.
deadline.state is withheld while neither the items nor proof of return have arrived (H3). The deadline date itself does not change.
version is sent with every save, request and approval, and the server checks it (H6, P3). While entered amounts are kept, the version they were based on is kept too, and is not replaced by the regular fetch.
refunds and approvalRequest hold the requests for this return and their status. A request whose response never arrived can be found here by the key it was sent with (requestKey) (R2).
followUps are the open items in After refund, each with someone who acts next (H4).
2. Request a refund
POST /api/returns/R-1051/refunds
Idempotency-Key: 4f9b2c1e-...
{ "expectedVersion": 4, "items": [{ "itemId": "it_1", "amount": 7900 }, { "itemId": "it_2", "amount": 2900 }, { "itemId": "it_3", "amount": 2500 }] }1Sending again after no response must never refund twice (R2). The return should show Refund processing once the request is accepted, without being mistaken for complete (R1).
2The payment provider supports a unique key per request, so the key from the screen can be passed straight through. The request returns only the acceptance; the final result is updated later from provider notifications.
3The key is created once, when the refund request starts, and reused when sending again. The response is 202 (accepted) only, and the screen does not show acceptance as completion.
Response formats
202 — Accepted
{ "result": "accepted", "refundId": "rf_301", "status": "pending", "version": 5 }422 — Approval needed (when the amounts meet a condition; P1 checked again)
{ "result": "rejected", "code": "APPROVAL_REQUIRED", "conditions": ["AMOUNT_THRESHOLD"] }422 — More than the amount not yet refunded (R5)
{ "result": "rejected", "code": "AMOUNT_EXCEEDS_REMAINING", "remaining": 10400 }409 — The facts changed (H6)
{ "result": "conflict", "code": "STALE_DATA", "version": 6, "changed": ["items.it_2.grade"] }409 — A refund is already processing (R2)
{ "result": "conflict", "code": "REFUND_IN_PROGRESS", "refundId": "rf_301" }The server records the key and the request before sending it to the provider. Even if no response arrives, getting the return shows whether the request exists and its status.
A request sent again with the same key returns the first result instead of creating a new request. While a refund on the return is processing, no new request with a different key is accepted, so even if the key is lost (for example, on reload), a double refund is prevented by the state itself.
Returns that need approval do not use this endpoint. The approval decision (4) starts the same process on the server, and the server creates the key.
3. Get a refund
GET /api/returns/R-1090/refunds/rf_290
GET /api/returns/R-1090/refunds/rf_290?refresh=true
1Results arrive later, so a change while the screen is open should appear. Failures should reach a queue even when no one has the screen open. This is also used for "Check result".
2The server updates the status from provider notifications. This service has no way to push updates to the screen. When needed, the server can also query the provider directly.
3Status, who acts next and available actions are updated by getting the return (1). This endpoint is for refund details such as the reason for a failure, and for querying the provider with refresh=true (R2, R4). Queues are based on the server-side status, so they do not depend on whether anyone has the screen open.
Request and response formats
{
"refundId": "rf_290",
"status": "failed",
"failure": { "category": "customer", "code": "CARD_INVALID" },
"source": "payment_provider",
"updatedAt": "2026-10-25T03:40:00Z"
}failure.category is the provider's failure code, sorted by the server into customer and temporary (R3). Provider-specific codes are not interpreted in the screen.
If no result arrives within 48 hours, the refund stays pending and the return moves to Needs check (R4). The status of the refund and the status of the return are kept separately.
source is payment_provider for results from the provider. Records of external refunds (5) are manual_record, and the activity shows them differently.
4. Request and decide approval
POST /api/returns/R-1042/approval-requests
{ "expectedVersion": 7, "items": [...], "destination": { "type": "original_payment" } }
POST /api/approval-requests/ap_55/decision
{ "decision": "approve", "expectedSnapshotVersion": 1 }1The approval dialog should show what is being approved: the amount for each item, the total, the conditions that applied, the refund destination and who requested it. What is approved must be what is refunded. If the facts change after the request, it should be withdrawn automatically (P3).
2When approval is requested, the amounts, inspection results and refund destination can be saved as a snapshot. The server can withdraw the request when inspection results or amounts change, and can tell whether the requester and the approver are the same person (P2).
3The dialog shows the snapshot, not the current values of the return. The response says whether approval led to a provider refund or a transfer arranged with Finance (P5).
Response formats
200 — Approved (through the payment provider)
{ "result": "approved", "next": { "type": "provider_refund", "refundId": "rf_302", "status": "pending" } }200 — Approved (external refund)
{ "result": "approved", "next": { "type": "external_transfer", "transferId": "tr_12", "status": "awaiting_finance" } }409 — Already withdrawn (P3)
{ "result": "conflict", "code": "REQUEST_WITHDRAWN", "changed": ["items.it_2.grade"] }403 — Your own request (P2)
{ "result": "forbidden", "code": "SELF_APPROVAL_NOT_ALLOWED" }Sending back uses decision "reject" and requires a reason (P4); without one, 422.
The approval and the refund record (pending) are saved together, and the server sends the refund to the provider afterwards. If sending fails, the record remains and can be sent again with the same key. A return is never approved with no refund request recorded anywhere.
The snapshot includes the bank details for an external refund, but the screen shows only the last four digits of the account number.
5. Record completion of an external refund
POST /api/external-transfers/tr_12/completion
Content-Type: multipart/form-data
executedAt: 2026-10-28
amount: 9500
reference: FIN-2026-0412
evidence: (proof of payment file)
1Results from the payment provider and completions recorded by people should look different on screen. Errors in the record should be prevented.
2The server can store the proof of payment file, along with who recorded it and when. The amount can be checked against the approved snapshot.
3Proof of payment is required. An amount different from the snapshot is not accepted. The record is saved as manual_record, and the activity shows who recorded it and that proof is attached (P6). Any team lead can record it, not only the one who approved, so the completion can be recorded when that person is away.
Response formats
200 — Recorded
{ "result": "recorded", "transferId": "tr_12", "status": "completed", "source": "manual_record" }422 — Amount does not match
{ "result": "rejected", "code": "AMOUNT_MISMATCH", "approved": 9500, "entered": 9000 }A record cannot be undone. An error is handled as After refund work.