Transaction disputes

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.

POST /cards/transactions/TRANSACTION_ID/dispute

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"
  }'

Response

{
  "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.

GET /cards/transactions/TRANSACTION_ID/dispute

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. 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.

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. 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:

Cancel the affected card. For a virtual card, replace it. For a physical card, delete it and issue a new one.
File a dispute for the settled unauthorized transaction.

Get started

Core concepts

Common workflows

How to manage users

How to fund your business wallet

How to use cards

How to use reports

Integration services

When a dispute can be filed

Filing window

Dispute type and reason code

Dispute types

Reason codes

Thresholds and fees

Status and reimbursement

Unauthorized charges

​When a dispute can be filed

​Filing window

​Dispute type and reason code

​Dispute types

​Reason codes

​Thresholds and fees

​Status and reimbursement

​Unauthorized charges

When a dispute can be filed

Filing window

Dispute type and reason code

Dispute types

Reason codes

Thresholds and fees

Status and reimbursement

Unauthorized charges