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.
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