Review Adyen refunds from Zendesk with two-person approval

I want a refund approval console my support leads can work out of, so they can review and issue Adyen refunds without every agent needing an Adyen Customer Area login. This is a governance surface first: every refund passes through a human, large ones need a second approver, and everything that happens gets written down.

The main view is a refund queue. Populate it from Zendesk using Search Tickets against the tag we use for refund requests (default it to refund-requested and make the tag configurable). Show one row per ticket with the requester, the subject, when it came in, how long it has been waiting, and the current decision state held in this app: awaiting review, awaiting second approval, submitted, confirmed, or declined. Let the reviewer filter by state and sort by age so nothing rots at the bottom of the list.

Clicking a row opens a detail pane with the full story. Use Zendesk List Ticket Comments to render the ticket thread, both public replies and internal notes, in order, so the reviewer reads what the customer actually said before deciding anything. Alongside the thread, show the payment reference the agent recorded on the ticket.

There is a hard constraint to design around. Adyen has no operation to look up a payment by PSP reference and no transaction search, so the app can never browse Adyen transactions or display a payment's original amount or status from Adyen. The PSP reference has to come from the Zendesk ticket, either read from a custom field on the ticket or pasted into the app by the reviewer. Show the reference found on the ticket, let the reviewer correct or supply it, and require them to confirm it before the approve action unlocks. Do not build any view that implies the app knows the payment's real state.

The reviewer then decides an amount, full or partial, and picks one of three Adyen actions. Put the selection guidance directly in the UI next to the choice, not buried in a help doc: use Refund a Captured Payment when the payment was already captured, Cancel an Authorised Payment when the charge was authorised but never captured, and Reverse a Payment when the reviewer is unsure of the capture state, because a reversal works out the right one automatically. Reverse should be the safe default when nothing on the ticket tells us the capture state. Amounts go to Adyen as a currency plus a value in minor units, so let the reviewer type 25.00, convert it, and show them the minor-unit value about to be sent.

Bake in an approval threshold. Any refund at or above a configurable amount cannot be submitted by the reviewer who raised it. It moves into an awaiting second approval state and a different signed-in user has to approve it inside the app, and the first approver must never be allowed to act as the second. Below the threshold, a single reviewer can submit on their own. Require a short written reason on every decision, whether it is an approval or a decline.

When a refund is submitted, call the chosen Adyen operation and then persist a record of it in the app: the ticket id, the PSP reference used, which operation ran, the amount and currency, the modification PSP reference Adyen returns, who approved it, who second-approved it, the reasons given, and the timestamp. Then use Zendesk Update Ticket to post the customer reply as a public comment and move the ticket to solved, and use Slack Bot Send a Message to drop a short note in the finance channel with the ticket, the amount, the operation used, and who approved it.

Adyen modifications are asynchronous, and the interface has to respect that. The HTTP response comes back with status received plus its own modification PSP reference, while the real CAPTURE, REFUND, or CANCELLATION result arrives later by webhook rather than in that response. So the app must say the refund was submitted and must never claim the money is back with the customer. Show submitted records in a pending state with their modification reference, and give the reviewer a way to return on a later pass and mark the outcome as confirmed or failed themselves. Word the on-screen confirmation, the ticket reply, and the Slack note the same careful way.

Give the app an audit view over everything it has persisted: every refund submitted, who approved it, who second-approved it where the threshold applied, the amount, the operation used, the reason given, the ticket it came from, and the final outcome once someone confirmed it. Make it filterable by approver and by date range, since this is the view someone opens when finance or an auditor asks what happened and when.

Include a small settings area for the threshold amount, the Zendesk tag the queue watches, the Zendesk custom field that holds the PSP reference, the Adyen merchant account, and the Slack channel used for finance notes.