Refunds

Refund paid sessions and invoice.

Open the interactive version or read this guide as markdown.

API reference

POST /api/v1/refunds/session/{sessionReference}: Refund a payment
POST /api/v1/refunds/invoice/{invoiceReference}: Refund an invoice
GET /api/v1/refunds: List refunds

A refund returns crypto to a customer for a payment or invoice they already made. CoinCircuit already knows the original amount and asset, so you only give the wallet address to send it to. The refund settles on the blockchain, and a webhook confirms when the customer has the funds. It comes out of your settled balance, except for a refund of an underpayment you never accepted, which is not debited because those funds were never credited there.

CoinCircuit refund — original payment and refund amount

How it works

Estimate the cost with GET /api/v1/refunds/estimate/{reference}?entity=session|invoice. The estimate includes network fees.
Refund a session with POST /api/v1/refunds/session/{sessionReference}, or an invoice with POST /api/v1/refunds/invoice/{invoiceReference}.
Track status with GET /api/v1/refunds and GET /api/v1/refunds/{id}.

Request fields

Field	Type	Required	Description
`refundAddress`	string	Yes	Customer wallet address that receives the refund.
`reason`	string	No	Reason for the refund.
`feePaidBy`	string	No	Who pays the network fee: `merchant` or `customer`. Defaults to your merchant settings.

Webhook events

Event	Sent when
`refund.created`	The refund is initiated.
`refund.success`	The refund is confirmed on-chain.
`refund.failed`	The refund could not be completed.

Use cases

Cancelled orders and returns
Overpayments and duplicate charges
Dispute resolution and goodwill credits

Refunds are paid from your balance. Run the estimate first to see the net cost, including network fees.