> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugins/ pages for correct interfaces and manifests.
> Canonical locations: API auth = /api/authentication, webhook verification = /api/webhooks, rate limits = /resources/rate-limiting, transaction statuses = /fundamentals/payment-flow.
> The documentation uses the Diataxis framework: Tutorials (learning), How-to (tasks), Reference (lookup), Explanation (understanding).

# Disputes

> Track chargebacks and disputes through their full lifecycle, respond with evidence, and understand the financial impact of dispute outcomes.

A dispute (also called a chargeback) occurs when a customer contacts their bank or card issuer to reverse a completed payment. OwnPay tracks each dispute through its full lifecycle and records the financial impact on your ledger.

## Dispute lifecycle

<Mermaid
  chart={`
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#0F97ED','primaryTextColor':'#ffffff','primaryBorderColor':'#102963','lineColor':'#102963','secondaryColor':'#E8F4FD','tertiaryColor':'#F0F7FF','noteBkgColor':'#E8F4FD','noteTextColor':'#102963','noteBorderColor':'#0F97ED'}}}%%
stateDiagram-v2
[*] --> Open: Chargeback received
Open --> Under_Review: Evidence requested
Under_Review --> Won: Dispute resolved in your favor
Under_Review --> Lost: Dispute resolved against you
Under_Review --> Closed: Customer withdrew
Won --> [*]
Lost --> [*]
Closed --> [*]
`}
/>

## Viewing disputes

Navigate to **Reports > Disputes**. The table lists all disputes with these columns:

| Column             | Description                                |
| ------------------ | ------------------------------------------ |
| **Transaction ID** | The original payment that was disputed     |
| **Amount**         | The disputed amount                        |
| **Status**         | Open, Under Review, Won, Lost, or Closed   |
| **Deadline**       | The date by which you must submit evidence |
| **Reason**         | The customer's stated dispute reason       |
| **Gateway**        | The payment gateway handling the dispute   |

## Responding to a dispute

<Steps>
  <Step>
    Click the dispute row to open its detail view.
  </Step>

  <Step>
    Review the customer's dispute reason and the original transaction details.
  </Step>

  <Step>
    Under the **Evidence** section, upload supporting documents - delivery receipts, service logs, communication records, or any proof of fulfillment.
  </Step>

  <Step>
    Add internal **notes** for your team. These notes are private and not sent to the bank.
  </Step>

  <Step>
    Click **Submit Response** before the deadline expires.
  </Step>
</Steps>

<Warning>
  Missing a dispute deadline almost always results in an automatic loss. Set up [webhook notifications](/docs/notifications/webhooks) for the `dispute.opened` event so your team is alerted immediately.
</Warning>

## Dispute outcomes

<Columns>
  <Column>
    ### Won

    * Disputed amount is returned to your ledger balance
    * No additional fee from the gateway (varies by provider)
    * Transaction status reverts to completed
  </Column>

  <Column>
    ### Lost

    * Disputed amount is debited from your ledger
    * A **dispute fee** (charged by the card network) is also debited
    * The transaction is permanently marked as disputed
  </Column>
</Columns>

## Prevention best practices

* Use clear payment descriptors so customers recognize charges on their statements
* Provide order confirmations and delivery receipts proactively
* Respond to customer inquiries before they escalate to chargebacks
* Keep detailed records of every transaction accessible for evidence submission

## Related Pages

* [Transactions](/docs/payments/transactions) - View the original payment behind a dispute
* [Refunds](/docs/payments/refunds) - Issue refunds proactively to avoid disputes
* [Audit Log](/docs/reports/audit-log) - Track all dispute-related actions by staff
* [Webhooks](/docs/notifications/webhooks) - Set up real-time dispute alerts


## Related topics

- [Features and Capabilities](/docs/resources/features.md)
- [Webhooks](/docs/notifications/webhooks.md)
- [Audit Log](/docs/reports/audit-log.md)
- [Event System](/docs/developer/plugins/events.md)
- [Glossary](/docs/resources/glossary.md)