Yoko Shiina

Sample specification: returns and refunds screen for a fictional online retailer

This page presents a screen specification for the returns and refunds work of a fictional online retailer. For a screen where one person replaces a full day’s shift data in a single action, see the daily shift upload sample. For a public guide that visitors use on their own, in the gallery and at home, see the museum guide sample.

Whenever a return is waiting, someone has taken it on, and the next step is clear.

An internal screen for returns and refunds, shared by a returns inspector, a support agent and a team lead, with a payment provider in the loop, designed around that principle.

A single return in detail: refund fields for each item, a total of €184.00, and a message that a team lead’s approval is needed, with a Request approval button.

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.

Purpose of this screen

An internal screen for handling a single return at an online retailer, from the customer's withdrawal to the work left after the refund.

A return passes between a returns inspector, a support agent and a team lead over several days. Refunds are sent to a payment provider, which returns the result later. Refunds that meet certain conditions need approval.

The design is built around one principle: whenever a return is waiting, someone has taken it on, and it is clear what will move it forward. An error or a notification is not where the work ends; the specification also says who picks it up and what they do next.

In the shift sample, one person settled the result in a single action. Here, the person who acts and the person who resolves a problem are often different. That is why the edge cases carry "Taken on by" and "Next step" as their own fields.

User's side
A stalled refund can still look as if someone has it. The person is on leave, the result arrived after they went home, or the facts changed after approval. Returns like these reach their deadline unnoticed. This specification is there to remove that time when a return belongs to no one.

Setting

Halden Home (fictional) is a mid-sized retailer selling small kitchen appliances in the Netherlands, Germany and Belgium. It has one warehouse and handles a few dozen returns a day. Payments go through an external payment provider, and so do refunds. This screen is an internal tool built by its own development team.

The product is in English, so the screens and their text are shown as they appear.

Refund deadline
14 days from the withdrawal (EU right of withdrawal). The refund may be held until the items arrive or proof of return is received, whichever comes first.
Approval needed
A total of €150 or more, a refund before inspection, a refund above the suggested amount, or a changed refund destination. The person who requests and the person who approves are different.
Due soon
Due within 3 days.
Stalled
Due soon, with no action from the assigned person for 2 working days.
No result
48 hours after the refund request. If checking shows it is still processing and the return goes back to Refund processing, the count starts again.
Not arrived after refund
14 days after a refund made on proof of return.

The deadline and the hold follow the actual right of withdrawal rather than an invented rule. Why queues carry deadlines, and why a return moves from waiting to action, then come from regulation rather than habit. The figures 21 days, 3 days, 2 working days, 48 hours, 14 days after refund and €150 are fictional internal rules.

Who is involved

Three roles use this screen. People who do not use it also change the state of a return.

Uses this screen

  • Returns inspector

    Matches arriving parcels to returns and records an inspection result for each item. Does not handle refunds.

  • Support agent

    Talks to the customer, decides the refund amount from the inspection, and requests the refund or an approval. Handles failed refunds.

  • Team lead

    Approves refunds that meet the approval conditions, reassigns returns that have stalled, and takes on work left after a refund. Can also act as a support agent.

Does not use this screen

  • Customer

    Withdraws from the purchase and sends the items back. Does not use this screen.

  • Carrier

    Carries the return parcel. Tracking on the return label records when the parcel is handed over.

  • Payment provider

    Receives refund requests and returns the result later. Not a person.

  • Finance

    Makes the bank transfer when the refund destination changes. Does not use this screen.

"The support agent for the return" is the support agent who first took it on in Awaiting decision. Failed refunds and approvals sent back come back to them, so the customer deals with one person.

Returns inspectors are not assigned to individual returns. A parcel is physically in one place, so two people inspecting the same parcel rarely happens. Approval is not assigned either; any team lead other than the requester can approve.

What staff do is called a "request" (an approval request, a refund request); what the customer does is a "withdrawal". The specification never says "the requester" on its own; it always names the role. When one word means different people in different places, the definition of who takes a return on falls apart.

