Overview

A refund is one outgoing return linked to an invoice. It does not cancel or erase the original payment. Refunds created through the API, dashboard, or admin interface appear in the same collection, including returns of payments that were not credited to the merchant.

Read refunds# #

• List refunds: GET /v1/refunds returns all refunds for your API key's merchant and environment.
• Add invoice_id to read one invoice's refunds: GET /v1/refunds?invoice_id=…. Filtering changes the selection, not the response format.
• Get refund: GET /v1/refunds/{refundID} returns one refund's current state. Save its id and pass it unchanged; IDs are opaque strings.

Each record describes one return: amount, currency, network, destination, fees, status, and transaction hash. payment_id identifies the original incoming payment when known. refund_request_id groups returns authorized by one manual confirmation; both fields are null for invoice-level API refunds without payment attribution.

For example, returning two payments of 60 and 40 USDT produces two refund records with the same refund_request_id. One can be completed while the other is still confirming. A later separately authorized attempt has its own refund ID, so earlier failed attempts stay in the history.

Refund from the dashboard# #

Open the invoice and choose Refund. Review the original sender, asset, network, full remaining principal, and fees for every payment. Confirm with your authenticator code. You cannot change the amount or destination; the merchant pays the refund fee and configured network charge.

Accepted payments use the merchant's available balance in their original asset and network. Payments not credited to the merchant return their own held principal; the merchant funds only the charges. No automatic reverse conversion funds a refund.

One blocked payment prevents confirmation of the whole request. Insufficient funds, incomplete confirmations, an unverified source, or an unresolved prior return must be resolved first. A newly arrived late payment requires a new confirmation. An earlier API refund without payment attribution blocks this workflow until reconciled; a confirmed full refund request blocks later custom-address API refunds for the same invoice.

Confirmation accepts the request; it does not mean the money has arrived. Transfers execute separately. If the confirmation response is lost, use Check refund request to repeat the original request instead of creating a replacement.

Create a refund# #

The merchant API creates an individual refund with a chosen amount and destination. It does not expose the dashboard's full-refund confirmation operation.

Use Create refund with invoice_id, currency, network, amount, and a recipient-confirmed destination; include destination_tag when needed. Do not assume an exchange's sender address can receive the customer's refund.

Closed invoices with accepted funds are eligible: paid, overpaid, underpaid, expired, or invalid. The cap is accepted gross principal minus completed and in-flight refunds. Partial refunds are allowed within that cap and the merchant's available balance. A payment not accepted by the platform cannot be returned through this creation operation.

Creation requires refunds:write and an idempotency key. Save the returned ID. The compatibility field payout_id equals the refund ID and does not identify a separate payout. After a timeout, repeat the original body and key. A corrected body may reuse the key only after Idempotency-Key-Released: true.

Fees and states# #

amount is requested principal; recipient_amount is the amount to send after customer-paid commercial charges. merchant_debit_amount is the authorized merchant debit: principal plus merchant-paid charges for an accepted payment, or charges only when held customer funds supply the principal. Failed or reversed execution can release or reverse that debit.

configured_network_fee_amount is the commercial charge. network_fee is measured chain cost when available, not an extra merchant debit. It can be null, including for returns of payments not credited to the merchant. When delivered, the refund.completed webhook identifies the measured fee's currency and network.

There is no refund cancellation operation. Never automatically replace an uncertain or reversed return. Later chain re-inclusion does not automatically resend or rebook it.

Track a full refund# #

1. Read /v1/refunds?invoice_id=… and follow every cursor page to discover the returns.
2. Save their IDs. Periodically read the list or individual refunds with bounded backoff; GET requests never create or retry a transfer.
3. For one manual request, inspect every record sharing its refund_request_id. It is complete only when all those records are completed.
4. Reconcile the invoice's refund_summary too: another payment may have arrived after the confirmation.

Existing refund.created, refund.completed, refund.failed, and refund.reversed webhooks cover refunds of accepted funds. They do not cover returns of payments that were not credited to the merchant. Poll the collection for complete coverage. Deduplicate webhook event IDs and use GET for current state; delivery order is not guaranteed.

Invoice refund summary# #

Invoice GET and list responses include refund_summary. Payment status stays separate: a paid invoice remains paid after a refund. There is no invoice.refunded event.

amounts groups values by currency and network. principal_amount is confirmed incoming principal; refunded_amount is completed return principal excluding reversed executions; recipient_amount is delivered value after customer-paid charges. inflight_amount includes unresolved execution. remaining_amount subtracts completed and in-flight principal, floored at zero; it is not a promise that another refund is eligible.

Never sum different assets or compare their native amounts directly with an invoice's fiat price. A new late payment can change full coverage back to partial without changing the invoice's payment status.