Your BusinessThe Contractor Codex

Refunds and disputes

Two ways money flows back to a client: refunds (you initiate) and disputes (the client's card issuer initiates a chargeback). They're handled differently. This page covers both.

Refunds

A refund is when you, the contractor, decide to return some or all of a payment to your client.

When to use a refund

  • The client paid an invoice you later realized was wrong (overbilled hours, wrong rate, duplicate charge).
  • The client cancelled the project after paying a deposit and you agreed to return it.
  • You're issuing a goodwill credit for something that went wrong.

How to issue a refund

  1. Open the client's workspace at /admin/clients/<id>.
  2. Find the paid invoice in the Payment History tab.
  3. Click Refund on the invoice row.
  4. Pick Full refund or Partial (enter the amount).
  5. Add an optional reason (shown internally; doesn't go to the client).
  6. Confirm.

The portal calls Stripe's refund API. The refund settles back to the client's original payment method (their card or bank) in 5–10 business days for cards, 7–10 for ACH.

What the client sees

Stripe sends the client an automatic refund-receipt email. The portal also shows the refund on:

  • The client's portal Pay page under the original invoice
  • Their dashboard Total Paid stat (decreases by the refund amount)

Partial refunds

You can refund less than the full invoice amount. The portal tracks amountRefundedCents against amountPaidCents and shows both on the invoice card.

You can issue multiple partial refunds against the same invoice as long as the total doesn't exceed what was paid.

Refunding a deposit invoice

If you're refunding a deposit because the client cancelled the project, also consider:

  • Voiding the balance draft invoice (if billing mode was deposit+draft).
  • Marking the project as cancelled/completed in the client's workspace.

The portal doesn't automatically do these — you decide what to do based on the cancellation circumstances.

Disputes (chargebacks)

A dispute is when a client's card issuer pulls money back from your account because the client reported the charge as unauthorized, didn't recognize it, or claims they didn't receive what they paid for.

What triggers a dispute

  • Client contacted their bank/card issuer claiming the charge was fraudulent.
  • Client disputes the quality of service ("never received what I paid for").
  • The card holder didn't actually authorize the charge (real fraud).

Disputes are out of your control to initiate or prevent — they come from the issuer side.

What happens when a dispute fires

  1. Stripe receives the dispute notification from the card network.
  2. Stripe holds the disputed amount + a fixed dispute fee from your balance.
  3. A Stripe webhook fires to the portal at /api/webhooks/stripe.
  4. The portal:
    • Marks the original invoice with a dispute badge.
    • Sends you an in-portal notification + email.
    • Logs the dispute to the activity history.

How to respond

You typically have 7–21 days to submit evidence to Stripe. The portal links you to the Stripe dispute page where you can:

  • Upload the signed contract, signed quote, project deliverables, communication history with the client, etc.
  • Submit a written response explaining the charge was valid.

Stripe forwards your evidence to the card network. The card network rules in 60–75 days. If they side with you, the funds are returned. If they side with the client, you lose the funds + the dispute fee permanently.

Dispute prevention

  • Always use the built-in signing flow or Docusign for contracts — a signed agreement is the strongest piece of evidence in a dispute.
  • Keep work logs — time tracking sessions with notes show the work was performed.
  • Use clear invoice descriptions so the charge is recognizable on the client's statement.
  • Respond fast to client complaints before they escalate to a dispute.

Where dispute records live

Dispute history is on:

Refund vs dispute — quick decision

If the client is asking you for their money back: refund. Issue it from the portal. Cheaper, fewer fees, no time pressure.

If the card issuer has already pulled the money: dispute. You can't refund retroactively — the dispute supersedes your refund options.

Don't refund a charge that's already been disputed — it creates an accounting mess. Wait for the dispute to resolve.