Checkout.com billing lookup console for support agents

Build me an internal billing lookup console my support agents can open instead of asking someone with a Checkout.com login. It is a tool humans work one customer at a time, so nothing runs on a schedule and nothing decides a refund on the agent's behalf.

The landing view is a single search box. An agent pastes a customer email address, an order reference or a Checkout.com payment id, and the app works out which one it received. A value starting with pay_ goes straight to Get Payment Details. A client reference goes to Get Payment Lists to pull the payments recorded against that reference, falling back to Search Payments when nothing matches. An email goes to Get Customer Details to resolve the customer, then Search Payments for their payments. Results render in a table showing amount, currency, status, card brand and last four digits, and the payment date, newest first, using the cursor pagination Search Payments returns so long histories keep loading.

Clicking a row opens the payment. The heart of that screen is a plain-English timeline built from Get Payment Actions, so the agent reads lines like "Authorized 12 Mar for 45.00 GBP", "Captured 13 Mar" and "Refunded 10.00 GBP on 2 Apr" rather than raw action records. Show the authorization, the capture, every partial refund already issued and any void. Beside the timeline show the customer record and their stored cards from Get Customer Details and Get Instrument Details, and check Get Disputes filtered to this payment so an attached dispute is visible before anyone touches a refund.

From that screen the agent can act, and which action is offered is derived from the payment status rather than showing both buttons and letting the API reject one. A payment that is authorized but not yet captured offers Void a Payment. A captured payment offers Refund a Payment, either in full or for an amount the agent types. Every action requires a reason picked from a short configurable list such as duplicate charge, item not received, goodwill or cancelled order. A free-text note is optional on top of the reason, never instead of it.

Get the money handling exactly right. Checkout.com amounts are integers in the currency's minor unit, so the partial refund box must accept a normal amount like 12.50 and convert it for the payment's currency, allowing for zero-decimal currencies such as JPY and three-decimal ones such as KWD. Validate the typed amount against how much is still refundable after earlier partial refunds, and block anything over that with a clear message in the form.

Refunds and voids return 202 Accepted with an action id and complete asynchronously, so never report success the moment the call returns. Show a pending state, then poll Get Payment Actions until the matching action reaches a final status, and update the timeline in place when it does. Send an Idempotency-Key on every refund and void so a double-click, a page refresh or a retry cannot issue the refund twice. That is the single most damaging bug in a tool like this, so also disable the action button the moment it is pressed.

If the agent has a Zendesk ticket open, the console finds it with Search Tickets by requester email or ticket number, shows the recent comments from List Ticket Comments beside the payment for context, and after a completed refund or void writes an internal note back with Update Ticket recording exactly what was refunded, how much, why, and which agent did it. The note must be internal, never a public reply to the customer.

An admin sets a refund approval threshold in a settings screen. Refunds at or below it are executed by the agent directly. Refunds above it are not executed at all. Instead the console posts an approval request to a Slack channel with the Slack Bot integration, naming the agent, the customer, the payment, the amount and the reason, and holds the request in a pending approvals list inside the app until a supervisor approves or declines it there. Every completed action posts to the same channel too, so the channel reads as a running audit trail.

Persist a record of every action attempt: the signed-in agent, the payment, the amount, the reason, the linked ticket, the resulting status and the timestamp. That record powers the pending approvals list and an audit log view an admin can filter by agent or by date. Attribute actions to whoever is signed in rather than to a shared account, since naming the agent is the whole point of the audit trail.

Keep the console focused on human lookup and action. It is where escalated refund requests get worked by a person, so do not build automatic triage rules into it.