# Disputes & chargebacks

> [!CAUTION]
> **This feature is not yet available via the API.** The Fynex dashboard includes a disputes & chargebacks view, but it currently directs merchants to the manual support flow — there are no live API endpoints for dispute management today. For any active dispute or chargeback, contact your Fynex representative directly.

---

## What are disputes and chargebacks?

A **dispute** is raised when a cardholder questions a charge with their issuing bank. If the issuer sides with the cardholder, the charge is reversed — this is called a **chargeback**. A chargeback results in:

- The captured amount being returned to the cardholder.
- A chargeback fee charged to the merchant by the card scheme.
- A formal process in which you may submit evidence to contest the reversal.

Chargebacks have strict response deadlines (typically 7–30 days depending on the card scheme). Acting quickly with strong evidence is the most effective defence.

---

## Current state

The Fynex disputes surface is **under active development**. Today:

- The `/online-payments/disputes-and-chargebacks` dashboard page exists but is an informational/manual-support surface only.
- There is no `disputes` GraphQL query or REST endpoint available.
- There is no evidence-submission or lifecycle-management API.

**To handle a dispute now:** email or message your Fynex representative as soon as you are notified of a chargeback. Include the payment reference, order details, customer contact, and any supporting evidence you hold.

---

## What to prepare (before the API ships)

Even without an API, you can reduce chargeback risk and improve dispute outcomes by preserving the following data at payment time:

| Data point | How to capture it |
|------------|-------------------|
| Order details | Store item names, quantities, and amounts tied to the Fynex payment reference. |
| Customer email | Collect at checkout; include in your order record. |
| Customer IP address | Log from your server at the point the payment is submitted. |
| Device fingerprint | Forward the `X-Device-Fingerprint` header to Fynex at payment time — it is passed to the upstream processor for risk scoring and becomes available for dispute evidence. |
| Delivery / fulfilment proof | Keep shipping tracking numbers, download logs, or service-completion records linked to each order. |

---

## Planned API surface

When the disputes API ships, expect the following shape (subject to change):

```graphql
# Planned — not yet available
query disputes($limit: Int, $offset: Int) {
  disputes(limit: $limit, offset: $offset) {
    id
    status          # under_review | accepted | contested | won | lost
    amount
    currencyCode
    reason
    deadline
    genericPayment { id externalOrderRef }
    createdAt
  }
}

mutation submitDisputeEvidence($disputeId: ID!, $evidence: DisputeEvidenceInput!) {
  submitDisputeEvidence(disputeId: $disputeId, evidence: $evidence) {
    id
    status
  }
}
```

Planned lifecycle states:

| State | Meaning |
|-------|---------|
| `under_review` | Fynex has received the chargeback notification and is reviewing. |
| `accepted` | You have accepted the chargeback (amount returned to cardholder). |
| `contested` | Evidence submitted; awaiting card scheme ruling. |
| `won` | Card scheme ruled in your favour; funds retained. |
| `lost` | Card scheme ruled for the cardholder; funds reversed. |

---

## Interim resolution path

While the API is unavailable, a **full refund** is sometimes the fastest way to resolve a pre-chargeback dispute directly with the customer — it avoids chargeback fees and the scheme process entirely. See [Captures & Refunds](https://api.fynex.ai/payments-api/v2/docs#tag/captures-refunds) for how to issue a refund programmatically.

## See also

- **[Captures & Refunds](https://api.fynex.ai/payments-api/v2/docs#tag/captures-refunds)** — Issue partial or full refunds as an interim resolution before a chargeback escalates.
- **[Errors](https://api.fynex.ai/payments-api/v2/docs#tag/errors)** — Understand Fynex error shapes and status codes.
- **[Concepts](https://api.fynex.ai/payments-api/v2/docs#tag/concepts)** — Key domain concepts: GenericPayment, SellerAccount, operationalMode, and more.