Screen structure

There are two screens: a list with queues for each role, and the detail of a single return. The queues and columns in the list depend on the role of the person signed in. Returns inspectors do not see amounts or customer contact details.

The detail has items, refund and messages in the left column, and activity in the right. The activity holds both results from the payment provider and records made by people.

The support agent list. The Awaiting decision queue is selected, and the return due soonest has a clock icon.
01 List (support agent)Queues differ by role. Counts are always shown, and returns due within 3 days are marked with bold text and a clock icon.
A return in detail: refund fields for each item, the total, and a message that approval is needed with a Request approval button.
04 Awaiting decision (approval needed)The need for approval appears as soon as an amount changes. Approval is the normal path, so it is shown as "your next step".
Two approval dialogs: a refund through the payment provider, and a refund by bank transfer.
05 Approval dialogWhat is being approved is read before the buttons. The button states the amount and what happens when it is pressed.
A message that the refund is complete, and a next-step message that one item has not arrived.
11 After refundRefunded and Closed are separate. Work left after the refund also has someone who acts next.

The screens are designed in Figma as eleven states. This page shows the four main ones; the full set is in Figma.

User flow

A return moves through six steps, taken by different people at different times. One of them happens outside the screen. For each step, where people get stuck is paired with how the screen handles it.

Withdraw and send the items backOutside the screen

Done by
Customer
Where people get stuck
The customer feels they sent the items and have not been refunded. On the business side, returns that have arrived and those that have not look the same.
How it is handled
Tracking on the return label records when the carrier has the parcel, and that counts as proof of return. When proof arrives, the return moves from waiting to action.

Match the parcel and record the inspection

Done by
Returns inspector
Where people get stuck
It is unclear which parcel belongs to which return, and how to record a parcel that does not match the request.
How it is handled
Scanning the return label opens the return. Amounts and customer contact details are not shown. Each item can be recorded with an inspection result, or as not received or a different item.

Decide the refund amount

Done by
Support agent
Where people get stuck
Which amounts need approval only becomes clear after requesting. If the inspection changes while the return is open, no one notices.
How it is handled
Each item shows a suggested amount, and the need for approval appears as soon as an amount changes. If the return is updated, the entered amounts stay and what changed is shown.

Approve

Done by
Team lead
Where people get stuck
People press approve without seeing what they are approving or what will happen next.
How it is handled
What is being approved is read before the buttons, and the button states the amount and the result. Approving sends the refund or arranges the transfer at the same time.

Process the refund

Done by
Payment provider
Where people get stuck
It is unclear whether the refund is processing, has failed, or needs nothing. A failure arrives when the person who requested it is not there.
How it is handled
While processing, no action is offered and the screen says there is nothing to do. Failures, and returns with no result, go to the queue of whoever takes them on.

Clear the work left after the refund

Done by
Returns inspector · Team lead
Where people get stuck
Once the refund is done, the return looks finished, and a missing item or an error found later belongs to no one.
How it is handled
Refunded and Closed are separate states, and open items move the return to After refund. Each open item has someone who acts next. For a refund made on proof of return, the returns inspector handles arrival and inspection, and the return closes automatically if the items are fine. Damage, items not arrived 14 days after the refund, refunds for further items and errors found after the refund go to a team lead.

There is one refund per return. Allowing separate refunds for individual items within the same return would make asynchronous results harder to handle. When only some items arrive, the arrived items are refunded and the rest stays as After refund work, with someone to take it on.

User's side
Once a return leaves your hands, what happens to it is hard to see. A refund you requested may have failed, or an approval may have been withdrawn; unless it comes back to your queue, you will not know. That is why each state has a defined place to come back to.

Levels of emphasis and how actions are offered

In work tools, plain information, risky states and your own tasks often look the same. Here, levels are defined by what the person needs to do, and each level has its own appearance.

Five message levels

Each level has a thick bar on the left, an icon and a bold title. The status is always stated in text; colour, the bar and the icon are additional cues.

