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

# Reduce and Dispute Chargebacks with FraudEG Evidence

> Use FraudEG risk scores and transaction signals as evidence in chargeback disputes. Learn how to retrieve fraud evidence and automate dispute workflows.

A chargeback occurs when a cardholder disputes a transaction with their bank, forcing the payment processor to reverse the charge and, in most cases, hold the merchant liable. Winning a chargeback dispute requires evidence — proof that you took reasonable steps to verify the transaction and that the charge was legitimate. Because FraudEG scores every transaction before authorization, it produces an immutable, timestamped fraud evidence record for each payment: risk score, signals, device fingerprint, behavioral data, and the decision your system received. That record is your primary asset in any dispute.

## How FraudEG evidence helps in disputes

Every time you call `POST /v1/transactions/score`, FraudEG creates a permanent audit record tied to the returned `transaction_id`. This record captures the state of more than 50 fraud signals at the exact millisecond the scoring request was made — before your system touched the payment processor. The record cannot be altered after the fact, which makes it credible evidence that your fraud controls were active and functioning at the time of the disputed charge.

When you submit a chargeback response package to your payment processor or acquirer, include the `transaction_id` and the fraud evidence summary. Many processors accept API-generated fraud screening results as compelling evidence under Visa's dispute resolution program and Mastercard's chargeback guidelines.

## Retrieving a transaction's fraud evidence

Use the events endpoint to pull the full audit trail for any previously scored transaction. Pass the `transaction_id` as a query parameter.

<Steps>
  <Step title="Identify the disputed transaction">
    Retrieve the `transaction_id` from the order record in your system. If you stored it at time of scoring (as recommended), this lookup is immediate. If not, you can search your order database by amount, timestamp, and customer to locate the corresponding FraudEG `transaction_id`.
  </Step>

  <Step title="Call GET /v1/events to retrieve the evidence record">
    Query the events endpoint with the transaction ID. The response returns a chronological audit trail of every signal evaluated and every decision made for that transaction.

    ```bash cURL theme={null}
    curl -G https://api.fraudeg.com/v1/events \
      -H "Authorization: Bearer $FRAUDEG_API_KEY" \
      --data-urlencode "transaction_id=txn_4r8wq1zb"
    ```

    **Example response:**

    ```json theme={null}
    {
      "transaction_id": "txn_4r8wq1zb",
      "risk_score": 82,
      "decision": "challenge",
      "signals": ["new_device", "ip_reputation_medium_risk", "velocity_burst"],
      "device_fingerprint_id": "dfp_9zk1qp3r",
      "identity_verification_status": "verified",
      "ip_address": "203.0.113.42",
      "ip_country": "US",
      "created_at": "2024-11-14T10:23:00Z",
      "events": [
        {
          "type": "score_requested",
          "timestamp": "2024-11-14T10:23:00.041Z",
          "latency_ms": 74
        },
        {
          "type": "challenge_issued",
          "timestamp": "2024-11-14T10:23:01.220Z",
          "method": "3ds2"
        },
        {
          "type": "challenge_passed",
          "timestamp": "2024-11-14T10:23:47.803Z"
        }
      ]
    }
    ```
  </Step>

  <Step title="Export the evidence for your dispute package">
    Include the following fields in your chargeback response package. Most payment processors and acquirers accept these as supporting documentation:

    | Field                   | Dispute value                                                                    |
    | ----------------------- | -------------------------------------------------------------------------------- |
    | `transaction_id`        | Unique fraud screening record identifier                                         |
    | `risk_score`            | Numeric score at time of transaction (0–100)                                     |
    | `decision`              | `allow`, `challenge`, or `block` — the action your system was instructed to take |
    | `signals`               | List of fraud indicators present at the time of the transaction                  |
    | `device_fingerprint_id` | Persistent device identifier tied to the transaction                             |
    | `created_at`            | UTC timestamp proving fraud screening occurred before authorization              |
  </Step>

  <Step title="Create a case record in FraudEG">
    Log the dispute as a case in FraudEG using `POST /v1/cases`. This links the chargeback to the original fraud evidence record and keeps your dispute workflow in sync with your fraud data.

    ```bash cURL theme={null}
    curl -X POST https://api.fraudeg.com/v1/cases \
      -H "Authorization: Bearer $FRAUDEG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "transaction_id": "txn_4r8wq1zb",
        "type": "chargeback",
        "reason": "customer_dispute",
        "amount": 12999,
        "currency": "USD",
        "notes": "Cardholder claims unauthorized transaction. 3DS challenge was completed."
      }'
    ```
  </Step>
</Steps>

## Best practices for chargeback prevention

Reducing chargebacks starts before a dispute ever arrives. The following practices minimize your exposure:

**Use `challenge` decisions to shift liability.** When FraudEG returns `challenge` and you trigger 3D Secure authentication, liability for fraud-related chargebacks shifts from you to the card issuer upon successful 3DS completion. This is one of the most effective chargeback prevention strategies available to card-accepting merchants.

**Block high-risk transactions before authorization.** A `block` decision means FraudEG is highly confident the transaction is fraudulent. Acting on blocks prevents chargebacks by stopping the payment before it ever reaches your processor. Review your block rate regularly to ensure thresholds are calibrated correctly for your business.

**Score all transactions, not just suspicious ones.** Only transactions that have been through `POST /v1/transactions/score` have a fraud evidence record. If you selectively score transactions, you will have no evidence for the ones you skipped — even if they turn out to be legitimate disputes. Scoring every transaction ensures full evidential coverage.

**Enable webhook logging for a complete audit trail.** Subscribe to `transaction.flagged` and `transaction.blocked` events to maintain a secondary log of fraud decisions in your own systems. Cross-referencing your internal logs with FraudEG evidence strengthens your dispute response.

<Note>
  FraudEG retains fraud evidence records for **7 years by default**, which covers the evidence retention requirements of most payment networks and financial regulators. You can retrieve the full evidence record for any transaction within that window at any time using `GET /v1/events?transaction_id={txn_id}`. If your regulatory environment requires a different retention period, contact FraudEG support to configure a custom retention policy for your account.
</Note>

<Tip>
  Automate your dispute intake by using `POST /v1/cases` as soon as you receive a chargeback notification from your payment processor. Attach the `transaction_id` immediately so the case is linked to its evidence record before you build your response package. The `case.updated` webhook will notify you as case status changes, keeping your dispute queue synchronized with FraudEG automatically.
</Tip>