> ## 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.
# Disputes
> Follow the dispute lifecycle: creation, status updates, evidence requests, and chargebacks.
Rain sends webhook notifications when disputes are created or updated. These webhooks work the same way for both consumer and corporate programs.
The following events are available:
| Event | Description |
| --------------------------------------------------------- | --------------------------------------------------------------------- |
| [`dispute.created`](#dispute-created) | A new dispute is opened. |
| [`dispute.updated`](#dispute-updated) | A dispute changes status or you update evidence. |
| [`dispute.evidenceRequested`](#dispute-evidencerequested) | Rain requests additional evidence for a dispute. |
| [`dispute.chargebackCreated`](#dispute-chargebackcreated) | Rain processes a chargeback after the card network accepts a dispute. |
A dispute is a back-and-forth with the card network. After it opens, you may need to submit evidence by a deadline, and the outcome can be a chargeback or a resolution.
## `dispute.created`
Rain sends this webhook immediately after you successfully create a dispute. You can only have one active dispute (pending or in-review) per transaction. This webhook is informational only and does not require a response.
```json Payload theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resource": "dispute",
"action": "created",
"version": "1.1.0",
"body": {
"id": "dispute_abc123",
"transactionId": "txn_def456",
"status": "pending",
"disputeType": "fraud",
"textEvidence": "I did not authorize this transaction",
"disputeAmount": 2500,
"createdAt": "2026-01-27T15:30:00.000Z",
"transaction": {
"id": "txn_def456",
"cardholderUserId": "user_789",
"cardholderFirstName": "John",
"cardholderLastName": "Doe",
"amount": 5000,
"merchantName": "UNKNOWN MERCHANT",
"postedAt": "2026-01-25T10:00:00.000Z"
}
}
}
```
| Field | Type | Description |
| --------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `id` | `string` | The dispute ID |
| `transactionId` | `string` | The ID of the disputed transaction |
| `status` | `string` | Dispute status. See [Status values](#status-values). |
| `disputeType` | `string` (optional) | Type of dispute. See the dispute types below. |
| `textEvidence` | `string` (optional) | Text evidence provided for the dispute |
| `disputeAmount` | `number` (optional) | The disputed amount in cents. Equals the full transaction amount unless a partial dispute was filed. |
| `createdAt` | `string` | ISO 8601 timestamp of dispute creation |
| `updatedAt` | `string` (optional) | ISO 8601 timestamp of last update |
| `resolvedAt` | `string` (optional) | ISO 8601 timestamp of resolution |
| `transaction` | `object` (optional) | Details of the disputed transaction |
| `transaction.id` | `string` | Transaction ID |
| `transaction.cardholderUserId` | `string` (optional) | Cardholder's user ID |
| `transaction.cardholderFirstName` | `string` (optional) | Cardholder's first name |
| `transaction.cardholderLastName` | `string` (optional) | Cardholder's last name |
| `transaction.amount` | `number` | Transaction amount in USD cents |
| `transaction.merchantName` | `string` (optional) | Merchant name |
| `transaction.postedAt` | `string` (optional) | ISO 8601 timestamp when the transaction was posted |
| `transaction.currency` | `string` (optional) | The transaction's currency, lowercase ISO-4217. Requires version `1.2.0` or later. |
| `currency` | `string` (optional) | The dispute currency, lowercase ISO-4217. Requires version `1.2.0` or later. |
The `disputeType` field can be one of these types:
| Type | Description |
| -------------------- | -------------------------------------- |
| `fraud` | Unauthorized or fraudulent transaction |
| `creditNotProcessed` | A credit or refund was not processed |
| `serviceNotReceived` | Service was not received |
| `merchandiseIssue` | Issue with merchandise received |
| `other` | Other dispute reason |
## `dispute.updated`
Rain sends this webhook whenever a dispute status changes or you update text evidence. This includes status changes to `"inReview"`, `"accepted"`, `"rejected"`, `"canceled"`, and `"resolvedByMerchant"`, as well as updates to text evidence. This webhook is informational only and does not require a response.
```json Payload theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resource": "dispute",
"action": "updated",
"version": "1.1.0",
"body": {
"id": "dispute_abc123",
"transactionId": "txn_def456",
"status": "accepted",
"disputeType": "fraud",
"textEvidence": "I did not authorize this transaction",
"disputeAmount": 2500,
"createdAt": "2026-01-27T15:30:00.000Z",
"updatedAt": "2026-02-03T09:00:00.000Z",
"resolvedAt": "2026-02-03T09:00:00.000Z",
"transaction": {
"id": "txn_def456",
"cardholderUserId": "user_789",
"cardholderFirstName": "John",
"cardholderLastName": "Doe",
"amount": 5000,
"merchantName": "UNKNOWN MERCHANT",
"postedAt": "2026-01-25T10:00:00.000Z"
}
}
}
```
The `dispute.updated` payload uses the same dispute object as [`dispute.created`](#dispute-created), plus one field of its own. Rain populates the `resolvedAt` timestamp when the status is `accepted`, `rejected`, `canceled`, or `resolvedByMerchant`.
| Field | Type | Description |
| ------------ | ------------------- | --------------------------------------------------------------------------------- |
| `reviewedBy` | `string` (optional) | Who resolved the dispute: `rain` or `network`. Requires version `1.3.0` or later. |
### Status values
The `status` field can be one of the following:
| Status | Description |
| -------------------- | ---------------------------------------------------------------- |
| `pending` | Dispute has been created and is awaiting review |
| `inReview` | Dispute is being reviewed |
| `accepted` | Dispute was accepted |
| `rejected` | Dispute was rejected |
| `canceled` | Dispute was canceled |
| `resolvedByMerchant` | Dispute was resolved because the merchant issued a direct refund |
## Automatic resolution from merchant refunds
When a merchant issues a refund on a transaction with an active dispute, Rain automatically resolves the dispute with status `"resolvedByMerchant"`. This occurs when:
1. A cardholder files a dispute on a transaction (status: `"pending"` or `"inReview"`)
2. The merchant independently processes a refund for that transaction
3. Rain detects the merchant refund settlement
When Rain detects the refund:
* The dispute status changes to `"resolvedByMerchant"`
* The credit to the cardholder equals the merchant refund amount
* Rain populates the `resolvedAt` timestamp
* You receive a `dispute.updated` webhook with the new status
* Rain credits the cardholder account with the refund amount
This status is distinct from other terminal states:
* `"accepted"` - Dispute was won through the card network dispute process
* `"rejected"` - Dispute was denied through the card network dispute process
* `"canceled"` - Dispute was withdrawn or invalidated
* `"resolvedByMerchant"` - Dispute was automatically resolved because the merchant issued a direct refund
When a dispute is resolved by merchant refund, you do not receive a `dispute.chargebackCreated` webhook because the credit comes from the merchant refund settlement, not from a chargeback process.
## `dispute.evidenceRequested`
Rain may request additional documentation to process a dispute. When this happens, you receive the `dispute.evidenceRequested` webhook. Check the `message` field to see what evidence is needed, then prompt the cardholder to submit it.
Rain does not currently emit this event; evidence requests reach you through your Rain contact instead. The schema below is reserved so you can build the handler ahead of time.
```json Payload theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resource": "dispute",
"action": "evidenceRequested",
"version": "1.0.0",
"body": {
"id": "dispute_abc123",
"transactionId": "txn_def456",
"message": "Please provide receipt for the disputed transaction"
}
}
```
| Field | Type | Description |
| --------------- | -------- | -------------------------------------------------------- |
| `id` | `string` | The dispute ID |
| `transactionId` | `string` | The ID of the disputed transaction |
| `message` | `string` | The message from Rain describing what evidence is needed |
## `dispute.chargebackCreated`
Rain sends this webhook after the card network accepts a dispute and Rain processes the reimbursement. It lets you directly link the chargeback transaction back to the original dispute without having to match amounts and timing. This webhook is informational only and does not require a response.
```json Payload theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resource": "dispute",
"action": "chargebackCreated",
"version": "1.0.0",
"body": {
"id": "dispute_abc123",
"disputeId": "dispute_abc123",
"transactionId": "txn_chargeback_xyz789",
"originalTransactionId": "txn_original_def456",
"amount": -2500,
"originalTransactionAmount": 5000
},
"eventReceivedAt": "2026-02-18T12:00:00.000Z"
}
```
| Field | Type | Description |
| --------------------------- | ------------------- | ------------------------------------------------------------------------------- |
| `id` | `string` | The dispute ID |
| `disputeId` | `string` | The dispute ID |
| `transactionId` | `string` | The ID of the new chargeback transaction |
| `originalTransactionId` | `string` | The ID of the original disputed transaction |
| `amount` | `number` | Chargeback amount in USD cents (always negative) |
| `originalTransactionAmount` | `number` | Original transaction amount in USD cents |
| `currency` | `string` (optional) | The chargeback currency, lowercase ISO-4217. Requires version `1.1.0` or later. |
| `eventReceivedAt` | `string` (optional) | ISO 8601 timestamp of when Rain received the event |
### When is this webhook sent?
Rain sends the `dispute.chargebackCreated` webhook after:
1. The card network accepts a dispute (status changes to `"accepted"`)
2. Rain creates the reimbursement transaction
3. Rain credits the account
You will also receive a `transaction.completed` webhook for the chargeback transaction. The `dispute.chargebackCreated` webhook provides the explicit link between the chargeback and the dispute.
## Dispute reimbursement
After the card network accepts a dispute (`status` changes to `"accepted"`), Rain automatically processes the reimbursement and credits the account.
Rain files and reimburses only disputes that meet the minimum dispute amount. See [Dispute Thresholds and Fees](/docs/transaction-issues-disputes#dispute-thresholds-and-fees) for the thresholds, effective dates, and fee details.
When the reimbursement is processed, you will receive two webhooks:
1. **`dispute.chargebackCreated`** - Links the chargeback transaction directly to the dispute (see above)
2. **`transaction.completed`** - Standard transaction webhook for the chargeback transaction
The chargeback transaction has:
* Negative transaction amount (credit to the account)
* Amount matches the credit issued for the dispute
* Transaction appears in your transaction history
* Account balance updated to reflect the credit
### Identify reimbursement transactions
You can identify reimbursement transactions by:
* The `dispute.chargebackCreated` webhook, which provides the `transactionId` linked to the `disputeId`
* Negative transaction amount (credit)
* Transaction type of `"spend"`
Use the `dispute.chargebackCreated` webhook for the most reliable way to link chargeback transactions back to disputes.
## What's next
Walk through filing a dispute, the reimbursement process, and common questions.
Look up what a `declinedReason` value means and what to do about it.