LevelUsed when
CriticalSomething failed, or the deadline may be missed.
Check before continuingSomething changed, or a result is unknown. Not used for routine rules.
Your next stepWork you have taken on. Not a risk, but it does not move until you act.
WaitingProcessing, or someone else's turn. Nothing to do right now.
DoneThe refund is complete.

How actions are offered

Kind of actionHow it looksReason
The main action on the screenBlue fillOne per screen, so the next step is easy to find.
Actions that move moneyBlue fill, with the amount and an iconThe button states the result, as in "Approve and refund €184.00", so what happens is clear before it is pressed.
Other actionsOutline onlyNext to the main action, it is clear which comes first.
Actions not possible in the current stateNot shown; replaced by the action that is possibleWhen approval is needed, "Request approval" replaces the refund; while processing, no action is offered. Since there is a clear action to take instead, this is less confusing than a button that cannot be pressed.

Fields and areas

Fields are the only boxed elements on the screen. Areas that are only read have no box, and are separated by rules and space.

Fields have no background colour, because a grey fill tends to read as disabled. The border is mid-grey (5.10:1 against white); on hover it turns ink, and on focus a blue ring appears.

Warning amber is reserved for changes and unknown results. If "approval needed" also used amber, it would appear on every larger refund and become routine, and a real change in the facts would no longer stand out.

Blue marks what can be acted on: selection, focus and the main action. No status uses blue, so a selected row never looks like a status.

User's side
People work in this screen all day. Strong colours on every status are tiring and bury the returns that really are at risk. Strong colour is kept for what needs action now and for the action you are about to take.

States of a return

The diagram shows how a single return moves between states, not the states of the screen. Each state has someone who acts next.

RequestedCustomerAwaiting parcelCustomer · CarrierNot receivedSupport agentAwaiting inspectionReturns inspectorAwaiting decisionSupport agentAwaiting approvalTeam leadRefund processingPayment providerNeeds checkSupport agentRefund failedSupport agentExternal refundTeam leadRefundedAfter refundTeam lead · Returns inspectorClosedMain flowBack to a personAfter the refund

States that go back to a person return a case to someone's queue after a set time or a result. After Refunded, a return passes through After refund only when work is left. The diagram shows how states connect; what triggers each move is listed below.

There are two ways back from Awaiting approval to Awaiting decision: sent back, and withdrawn because the facts changed. "Sent back" is not a state of its own; it is a queue within Awaiting decision.

Needs check is a state of the return, not of the refund. The refund itself stays pending while the check goes back to a person. Keeping the two apart means a result that arrives later never contradicts the screen.

User's side
State names say what to do in that state. Names that only describe what happened, such as "Error" or "On hold", were avoided.

13 states and who acts next

Main flow

  • RequestedREQUESTED

    The customer has withdrawn and a return label has been issued.

    Acts next
    Customer
    Moves to
    • Awaiting parcel
  • Awaiting parcelAWAITING_PARCEL

    Waiting for the items or for proof of return. While neither has arrived, the refund deadline is shown as on hold.

    Acts next
    Customer · Carrier
    Moves to
    • Awaiting inspection (Arrived)
    • Awaiting decision (Proof of return)
    • Not received (21 days)
  • Awaiting inspectionAWAITING_INSPECTION

    The parcel has arrived at the warehouse and is waiting to be inspected.

    Acts next
    Returns inspector
    Moves to
    • Awaiting decision (Inspected)
  • Awaiting decisionAWAITING_DECISION

    A support agent decides the refund amount for each item, based on the inspection or the proof of return. Requests that were sent back also return here.

    Acts next
    Support agent
    Moves to
    • Refund processing (No approval needed)
    • Awaiting approval (Approval needed)
    • Refunded (Already refunded)
    • Awaiting parcel (Wait for the rest)
  • Awaiting approvalAWAITING_APPROVAL

    A refund that meets the approval conditions is reviewed by a team lead other than the person who requested it.

    Acts next
    Team lead
    Moves to
    • Awaiting decision (Sent back or withdrawn)
    • Refund processing (Approved (provider))
    • External refund (Approved (bank transfer))
  • Refund processingREFUND_PROCESSING

    The refund has been sent to the payment provider and the result is pending. No one needs to act.

    Acts next
    Payment provider
    Moves to
    • Refunded (Succeeded)
    • Refund failed (Failed)
    • Needs check (48 hours)
  • RefundedREFUNDED

    The refund is complete. With no open items the return closes; with open items it moves to After refund.

    Moves to
    • Closed (No open items)
    • After refund (Open items)
  • ClosedCLOSED

    No work is left on this return. If an error in an inspection or a completion record is found after closing, it returns to After refund.

    Moves to
    • After refund (Error found after closing)

