Auto-triage Zendesk refund requests against Checkout.com

Every 30 minutes during business hours (default: every 30 minutes, 9am to 6pm, Monday to Friday, in my account timezone), triage new refund requests sitting in Zendesk against the real transaction records in Checkout.com, so my support team stops looking up and processing every refund by hand.

Start with Zendesk Search Tickets to find open or pending tickets that are asking for a refund (search the ticket text for refund language such as refund, money back, chargeback, or cancel and refund). Exclude any ticket already carrying the tag refund-triaged, so a ticket is never worked twice on a later run. For each ticket that comes back, use Show Ticket for the requester and ticket metadata and List Ticket Comments to read the full thread.

From the thread, pull out three things: the customer email address, the order or payment reference they cite, and the reason they are asking. Also work out the amount they are asking for and whether it is a full or partial refund. If the thread genuinely does not identify a transaction, do not guess.

Look the transaction up in Checkout.com using Search Payments against the order reference first, falling back to the customer email if there is no reference. Confirm the match with Get Payment Details to read the amount, currency, status, and creation date. Payment ids are prefixed pay_ and customer ids cus_. If Search Payments returns several plausible payments and none is a clear match, treat the ticket as unidentified rather than picking one.

Before deciding anything, call Get Payment Actions to list the authorization, capture, refund, and void actions on that payment. Add up every refund action already recorded. This is the guard against issuing a duplicate refund, so treat it as mandatory: if the payment is already fully refunded, or the existing refunds already cover what the customer is asking for, do not refund again.

Then apply the refund policy. Auto approve and issue the refund only when all of these are true: the payment status is captured, the payment date is inside the refund window (default 30 days), the refund amount is under the auto approve threshold (default 100 in the account currency), and the ticket clearly identifies exactly one transaction.

Be careful with amounts. Checkout.com expresses amounts as integers in the currency's minor unit, so 1000 means 10.00 GBP. Zero-decimal currencies such as JPY and KRW use the major unit directly, and three-decimal currencies such as BHD, KWD, and OMR are the value times 1000. Convert the auto approve threshold into the same minor unit as the payment before comparing, otherwise the threshold check will be wrong by a factor of 100.

When a refund is approved, issue it with Refund a Payment and send an Idempotency-Key header derived from the ticket id and payment id so that a retry can never double refund. This call returns 202 Accepted with an action id and is processed asynchronously, so the response does not confirm settlement. Confirm the outcome by calling Get Payment Actions again and reading the status of the new refund action.

For an approved refund, use Update Ticket twice over: post a public reply to the customer confirming the refund has been issued and telling them to expect it in 5 to 10 business days back on their original payment method (do not claim it has already landed in their account), and add an internal note recording the payment id, the refunded amount and currency, the refund action id, and the policy reason it qualified for auto approval.

Do not refund when the amount is over the threshold, the payment is already refunded in full or in part covering the request, the payment is outside the refund window, the payment is not captured, or the ticket does not clearly identify a transaction. In those cases leave an internal note on the ticket via Update Ticket explaining what was searched and what was found, then send a Slack message to the payments channel (default #payments) containing a link to the ticket, what the customer asked for, what was found in Checkout.com including the payment id, amount, status, date, and any existing refunds, the specific reason it was not actioned automatically, and a clear recommendation so a human can make the call quickly.

Finally, whichever path was taken, tag the ticket refund-triaged with Update Ticket so the next scheduled run skips it. Zendesk overwrites the whole tag array on a ticket update, so read the existing tags and write them back along with the new one rather than replacing them. Zendesk's search index also lags writes by a few seconds, so rely on the tag rather than on search freshness to avoid rework, and skip any ticket already tagged even if search returns it again.