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

# Transaction disputes

> File a dispute for a settled card transaction, choose a type and reason code, and follow the outcome.

File a dispute when a settled card charge should be reviewed. The transaction must belong to your business. Use the `id` from `GET /cards/transactions` or `GET /cards/{cardId}/transactions`, or the `transactionId` from a `card.transaction.*` webhook.

```bash title="POST /cards/transactions/TRANSACTION_ID/dispute" theme={null}
curl -s -X POST "https://b2b-api.easyonramp.com/api/v1/cards/transactions/TRANSACTION_ID/dispute" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "disputeType": "fraud",
    "disputeReasonCode": "otherFraudCardAbsent",
    "textEvidence": "Cardholder did not authorise this charge"
  }'
```

```json title="Response" theme={null}
{
  "id": "880e8400-e29b-41d4-a716-446655440099",
  "transactionId": "TRANSACTION_ID",
  "status": "pending",
  "disputeType": "fraud",
  "disputeReasonCode": "otherFraudCardAbsent",
  "textEvidence": "Cardholder did not authorise this charge",
  "disputeAmount": 4599,
  "currency": "usd",
  "createdAt": "2026-10-20T10:00:00.000Z"
}
```

The disputed amount is the full transaction amount, in cents. You do not send it. The response includes `disputeAmount` as the amount filed. Every dispute is submitted to the card network.