Back to a person

  • Not receivedNOT_RECEIVED_CHECK

    Twenty-one days after the withdrawal, neither the items nor proof of return have arrived. A support agent checks the carrier record and contacts the customer.

    Acts next
    Support agent
    Moves to
    • Awaiting inspection (Arrived)
    • Awaiting decision (Proof of return)
  • Needs checkNEEDS_CHECK

    Forty-eight hours after the request, there is still no result from the payment provider. The refund itself stays pending; the return goes back to a person.

    Acts next
    Support agent
    Moves to
    • Refunded (Result found)
    • Refund failed (Result found)
    • Refund processing (Still processing)
  • Refund failedREFUND_FAILED

    The payment provider reported that the refund failed. The deadline keeps running.

    Acts next
    Support agent
    Moves to
    • Refund processing (Try again)
    • Awaiting approval (Change destination)
  • External refundEXTERNAL_REFUND

    Approved with a bank transfer as the refund destination. Finance makes the transfer, and a team lead records the completion with proof of payment.

    Acts next
    Team lead
    Moves to
    • Refunded (Completion recorded)

After the refund

  • After refundAFTER_REFUND

    The refund is complete, but someone still has work on this return. When a refund was made on proof of return, the returns inspector takes on the arrival and inspection; if the items are fine, the return closes automatically. If they are damaged, or have not arrived 14 days after the refund, it moves to a team lead. Refunds for further items and errors found after the refund go to a team lead from the start.

    Acts next
    Team lead · Returns inspector
    Moves to
    • Closed (Outcome recorded)

Edge cases

Grouped as H, R and P: work passed between people, results that arrive later, and approval that depends on conditions. The letters are reference numbers within this specification, separate from B, A and S in the shift sample.

Each item has "Taken on by" and "Next step". A notification or an error message is not treated as the solution; the specification also decides who picks it up and what moves it forward.

What is shown is quoted in English, as it appears in the product. All text is defined on the front end.

Work passed between people

A return passes between three roles over several days. At no point should it be waiting with no one to take it on.

6 items in detail
H1

Another support agent opens a return that someone is working on

Shown
Tom Weber is working on this return (last action 18 Oct). If you take it over, you become the support agent for this return.
Behaviour
The return can be viewed. The only action offered is "Take over", and the handover is recorded in the activity. The check on saving follows the same idea as S4 in the shift sample.
Reason
If two people make decisions at once, contact with the customer and the refund amount are both duplicated. It is not a lock, so that a return does not stall when the person working on it is away.
User's side
"Working on this" may mean the person is on leave. Seeing when they last acted lets the next person decide whether to wait or take over.
Taken on by
The support agent for the return (or the agent who took it over)
Next step
Wait, or take it over.
H2

The support agent for a return does not act, and the deadline approaches

Shown
Due in 2 days. No action for 3 days.
Behaviour
Returns due within 3 days with no action from the assigned agent for 2 working days also appear in the team lead's "Stalled" queue. They stay in the support agent's queue. The server decides which returns qualify.
Reason
Even when the assigned person is away, a return should not reach its deadline without anyone seeing it.
Taken on by
Team lead
Next step
Reassign it to another support agent, or take it on.
H3

The items have not arrived while the return is awaiting the parcel

