PayWeaveRefunds
PayWeave automatically detects when a payment was collected but the service failed to deliver. A refund request is created and made available for the workspace owner to review and process. Refunds follow the MPP charge-flow refund model: a standard on-chain transfer back to the payer's address.
How automatic refunds work
When a paid request fails after the on-chain payment has settled, PayWeave records a pending refund with the full error trace. This happens automatically for:
| Channel | Trigger |
|---|---|
| Gateways | Upstream returns 5xx or connection fails |
| Functions | Handler throws an exception or returns 5xx |
| Files | File not found in storage or storage unavailable |
Direct app charges (SDK middleware) do not trigger automatic refunds because the app developer controls their own error handling on their server.
Reviewing refunds
Go to Refunds in the sidebar. Pending refunds are shown by default. Each row shows the refund amount, the payer's address, the trigger (automatic or manual), and the reason. Click a row to open the full payment detail with the complete error trace.
Processing a refund
Since workspace wallets are non-custodial, PayWeave cannot send funds on your behalf. To process a refund, click Process Refund on the payment detail page. This opens a signing dialog where your embedded wallet signs an ERC-20 transfer back to the payer. The signed transaction is submitted through the PayWeave backend for tracking.
Batch refunds
If you have multiple pending refunds, click Process N pending on the Refunds page. All transfers are bundled into a single Tempo batch transaction. You sign once, and all refunds are processed atomically in one on-chain transaction.
Manual refunds
You can also issue a refund for any settled payment manually. Open the payment detail page and click Refund. This creates a pending refund that you can then process using the same signing flow.
Refund statuses
| Status | Meaning |
|---|---|
| Pending | Refund recorded, waiting for the workspace owner to sign and send. |
| Completed | Refund transaction confirmed on-chain. Payer has been reimbursed. |
| Failed | Broadcast failed (e.g. insufficient balance). Can be retried. |
Platform fees on refunds
Currently, only the workspace portion of the original payment is refunded. The platform fee (3% on Free, 1% on Pro) is not refunded. This may change in a future update.