Functions

Refunds

When a function handler collects a payment but fails during execution, PayWeave automatically creates a refund request with the full error trace. This covers both unhandled exceptions and handlers that return 5xx responses.

Automatic refund triggers

Failure	What happens
Handler throws	Unhandled exception — refund created with the stack trace
Handler returns 5xx	Response body parsed for error detail and stored with the refund
Execution timeout	Worker times out — refund created with timeout error

The full error trace (up to 1,000 characters) is captured in the refund record. Open the payment detail page to see exactly what went wrong.

Handlers that return 4xx responses are not refunded. If your handler returns 400 or 422, it means the handler ran successfully but rejected the input. Design your handlers to throw or return 5xx only for genuine failures.

Example: handler that triggers a refund

TypeScript

async function handler(input, { secrets, fetch }) {
  // This call might fail — if it does, PayWeave auto-refunds the payer
  const res = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${secrets.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: 'gpt-4',
      messages: [{ role: 'user', content: input.prompt }],
    }),
  });

  if (!res.ok) {
    // Returning 5xx triggers auto-refund
    return new Response(
      JSON.stringify({ error: `OpenAI returned ${res.status}` }),
      { status: 502 }
    );
  }

  const data = await res.json();
  return { result: data.choices[0].message.content };
}

Processing refunds

Go to Refunds in the sidebar. Pending refunds show the handler name, error trace, and payer address. Click a row to see the full payment detail, then click Process Refund to sign the on-chain transfer.

Use Process N pending to batch multiple refunds into a single Tempo transaction.

Test your handlers in test mode first. Test mode payments use test tokens — if a handler fails, the auto-refund fires but no real money is involved.

Secrets Overview