Shown
On hold: not received / Not received · proof of return / It has been 21 days since the withdrawal, and neither the item nor proof of return has arrived.
Behaviour
While neither the items nor proof of return have arrived, the deadline is shown as on hold. When tracking on the return label shows the carrier has the parcel, the system records it as proof; when the customer sends a receipt, the support agent records it. Either moves the return to Awaiting decision. If neither has arrived 21 days after the withdrawal, the return goes to the "Not received" queue. A return refunded on proof of return moves to After refund once the refund is complete, with "arrival and inspection" as an open item. When the items arrive, the returns inspector inspects them; if they are fine, the return closes automatically. If they are damaged, or have not arrived 14 days after the refund, it moves to a team lead.
Reason
Under the EU right of withdrawal, a business may hold the refund only until it receives the items or proof that they were sent, whichever comes first. When new information arrives, the return has to move from waiting to action. The 21 days are a fictional internal rule: the 14-day return period plus 7 days for delivery. Sending returns that arrived without problems to the team lead would fill their queue with work that is not an exception.
User's side
If returns that may still be held look urgent, the ones that really are urgent get buried. Leaving them alone, though, keeps the customer waiting.
Taken on by
With proof: the support agent for the return. "Not received" is a shared support queue; whoever takes the return becomes its support agent. After the refund, inspecting arrived items is the returns inspector's; damage or non-arrival is the team lead's.
Next step
With proof, request approval for a refund before inspection. Without it, check the carrier record and contact the customer.
H4

What arrived does not match the request (for example, 1 of 2 items)

Shown
Parcel arrived · 1 of 2 items / Your next step: Coffee grinder has not arrived
Behaviour
The returns inspector records "not received" or "different item" for each item. The return moves to Awaiting decision with a mismatch flag. If the support agent chooses to wait for the rest, it goes back to Awaiting parcel. There is one refund per return. If the agent refunds the items that arrived, the return moves to After refund once the refund is complete, with the missing item recorded as open. If it arrives later, the returns inspector can record the inspection, and it goes to the team lead.
Reason
Refunding items that have not arrived is hard to undo. Waiting for everything delays the refund for the items that did arrive. A second refund is outside this screen, and the work left outside it still has someone to take it on.
Taken on by
Recording: the returns inspector. Deciding: the support agent for the return. What remains after the refund: the team lead.
Next step
The support agent chooses whether to wait for the rest or refund what arrived. The team lead records the outcome for the rest and closes the return.
H5

An inspection result is changed

Shown
Changed since you asked: Coffee grinder inspection, No issues → Signs of use (Jonas Berg, 26 Oct).
Behaviour
Before the refund is requested, the result can be changed, with a reason. In Awaiting decision, the agent decides again. In Awaiting approval, the request is withdrawn (P3). After the refund is requested, the warehouse cannot change it; the team lead handles the error as After refund work. The same applies if it is found after the return has closed.
Reason
The basis of a decision should not change without the person who made it knowing.
Taken on by
Changing: the returns inspector. Deciding again: the support agent for the return. After the refund: the team lead.
Next step
The support agent reviews what changed and the refund amounts.
H6

The return is updated while amounts are being entered

Shown
This return was updated (Coffee grinder inspection). Your amounts have been kept. / Lena Vos assigned this return to Tom Weber.
Behaviour
While the screen is open, the return is fetched regularly to update its status, who acts next, and the actions offered. Amounts being entered are not overwritten. The version those amounts were based on is kept as well, and is not replaced by the latest one from the regular fetch. When the amounts are sent, the server checks that version and stops if the basis has changed. If the return was reassigned, the screen says why the actions are no longer offered.
Reason
If a regular update wiped what someone was typing, the update would itself cause a new mistake. But keeping the old amounts with the latest version would defeat the conflict check.
User's side
If the amounts disappear, people have to enter them again without remembering what they had.
Taken on by
The support agent for the return
Next step
Review what changed, check the amounts, and send them.

Results that arrive later

The payment provider's result can arrive after the person who requested it has left the screen. "Not known yet" is treated as a state, alongside success and failure.

