Refunds

A refund is an outbound money movement, so it rides the outbound half of the platform. Three pieces are involved, and you will usually touch all three.

1. Moving the money back

• codespar_pay is the outbound meta-tool: payouts, supplier disbursements, and refunds. Where codespar_charge requests money in, codespar_pay sends it out to a recipient, including back to a buyer. See Charge vs Pay.
• Provider refund tools. Connections also expose their provider's native refund surface through the tool router, tied to the original transaction rather than a free-form transfer, for example a Pix devolution on a Pix connection, or a card refund on a card processor's server. When you need "refund THIS payment" semantics (partial amounts, linkage to the original end-to-end id), prefer the provider tool on the same connection that took the charge.

Which of the two applies depends on the rail and the provider connection in your project; the provider tool list for each connection is discoverable in the catalog and via codespar_discover.

2. Knowing it settled

Subscribe a trigger to commerce.payment.refunded: it fires when the provider processes the refund, with the refunded amount in the payload (on Stripe, amount_minor carries it). commerce.payment.disputed is the neighboring event for chargebacks, which are a different animal: a dispute is opened against you, not initiated by you.

3. What it costs

A refund that reaches a terminal state counts as one settled transaction under Orchestration billing, the same $0.10 as the charge it reverses. Movements that never settle are free.

Honest edges

• Refund coverage follows the provider connection: not every provider exposes partial refunds, and Pix devolution windows are set by the rail, not by CodeSpar.
• There is no single cross-provider "refund this charge" meta-tool today; the pattern above (provider tool for linked refunds, codespar_pay for free-form returns) is the supported path.