Refunds

When a gateway collects a payment but the upstream service fails to respond, PayWeave automatically creates a refund request. No configuration needed — it works out of the box for every gateway endpoint.

Automatic refund triggers

A pending refund is created whenever the upstream call fails after the on-chain payment has settled:

The refund captures the full error detail — the upstream status code and response body (up to 1,000 characters) — so you can diagnose the root cause from the dashboard.

What happens to the transaction

1. Payer sends paid request to /gw/:gatewayId/endpoint
2. Payment verified on-chain → payment recorded as "settled"
3. Request forwarded to upstream → upstream returns 502
4. Pending refund created automatically
5. Payment marked as "needs_refund"
6. Payer receives the 502 error response

The payer still receives the error response immediately. The refund is recorded in the background and does not block the response.

Processing refunds

Go to Refunds in the sidebar to see all pending refund requests. Click a row to open the payment detail with the full error trace. Click Process Refund to sign and send the on-chain transfer back to the payer.

For multiple pending refunds, use Process N pending to batch them into a single Tempo transaction. One signature, one on-chain transaction, all refunds processed.