5 items in detail
R1

The refund has been requested and the payment provider's result is pending

Shown
Waiting for the payment provider. … There is nothing to do on this return right now. Tell the customer the refund is complete only after the result arrives.
Behaviour
No request action is offered. When the result arrives, the status updates and the activity records it.
Reason
Requesting again while one is processing would refund twice.
User's side
Without being told there is nothing to do, people tend to tell the customer the refund is done, or try another way to refund. "Nothing to do right now" is also an answer to what comes next.
Taken on by
The payment provider (no one needs to act)
Next step
Wait. When the result arrives, the return moves to Refunded or Refund failed.
R2

No response comes back to a refund request

Shown
We couldn’t confirm whether the refund request was received. Checking again will not refund the customer twice. / There is no record of this request on the server. Sending it again with the same details will not refund the customer twice.
Behaviour
Each request is sent with a unique key. "Check result" fetches the return again and looks for the request by that key. If found, its status is shown. If not, the screen does not say it was not sent; it offers to send it again with the same key. While a refund on the return is processing, the server accepts no new request with a different key.
Reason
No response does not mean failure (the same idea as S1 in the shift sample). The request can be checked from the return number, even when the refund ID never arrived.
Taken on by
Whoever requested the refund: the support agent for returns that need no approval, the approving team lead for those that do.
Next step
Check the result. If it is still unclear, see R4.
R3

The refund fails later

Shown
Refund failed on 25 Oct. Reason from the payment provider: the card is no longer valid. This is on the customer’s side, so the same payment method won’t work. The refund is still due by 30 Oct.
Behaviour
The return goes to the "Refund failed" queue. The reason is shown as either on the customer's side or temporary. A temporary reason offers "Try the same method again"; a reason on the customer's side offers "Confirm bank details and request approval".
Reason
The next step depends on the reason. A failure does not stop the deadline. Changing the refund destination is also a known fraud pattern, so it goes through approval.
Taken on by
The support agent for the return; the team lead if they are away.
Next step
Try the same method again, or confirm bank details with the customer and request approval.
R4

No result from the payment provider 48 hours after the request

Shown
No result from the payment provider 48 hours after the request.
Behaviour
The return moves to "Needs check". The refund itself stays pending. It is not requested again automatically, and there is no action for recording a result by hand. If checking shows the provider is still processing, the return goes back to Refund processing and the 48 hours start again from that point.
Reason
If a result recorded by hand differs from the provider's actual state, no one can tell which is right.
Taken on by
The support agent for the return; the team lead if checking again does not settle it.
Next step
Ask the payment provider for the status again.
R5

Part of the order has already been refunded another way

Shown
€89.00 has already been refunded for this order (payment provider record). You can request up to the remaining €95.00.
Behaviour
The provider's refund record sets the upper limit for the refund. If the full amount has been refunded, "Mark as already refunded" is offered, with a required reason. The return moves to Refunded, then to After refund if work such as a missing item remains, or to Closed if not.
Reason
Refunds are sometimes made directly in the provider's dashboard. The provider's record is treated as correct.
Taken on by
The support agent for the return
Next step
Request only the remaining amount, or record it as already refunded with a reason.

Approval that depends on conditions

An approval is tied to the facts at the time of approval. When they change, the decision goes back to the person who made it; once approved, the refund goes ahead without a gap.

6 items in detail
P1

The refund meets an approval condition

Shown
Needs a team lead’s approval. The total is €150 or more. A team lead reviews it, and the refund is sent as soon as it is approved.
Behaviour
The check runs whenever an amount changes, and the action switches to "Request approval". The conditions (€150 or more, refund before inspection, refund above the suggested amount, changed refund destination) come from the server and are not fixed in the screen. The server checks again when the request is sent.
Reason
Saying approval is needed only after the request has been sent means starting over. Approval is the normal path for larger refunds, so it is shown at the "your next step" level, not in warning colours.
Taken on by
The support agent for the return
Next step
Request approval.
P2

A team lead opens a return they requested approval for

