# Refunds and disputes: how they work and what they cost

> Refunds return purchase amounts while forfeiting processing fees, whereas disputes deduct the charge plus a $15 fee while the bank investigates.

**A refund returns a customer's money while you absorb the non-refundable processing fees, whereas a dispute forcibly removes the transaction amount plus a $15 fee from your balance while the cardholder's bank investigates.** A refund is a voluntary resolution you handle directly with your buyer. A dispute—often called a chargeback—occurs when a buyer bypasses you and asks their bank to reverse the charge. 

Both actions impact your balance, your cash flow, and your ledger. When you sell with thelastapi, [taking payments online without opening a merchant account](https://thelastapi.dev/blog/take-payments-without-merchant-account) means thelastapi acts as the merchant of record on card statements (shown as `VIBIZ, INC* <SUFFIX>`). Here is how refunds and disputes work under the hood, what they cost, and how to handle them in your application.

## How refunds work and what they cost

When you issue a refund, the full or partial purchase amount is returned to the buyer's card. However, the original transaction fees are not recovered. Card processing networks do not return their fees when a charge is reversed, and the thelastapi platform fee is also not returned.

As broken down in our guide on [payment fees explained: what a $100 sale leaves you](https://thelastapi.dev/blog/payment-fees-100-sale), a typical $100 sale on a standard US card breaks down into:
- Gross payment: $100.00
- Card processing fee (2.9% + 30¢): $3.20
- Platform fee (200 bps): $2.00
- Net balance added: $94.80

If you issue a full refund for that $100 transaction, the buyer receives $100.00 back on their card. Your project balance is debited the full $100.00. Because the initial $5.20 in fees is not returned, the net cost of the refunded transaction leaves your account $5.20 lower than it was before the sale occurred.

| Event | Buyer pays / receives | Processor fee | thelastapi fee | Dispute fee | Net change to your balance |
| --- | --- | --- | --- | --- | --- |
| Initial $100 sale | Pays $100.00 | -$3.20 | -$2.00 | $0.00 | +$94.80 |
| Full refund issued | Receives $100.00 | $0.00 returned | $0.00 returned | $0.00 | -$100.00 (Net loss: -$5.20) |
| Dispute opened | Bank holds $100.00 | $0.00 returned | $0.00 returned | -$15.00 | -$115.00 |
| Dispute won | Buyer keeps charge | $0.00 | $0.00 | +$15.00 returned | +$115.00 (Net returns to +$94.80) |
| Dispute lost | Buyer gets $100.00 | $0.00 | $0.00 | $0.00 | $0.00 (Net loss: -$20.20) |

A refund cannot exceed the amount remaining on the initial transaction. Additionally, the system checks whether your project has enough funds to cover the refund. If your project's balance (available plus pending, plus this payment's own fees) is lower than the refund amount, the request fails with `insufficient_balance` (HTTP 409). There is one exception: a project's very first sale can always be refunded in full, even before additional earnings land.

When handling non-USD transactions across the 35 supported currencies, the balance always remains in USD. A foreign currency refund deducts whatever the payment processor converts the amount back to on that day, which might fluctuate slightly from the initial settlement rate.

## How disputes work and what they cost

A dispute happens when a customer contacts their card-issuing bank to challenge a charge. Common reasons include unrecognized charges, claims of non-delivery, or dissatisfaction with a product.

When a dispute opens:
1. The disputed transaction amount is immediately deducted from your project balance.
2. A **$15 dispute fee** (`dispute_fee_cents: 1500`) is also deducted from your balance.
3. Your app receives a `dispute.created` webhook notification.

While the dispute is active, you cannot manually refund the charge via the API. Refunding an actively disputed payment returns a `conflict` error with `reason: disputed` (HTTP 409), because the processor has already withdrawn the contested funds.

Once the bank reviews the evidence and makes a ruling:
- **If you win the dispute**: The bank returns the disputed transaction amount to your balance, and the $15 dispute fee is returned to your balance. Your app receives a `dispute.closed` webhook.
- **If you lose the dispute**: The customer retains the money, and the $15 dispute fee is kept by the card network. The loss remains permanent.

If a wave of refunds or disputes pushes your balance into negative territory, the ledger registers a negative balance (`conflict` with `reason: negative_balance`). A negative balance blocks all subsequent bank withdrawals until you earn the amount back through new sales.

## Who has permission to refund live money?

AI coding agents and background workers often manage application tasks using Limited project keys. To protect your business from unintended fund transfers, permission to move live money is restricted.

In production:
- Limited API keys and app keys cannot issue refunds, cancel subscriptions, or make withdrawals. An attempt returns `403 forbidden` with `reason: owner_only`.
- Live refunds must be completed by the project owner in the console under **Payments ▸ the payment ▸ Refund**, or requested using an account key (`vz_sk_...`) with full access.
- In test mode (`env=development`), agents and Limited keys have full permission to simulate and execute refunds and disputes.

This boundary guarantees that background workers and agent workflows can safely inspect data without the authority to drain your balance.

## How to handle refunds and disputes in code

Your server should react automatically when a refund occurs or a dispute is opened. The [payments documentation](https://thelastapi.dev/docs/payments) and the guide on [webhooks](https://thelastapi.dev/docs/guides/webhooks) describe how thelastapi broadcasts payment lifecycle changes to your endpoint.

Configure your webhook endpoint with the CLI:

```bash
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev
```

In production, webhooks automatically route to `https://<the app's site>/api/vibiz/webhook`. Your endpoint receives a raw request signed with HMAC-SHA256 in the `Vibiz-Signature` header. Using `@vibiz/app`, your server action or API route verifies and unpacks the event automatically using your `VIBIZ_APP_KEY`:

```ts
// app/api/vibiz/webhook/route.ts
import { vibiz } from '@vibiz/app';

export async function POST(req: Request) {
  let event;
  try {
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('bad signature', { status: 400 });
  }

  switch (event.type) {
    case 'payment.refunded': {
      const payment = event.data.object;
      // Revoke credits, update order status, or alert your team
      console.log(`Payment ${payment.id} refunded. User: ${payment.user}`);
      break;
    }
    case 'dispute.created': {
      const dispute = event.data.object;
      console.log(`Dispute opened for payment ${dispute.payment_id}`);
      break;
    }
    case 'dispute.closed': {
      const dispute = event.data.object;
      console.log(`Dispute resolved. Status: ${dispute.status}`);
      break;
    }
  }

  return new Response('ok');
}
```

Because delivery failures trigger retries with exponential backoff over 3 days, make sure your event handler is idempotent by checking `event.id`.

## Testing refunds and disputes before launching

You should never wait for an angry customer to discover how your application handles reversals. The CLI allows you to simulate the entire lifecycle inside your development environment without touching real bank rails.

First, simulate a charge in your development environment:

```bash
vibiz payments simulate payment --amount 5000 --dev
```

Next, simulate a refund using the payment ID returned from your payment list:

```bash
vibiz payments simulate refund pay_12345
```

You can also simulate a dispute to see how your webhook routes and user permissions respond when funds are forcibly held:

```bash
vibiz payments simulate dispute
```

Unlike live transactions, which stay in a `pending` state for a 7-day hold period (`fees.hold_days`) before becoming available for withdrawal, development payments settle instantly with no hold.

## Next steps

Set up your webhook route at `/api/vibiz/webhook` and run `vibiz payments simulate refund` to make sure your app revokes user access or updates order records when charges reverse. To see how these fees fit into your general ledger and withdrawal schedules, read [Payments: how money moves](https://thelastapi.dev/docs/guides/payments).

## Frequently asked questions

### Are processing fees refunded when I issue a customer refund?

No. Card processing networks and thelastapi do not return their transaction fees on refunded purchases, so the processing cost is absorbed by your balance.

### Can a refund result in a negative account balance?

Yes, if refunds or dispute fees exceed your total earnings, your project enters a negative balance state. When this happens, withdrawals are blocked until new customer sales earn the balance back.

### What happens if I win a customer dispute?

If the card issuer decides the dispute in your favor, both the disputed transaction amount and the $15 dispute fee are returned to your project's balance.

### Can an automated agent issue refunds on live transactions?

No, automated tools and agents using Limited keys receive a `403 owner_only` error when attempting live refunds. Live refunds must be initiated by the project owner in the console or via a full-access account key.

---

Published 2026-11-15 · https://thelastapi.dev/blog/refunds-disputes-explained
