The problem

You need to refund an agent payment, return money for a payment that already happened, because a service did not deliver, a dispute resolved in the payer's favor, or your policy calls for it. Coming from card systems, you expect a refund to reverse the original charge. You look for that reverse-the-payment action and do not find it, which leaves you unsure how to actually return the funds for a payment that has settled.

This is the agent-payment-refund problem, and like disputes, it starts with understanding that settlement is final. There is no reverse-the-charge operation, because the payment cannot be undone. The symptom is wanting to refund a settled agent payment and finding no reversal; the fix is to refund the way final-settlement systems do, by sending the money back as a new payment. Once you see a refund as an outbound payment rather than a reversal, the path is clear.

The honest reality

The honest reality is that agent payments settle finally, so a refund is never a reversal of the original payment. The original payment moved USDC on chain and stays settled; you cannot claw it back. A refund is therefore a separate, new payment, you send funds back to the original payer for the refund amount, which makes them whole without touching the first transaction. There are now two payments in the record: the original, and the refund going the other way.

This follows directly from the finality that means agent payments have no chargebacks. Because nothing reverses automatically, returning money is always an action you take, sending a payment, not a mechanism that fires. Accepting this reframes the task: do not look for a refund button that reverses the charge; instead, send a refund payment. That is the only way to refund on a final-settlement rail, and it is a clean, explicit one, two recorded payments rather than a hidden reversal, which is the model to work with.

The fix

The fix is to send a payment back to the original payer for the refund amount. You determine the payer from the payment record, the original payment.received event and your log identify who paid, and you send USDC to that payer's address for the amount you are refunding, full or partial. That outbound payment is the refund, settling like any payment, and once it confirms, the payer has been made whole.

So refunding is sending a payment, using the same payment capability you use to pay anything else, directed at the original payer. There is no special refund endpoint that reverses; there is an ordinary outbound payment you label as a refund in your own records. The fix to the refund problem is therefore to treat a refund as a normal outbound payment to the payer, executed deliberately when warranted. This is the resolution mechanism referenced in the dispute material, see agent-payment-dispute, made concrete.

How to implement it

To implement a refund, send the payment to the payer. The direct payments API lets you create a payment from an agent to an address: client.payments.create({ agentId, to, amountWei, token }), where to is the original payer's address and amountWei is the refund amount in USDC base units. That sends the refund as an outbound payment, which settles and is recorded.

Two honest notes. First, the direct payments API is in progress and may return a transient 503 during the chain-adapter rollout, so treat a 503 as temporary, re-check, and retry the transient case rather than assuming the refund failed. Second, confirm the refund actually settled, via its payment record, before considering it done, the same confirmation discipline as any payment. So implementing a refund is creating an outbound payment to the payer and confirming it, handling the transient case carefully. Get the payer's address from your records, send the amount, and verify it landed.

Record the refund

Recording the refund well matters for accounting, because there are now two related payments. Log the refund linked to the original payment, so your records show that this outbound refund corresponds to that inbound payment, with the amount and reason. That linkage is what lets your accounting net the two correctly and gives you a clear trail of what was paid, refunded, and why.

Without that link, a refund looks like an unrelated outbound payment, which muddies reconciliation and reporting. So when you issue a refund, capture the relationship, store the original payment's id alongside the refund, or tag both, so the pair is reconstructable. Build refunds on the same transaction-recording practice you use for payments generally, covered in how-to-track-ai-agent-transactions, and extend it to mark refunds and their originals. Good records turn refunds from a source of accounting confusion into a clean, auditable pair of transactions.

Set a refund policy

Because refunds are deliberate actions rather than automatic mechanisms, decide a refund policy up front rather than handling each case ad hoc. State when you refund, a paid service that did not deliver, a dispute resolved in the payer's favor, a satisfaction window, whatever fits, so both you and your counterparties know what to expect. A clear policy makes refunds predictable and reduces disputes, since the conditions are known in advance.

The policy also guides automation if you want it: if certain conditions clearly warrant a refund, you can have your application issue the refund payment automatically when they are met, rather than handling every refund by hand. Whether manual or automated, the policy is what turns refunds from improvised reactions into a consistent practice. So part of solving the refund problem is not just knowing how to send a refund, but deciding when you will, which makes the whole approach coherent rather than case-by-case.

Partial refunds and edge cases

A few practicalities are worth planning for. Partial refunds are straightforward on this model: since a refund is just an outbound payment, you send back whatever portion you owe rather than the full amount, and record it as a partial against the original. There is nothing special to enable; you choose the amount. Multiple partial refunds against one payment are likewise just multiple outbound payments, all linked to the original in your records.

Two edge cases deserve thought. First, refunding more than was paid, or refunding the same payment twice, is possible by mistake precisely because refunds are ordinary payments with no built-in cap against the original, so guard against it in your own logic by tracking how much of each payment has been refunded. Second, fees: a refund is a new payment and carries its own settlement, so a full refund of a tiny payment may not be worth the overhead, which is one more reason small per-call amounts rarely warrant refunds. Handling partials cleanly and guarding against over-refunding are the main things to get right, and both live in your application logic rather than in any built-in refund mechanism, since there is none to lean on.

Related reading

Refunds are the resolution side of disputes, so see agent-payment-dispute for handling disagreements that may lead to a refund, and how-to-track-ai-agent-transactions for recording refunds linked to their original payments. Together they cover deciding on and executing refunds on a final-settlement rail. Pricing is on the pricing page.