Shown
You requested approval for this return, so another team lead approves it.
Behaviour
Your own requests do not appear in your approval queue. Any team lead other than the requester can approve. On days with only one team lead, a deputy approver approves (a fictional internal rule).
Reason
A refund cannot be taken back, so the same person does not both request and approve it.
Taken on by
Another team lead (or the deputy approver)
Next step
Approve, or send it back.
P3

An inspection result or amount changes while approval is pending

Shown
Your approval request was withdrawn. Changed since you asked: … / This request was withdrawn. No action needed.
Behaviour
The server withdraws the request and returns it to Awaiting decision. It also checks again at the moment of approval (the same idea as S4 in the shift sample). A team lead who had it open is told no action is needed.
Reason
An approval applies to the facts at the time of approval. When those change, the decision goes back to the person who made it.
Taken on by
The support agent for the return
Next step
Review what changed, check the amounts, and request approval again.
P4

An approval request is sent back

Shown
Sent back by Lena Vos: Signs of use, so please consider a reduced amount instead of a full refund.
Behaviour
A reason is required to send back. The return goes back to Awaiting decision, in the support agent's "Sent back" queue.
Reason
Without a reason, no one knows what to change for it to be approved.
Taken on by
The support agent who requested approval (the agent for the return); the team lead if they are away.
Next step
Change the amounts and request again, or talk to the customer first.
P5

A team lead approves

Shown
Approve and refund €184.00 / Approve and arrange transfer €95.00
Behaviour
The approval dialog shows the snapshot taken when approval was requested: the amount for each item, the total, the conditions that applied, the refund destination and who requested it. Approving immediately sends the refund to the payment provider, or arranges the bank transfer with Finance.
Reason
With no gap between approval and request, a return can never be approved with no one having requested the refund. The button states the amount and the result, so what happens is clear before it is pressed.
Taken on by
A team lead other than the requester
Next step
Approve, or send it back.
P6

Recording the completion of an external refund (bank transfer)

Shown
Your next step: record the bank transfer / Bank transfer of €95.00 completed · recorded by Lena Vos · proof of payment attached (FIN-2026-0412)
Behaviour
Finance makes the transfer outside this screen. A team lead records the completion with the date, the amount, the Finance reference and proof of payment. An amount different from the approved one is not accepted. The activity shows it apart from results that come from the payment provider. A record cannot be undone; an error is handled as After refund work, including one found after the return has closed.
Reason
A refund outside the payment provider has no result that arrives by itself. A record made by a person can sit alongside the provider's results only when it shows who recorded it, when, and on what evidence.
Taken on by
Team lead (Finance makes the transfer)
Next step
When the transfer is done, record the completion with proof of payment.

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
1

The 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.

2

The 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.

3

Available 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 }] }
1

Sending 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).

2

The 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.

3

The 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
1

Results 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".

2

The 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.

3

Status, 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 }
1

The 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).

2

When 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).

3

The 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)
1

Results from the payment provider and completions recorded by people should look different on screen. Errors in the record should be prevented.

2

The server can store the proof of payment file, along with who recorded it and when. The amount can be checked against the approved snapshot.

3

Proof 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.

What the specification leaves to engineers

This specification decides who takes a return on in each state, what is shown and when, which data is treated as correct, and what the messages say.

How it is built is up to the engineers: how often and how the return is fetched, how provider notifications are received and retried, what runs the stalled and 48-hour checks, and how components and state are structured.

If who takes a return on and what comes next are left undecided, they get decided during implementation, in the wording of error messages. Agreeing them first lets engineers focus on how to build the defined behaviour.

About this sample

The screens are designed in Figma: tokens (colour, spacing, radius, type), components, eleven screen states, and accessibility notes for the four main screens. Every colour pair is checked against WCAG 2.2 AA.

It uses the same token structure as the shift sample, with values set for this product: one design system carried over to different work and a different brand.

See the design

Used on this page

React / TypeScript / Next.js / Tailwind CSS

Used for the design

Figma (variables, component variants and properties)