Linked merchant refunds.
Prepare a full or partial testnet refund from an order, review every cost and approve with a passkey. Live outgoing services remain subject to activation and verified pilots.
01Choose the original order and recipient
Open Orders & invoices, check the current order and select Prepare refund. Use the exact original asset and network. Enter a full customer-confirmed refund address or use recipientId in the app-session API. Never assume the sending address belongs to the buyer; exchanges and contracts may not accept a return. Record a reason.
02Review the real principal budget
Only independently verified available gross receipts count. Actual overpayments count; waived invoice balances and internal top-ups do not. Reserved and delivered refund principal reduce the remaining budget. Unknown outcomes remain reserved. Original deposit fees remain recorded, so the order wallet may need an internal top-up to cover a full gross refund plus new processing and network fees.
03Approve the frozen quote
Preparing a quote moves no money. An approved applicable refund tariff takes priority; otherwise the quote explicitly discloses the approved withdrawal-tariff fallback. Review recipient amount, full address, processing fee, maximum network reserve, total debit and 60-second expiry. A recent passkey approval is required for confirmation. The order budget, outgoing reservation and linked intent commit together.
04Follow delivery and cancellation
Recover an interrupted action using the exact saved key and payload. An unused quote or unprepared reservation can be cancelled with a recent passkey. Once preparation starts, cancellation is unavailable. A broadcast, error string or cached completed status cannot free the budget. Actual canonical signed settlement and financial journals establish delivered principal or a failed zero-delivery return.
05Check fulfillment again
Current order responses expose a separate refund summary. Reserved, delivered or unverified refunds block canFulfill and stop checkout instructions. Original gross, net and fees remain in the payment record. Historical paid events do not authorize new fulfillment; always recover the current authenticated individual order and deduplicate your own fulfillment. Merchant bearer keys currently have no refund spending authority.
06Cancel an unused quote
POST /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds/{refundId}/cancel-quote accepts {} with the original Idempotency-Key, current Owner/Admin app session and a recent passkey. It closes only an unused quote without reserving, releasing or sending funds. A consumed quote or linked reservation is rejected. Its refund_quote_cancelled confirmation is historical; refresh current refund details afterward. Retry the exact key/body after a lost response. Refunds with a reservation continue through the separate original cancellation workflow.
07Trace recorded refund activity
The refund detail includes quote requests, reservations and cancellation actions. GET /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds/{refundId}/history returns these private app-session records with limit (default 20, maximum 50) and before pagination. A cursor belongs to that exact refund. Activity does not prove delivery or financial finality; use the current refund receipt and verified order budget for financial decisions.
POST /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds
Idempotency-Key: <stable-refund-request>
{ "expectedOrderRevision": 2, "amount": "5", "destination": "<full-customer-confirmed-address>", "reason": "Customer requested a partial refund." }
GET /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds/{refundId}
POST /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds/{refundId}/confirm
Idempotency-Key: <stable-refund-confirmation>
{ "quoteId": "<original-quote-uuid>" }
POST /v1/workspaces/{workspaceId}/merchant/orders/{orderId}/refunds/{refundId}/cancel
Idempotency-Key: <stable-refund-cancellation>
{}
// App session, current membership and recent passkey for confirm/cancel.
// Testnet only. There is no separate payment to unlock a refund.Open your workspace