Establish which refund scenarios the agent is authorized to initiate without human approval (e.g., item not delivered after N days, duplicate charge detected) versus which require human sign-off; encode this as a refund policy object.
Before initiating, verify the refund preconditions: the original charge is in a refundable state (settled, not already fully refunded, within the refund window), and the refund reason matches an authorized policy trigger.
Collect and store evidence before calling the refund API: the original PSP charge ID, order ID, reason code, and any supporting data (delivery tracking showing non-delivery, duplicate charge detection log); this evidence is required if the merchant disputes the refund or if you need to justify the action in an audit.
Call the PSP refund endpoint with the charge ID, amount (partial or full), and reason; use an idempotency key constructed from the original charge ID and refund reason to prevent duplicate refunds.
Persist the refund record with status in your audit log and your order management system; update the wallet balance to reflect the incoming refund once it settles.
If the refund API returns an error (e.g., charge not refundable, refund window expired), the agent must surface this to the human with the full context rather than marking the task as failed silently.
Known gotchas
Refund windows vary by PSP and card network — Stripe allows refunds on charges up to a year old in some cases, but card network rules may not credit back to the original card after 180 days; always check the PSP's refund eligibility before attempting.
A refund does not cancel a subscription or future charges — if the agent is handling a subscription dispute, a refund of the last charge and a cancellation are two separate actions, both required.
Automated refunds on behalf of customers may trigger fraud detection at the PSP level if the pattern is unusual (many refunds in a short period) — spread refund initiation over time if batch-processing and notify the PSP if you anticipate high refund volume.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp