> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Handle Disputes & Refunds
> Handle unauthorized transactions, disputes, refunds, chargebacks, pending payments, in-progress authorizations, and terminal declines.
## Filing a Dispute
You can only file disputes for transactions that:
* Have a `postedAt` timestamp (settled transactions). Pending or unsettled transactions cannot be disputed.
* Have a non-zero amount. Zero-amount transactions, such as authorization holds that were not captured, cannot be disputed.
If these requirements are not met, the API returns a `400 Bad Request` error.
### Card Network Deadline
Card networks (Visa, Mastercard) require disputes to be filed within **120 days** of the transaction date. After 120 days, the card network may decline the dispute.
Submit disputes as early as possible. Disputes filed close to the 120-day deadline have a higher risk of rejection.
To file a dispute, use Rain's [Dispute API](/reference/disputes/create-a-dispute-for-a-transaction).
### Dispute Reason Codes
When you file a dispute, you can optionally set a `disputeReasonCode` to classify it precisely using a Visa Claims Resolution (VCR) reason code. Reason codes give you finer-grained classification than the broad `disputeType` categories, which reduces back-and-forth during review.
The `disputeReasonCode` field is optional. Here is how it interacts with `disputeType` when you create a dispute:
* If you send only `disputeReasonCode`, Rain derives the `disputeType` from it automatically.
* If you send only `disputeType`, Rain files the dispute with that type and no reason code, exactly as before.
* If you send both, they must agree. If the reason code implies a different `disputeType` than the one you sent, the API returns a `400 Bad Request` naming the expected type.
* If you send a reason code that is not one of the supported values, the API returns a `400 Bad Request`.
Rain returns the reason code on the dispute wherever you read it, including the get, list, and update responses. The field is omitted when you file the dispute without one.
Each reason code maps to a coarse `disputeType`, as shown in the table below.
| Reason code | Visa VCR code | Description | Derived `disputeType` |
| -------------------------------------- | ------------- | ---------------------------------------------------- | --------------------- |
| `emvLiabilityShiftCounterfeitFraud` | 10.1 | EMV Liability Shift Counterfeit Fraud | `fraud` |
| `emvLiabilityShiftNonCounterfeitFraud` | 10.2 | EMV Liability Shift Non-Counterfeit Fraud | `fraud` |
| `otherFraudCardPresent` | 10.3 | Other Fraud – Card-Present Environment | `fraud` |
| `otherFraudCardAbsent` | 10.4 | Other Fraud – Card-Absent Environment | `fraud` |
| `visaFraudMonitoringProgram` | 10.5 | Visa Fraud Monitoring Program | `fraud` |
| `cardRecoveryBulletin` | 11.1 | Card Recovery Bulletin | `other` |
| `declinedAuthorization` | 11.2 | Declined Authorization | `other` |
| `noAuthorization` | 11.3 | No Authorization / Late Presentment | `other` |
| `incorrectTransactionCode` | 12.2 | Incorrect Transaction Code | `other` |
| `incorrectCurrency` | 12.3 | Incorrect Currency | `other` |
| `incorrectAccountNumber` | 12.4 | Incorrect Account Number | `other` |
| `incorrectAmount` | 12.5 | Incorrect Amount | `other` |
| `duplicateProcessing` | 12.6 | Duplicate Processing / Paid by Other Means | `other` |
| `invalidData` | 12.7 | Invalid Data | `other` |
| `merchandiseServicesNotReceived` | 13.1 | Merchandise / Services Not Received | `serviceNotReceived` |
| `cancelledRecurringTransaction` | 13.2 | Cancelled Recurring Transaction | `other` |
| `notAsDescribedOrDefective` | 13.3 | Not as Described or Defective Merchandise / Services | `merchandiseIssue` |
| `counterfeitMerchandise` | 13.4 | Counterfeit Merchandise | `merchandiseIssue` |
| `misrepresentation` | 13.5 | Misrepresentation | `other` |
| `creditNotProcessed` | 13.6 | Credit Not Processed | `creditNotProcessed` |
| `cancelledMerchandiseServices` | 13.7 | Cancelled Merchandise / Services | `other` |
| `originalCreditTransactionNotAccepted` | 13.8 | Original Credit Transaction Not Accepted | `other` |
| `nonReceiptOfCashAtm` | 13.9 | Non-Receipt of Cash at an ATM | `other` |
## Dispute Thresholds and Fees
Rain files a dispute with the card network only when the disputed amount meets a minimum threshold. Nothing changes in how or what you submit. Keep submitting every dispute regardless of size: reporting a dispute costs you nothing, and it helps Rain track fraud patterns even when a formal dispute is not filed.
The date you submit a dispute determines which threshold applies:
| Dispute submitted | Threshold and fee |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Before September 1, 2026 | Disputes of \$10 or under are not filed or reimbursed. |
| On or after September 1, 2026 | Disputes under \$30 are not filed or charged. The dispute fee applies to each dispute of \$30 or more escalated to the card network, regardless of the outcome. |
These thresholds are defined in your Master Services Agreement (MSA). Refer to your MSA for the full terms, and reach out to your account manager with any questions.
## Webhooks
Rain sends webhook notifications to track dispute lifecycle events in real-time. These webhooks are informational and do not require a response.
### `created`
**Dispute created webhook:**
Rain sends this webhook when you create a new dispute for a transaction.
See the [`dispute.created` webhook reference](/changelog/webhooks/v1/dispute/created) for the full payload schema, field descriptions, and version history.
### `updated`
**Dispute status update webhook:**
Rain triggers this webhook when a dispute's status changes or you change `textEvidence`.
Provides real-time updates on dispute resolution progress. Handle both status transitions and evidence updates in your webhook handler. See the [`dispute.updated` webhook reference](/changelog/webhooks/v1/dispute/updated) for the full payload schema, field descriptions, and version history.
**Possible status values**: `"pending"`, `"inReview"`, `"accepted"`, `"rejected"`, `"canceled"`, `"resolvedByMerchant"`
**Key fields:**
There are two different `id` fields. The one in the root is the `webhookId`, while the one in the `body` is the `disputeId`.
## Dispute Reimbursement Process
Rain automatically processes reimbursements when the card network accepts a dispute. Network investigations and chargebacks typically resolve within **30-60 business days**.
### Reimbursement timeline
1. Create a dispute using the [Dispute API](/reference/disputes/create-a-dispute-for-a-transaction)
2. Rain reviews the dispute (status: `"inReview"`)
3. If accepted (status: `"accepted"`), Rain processes the reimbursement
4. You receive a `transaction.completed` webhook for the credit transaction
5. Rain updates the cardholder balance with the credit amount
### What happens during reimbursement
When Rain processes an accepted dispute:
* Rain creates a new transaction with a **negative amount** (credit to the account)
* The credit amount matches the `disputeAmount` from the original dispute
* The transaction appears in transaction history as type `"spend"` with a negative amount
* Rain credits the cardholder account balance
* You receive a `transaction.completed` webhook for the credit
### Webhook notifications
You receive webhook notifications during the dispute lifecycle:
1. **`dispute.updated`** - Sent when the dispute status changes (including `"accepted"`, `"rejected"`, `"canceled"`, `"resolvedByMerchant"`, or `"inReview"`) and when `textEvidence` changes.
2. **`transaction.completed`** - Sent when Rain processes the reimbursement for an accepted dispute, includes the negative transaction amount
The `transaction.completed` webhook follows the same format as other transaction webhooks, with a negative `amount` field indicating a credit.
## Unauthorized transactions
When a user reports a transaction they didn't make:
1. Cancel the affected card immediately by setting its status to `canceled`.
2. [Issue a new card](/reference/cards/create-a-card-for-a-user) to the user.
3. [File a dispute](#filing-a-dispute) for the unauthorized transaction.
Rain's team manages the dispute through the card network from there.
## Pending and reversed transactions
A `pending` transaction is waiting for the merchant to finalize or cancel it. Most clear within days, but a transaction can stay pending for up to 30 business days; until it resolves, the funds are neither fully debited nor refunded.
* **Terminal declined, but funds are held.** Confirm with the merchant that the transaction was declined on their system. If the authorization was never finalized, the hold returns to the account automatically when the authorization expires.
* **No transaction ID for an attempted payment.** Rain never received the authorization request. Check with the merchant for issues on their side, and have the cardholder try another payment method if the problem persists.
* **A transaction reversed.** Reversals typically come from a merchant decline or a terminal error. If an expected reversal hasn't posted within 30 days, escalate to Rain support.
For refund timing, including canceled orders and merchant-declined refunds, see [Refund timing](/docs/handling-refunds#refund-timing).
## What's next
See the full webhook payload and field reference for every transaction event.
See the dispute lifecycle events and their trigger conditions.