See [Create a dispute for a transaction](https://b2b-docs.easyonramp.com/api-reference/cards/create-a-dispute-for-a-transaction.md).

```bash title="GET /cards/transactions/TRANSACTION_ID/dispute" theme={null}
curl -s "https://b2b-api.easyonramp.com/api/v1/cards/transactions/TRANSACTION_ID/dispute" \
  -H "Authorization: Bearer YOUR_JWT"
```

This returns the dispute from the card issuer, including its current status. It returns `404` when the transaction has no dispute.

`GET /cards/transactions/{transactionId}` includes `issuerDispute` when a dispute was logged. That object is loaded from the card issuer and includes the current status. `GET /cards/transactions/{transactionId}/dispute` returns the same issuer dispute. See [Get the dispute for a transaction](https://b2b-docs.easyonramp.com/api-reference/cards/get-the-dispute-for-a-transaction.md).

One active dispute is allowed per transaction. A dispute is active while its status is `pending` or `inReview`. Filing another dispute in that window returns `409`.

## When a dispute can be filed

The transaction must be settled. That means status `completed` and a posted time. Pending, declined, and reversed transactions are rejected with `400`. A zero-amount transaction, such as an authorisation hold the merchant never captured, is also rejected with `400`.

## Filing window

Card networks expect a dispute within **120 days** of the transaction date. A shorter **75-day** window applies when either of these is true:

* The transaction was force-posted, meaning it settled without a prior authorisation.
* You file under `cardRecoveryBulletin`, `declinedAuthorization`, `noAuthorization`, or `invalidData`.

> [!WARNING]
>
> File as early as you can. A dispute submitted close to the 75-day or 120-day deadline has a higher chance of rejection. A late filing can be declined by the card network.

## Dispute type and reason code

`disputeType` is the broad category. `disputeReasonCode` is the finer reason code. It is optional. A reason code classifies the case more precisely and shortens review.

* Send only `disputeReasonCode` and the issuer derives `disputeType`.
* Send only `disputeType` and the dispute is filed with that type and no reason code.
* Send both and they must agree. When they disagree, the API returns `400` and names the expected type.
* An unsupported reason code returns `400`.
* The response includes `disputeReasonCode` when you sent one, and omits it when you did not.

### Dispute types

| `disputeType` | When to use it |
| - | - |
| `fraud` | The cardholder did not authorise the charge, or the card or its details were used without permission. This covers counterfeit cards and both card-present and card-absent fraud. |
| `creditNotProcessed` | The merchant agreed a refund or credit, and it never posted to the account. |
| `serviceNotReceived` | The cardholder paid for goods or a service that were never delivered. |
| `merchandiseIssue` | Goods or services arrived, and they were defective, counterfeit, or not what was described. |
| `other` | Processing errors and the remaining cases: a wrong amount, a duplicate charge, a cancelled recurring payment, a cancelled purchase, or cash that an ATM did not dispense. |

### Reason codes

| Reason code | What it means | Derived `disputeType` |
| - | - | - |
| `emvLiabilityShiftCounterfeitFraud` | Counterfeit fraud where the chip liability shift applies | `fraud` |
| `emvLiabilityShiftNonCounterfeitFraud` | Non-counterfeit fraud where the chip liability shift applies | `fraud` |
| `otherFraudCardPresent` | Other fraud while the card was present | `fraud` |
| `otherFraudCardAbsent` | Other fraud while the card was absent, including online and phone charges | `fraud` |
| `visaFraudMonitoringProgram` | Fraud monitoring programme | `fraud` |
| `cardRecoveryBulletin` | Card was listed on the card recovery bulletin. 75-day window. | `other` |
| `declinedAuthorization` | The authorisation was declined and the charge still posted. 75-day window. | `other` |
| `noAuthorization` | No authorisation, or the presentment was late. 75-day window. | `other` |
| `incorrectTransactionCode` | The transaction code was wrong | `other` |
| `incorrectCurrency` | The currency was wrong | `other` |
| `incorrectAccountNumber` | The account number was wrong | `other` |
| `incorrectAmount` | The amount was wrong | `other` |
| `duplicateProcessing` | The same charge was processed twice, or it was already paid another way | `other` |
| `invalidData` | The transaction data was invalid. 75-day window. | `other` |
| `merchandiseServicesNotReceived` | Merchandise or services were not received | `serviceNotReceived` |
| `cancelledRecurringTransaction` | A recurring charge continued after cancellation | `other` |
| `notAsDescribedOrDefective` | Goods or services were defective or not as described | `merchandiseIssue` |
| `counterfeitMerchandise` | The merchandise was counterfeit | `merchandiseIssue` |
| `misrepresentation` | The merchant misrepresented the purchase | `other` |
| `creditNotProcessed` | An agreed credit or refund was not processed | `creditNotProcessed` |
| `cancelledMerchandiseServices` | Merchandise or services were cancelled | `other` |
| `originalCreditTransactionNotAccepted` | An original credit was not accepted | `other` |
| `nonReceiptOfCashAtm` | An ATM did not dispense the cash | `other` |

`textEvidence` is optional written evidence, up to 65,535 characters.

## Thresholds and fees

You can submit a dispute of any amount. Reporting a dispute costs nothing, and small disputes still help track fraud patterns.

The card programme files a dispute with the card network only when the amount meets a minimum.

## Status and reimbursement

| Status | Meaning |
| - | - |
| `pending` | Filed and waiting for review |
| `inReview` | Under review. `reviewedBy` is `rain` while the card programme reviews it, then `network` once the card network is reviewing |
| `accepted` | The card network accepted the dispute. `reviewedBy` is `network` |
| `rejected` | The dispute was rejected. `reviewedBy` is `rain` or `network`, depending on who decided |
| `canceled` | The dispute was canceled |
| `resolvedByMerchant` | The merchant resolved it, for example with a refund |

`card.dispute.created` fires when the dispute is filed. `card.dispute.updated` fires when the status or `textEvidence` changes. Payload examples are in [Webhooks](https://b2b-docs.easyonramp.com/guides/webhooks.md).

When the network accepts the dispute, reimbursement is a new completed card transaction with a **negative amount** (a credit). You receive `card.transaction.completed` for that credit. The credit can be less than the transaction amount that was disputed. Network investigations typically take 30–60 business days.

## Unauthorized charges

When a user reports a charge they did not make:

1. Cancel the affected card. For a virtual card, [replace it](https://b2b-docs.easyonramp.com/guides/cards/replace-a-card.md). For a physical card, [delete it](https://b2b-docs.easyonramp.com/guides/cards/lifecycle-controls.md) and issue a new one.
2. File a dispute for the settled unauthorized transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.