How to refund a payment

Refunds return a paid merchant order back to the payer. A refund is always tied to an existing order — you cannot refund an arbitrary amount — and it is a two-step flow: estimate the refund first to learn the fees, then initialise it with the fee you were quoted.

Endpoint overview

HTTP Request	Description
`POST` `/public/merchants/refunds/estimate`	Estimate the amounts and fees for refunding an order.
`POST` `/public/merchants/refunds`	Initialise the refund.
`GET` `/public/merchants/refunds`	List your refunds, with pagination and filtering.
`GET` `/public/merchants/refunds/{id}`	Retrieve a single refund.

Reading refunds requires the merchants-refunds:read scope; estimating and initialising require merchants-refunds:create. See Scopes.

Step 1 — Estimate the refund

Estimation tells you what the payer will receive and what you will be charged, before anything moves.

Request body

Field	Required	Description
`merchantOrderId`	yes	The order being refunded.
`address`	yes	Destination address for the refunded funds.
`feeCurrencyCode`	yes	Currency the fees are charged in.
`networkCode`	no	Blockchain network to use, when the currency supports more than one. See Supported networks.
`amountType`	no	`PAY_AMOUNT` or `RECEIVE_AMOUNT` — whether the amount you specify is what leaves your account or what the payer receives.
`message`	no	Free-text note stored with the refund.

Response body

Field	Description
`paidAmount`	Amount originally paid on the order.
`currencyCode`	Currency of `paidAmount`.
`feeAmount`	Total fee for the refund.
`refundFeeAmount`	The refund fee component.
`withdrawFeeAmount`	The network/withdrawal fee component.
`feeCurrencyCode`	Currency the fees are charged in.
`gasPrice`, `gasLimit`	Present for networks where gas applies.

Step 2 — Initialise the refund

Send the fee you were quoted in step 1. The request is rejected if the order cannot be refunded.

Request body

Field	Required	Description
`merchantOrderId`	yes	The order being refunded.
`refundAccountId`	yes	Wallet the refunded amount is taken from.
`feeAccountId`	yes	Wallet the fees are taken from.
`feeAmount`	yes	Fee accepted for this refund — use the value returned by the estimate.
`address`	no	Destination address.
`networkCode`	no	Blockchain network, where applicable.
`amountType`	no	`PAY_AMOUNT` or `RECEIVE_AMOUNT`.
`message`	no	Free-text note.
`beneficiaryId`	no	Saved beneficiary to refund to, where Travel Rule information is required.

📘
Estimate immediately before initialising. Fees move with network conditions, and a stale feeAmount will not match the current quote.

Tracking a refund

GET /public/merchants/refunds lists refunds with pagination; GET /public/merchants/refunds/{id} returns one. Both require merchants-refunds:read.