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

# dispute.created

<Update label="v1.2.0" description="minor update">
  ### currency fields added

  | Field                  | Type                | Description                                                   |
  | ---------------------- | ------------------- | ------------------------------------------------------------- |
  | `currency`             | `string` (optional) | The dispute currency, lowercase ISO-4217 (for example, `usd`) |
  | `transaction.currency` | `string` (optional) | The disputed transaction's currency, lowercase ISO-4217       |
</Update>

<Update label="v1.1.0" description="Add disputeAmount field">
  ### v1.1.0 Changes

  Added the `disputeAmount` field to the webhook payload.

  #### New Fields

  | Field                | Type     | Description                                                                                                                                                                                                                                                                  |
  | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `body.disputeAmount` | `number` | Disputed amount in cents. Must be less than or equal to the transaction amount. When creating a dispute, this field is optional. If omitted, it defaults to the full transaction amount. Use this for partial disputes when you only want to dispute a portion of the total. |

  #### Example Payload

  ```json 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"
          }
      }
  }
  ```
</Update>

<Update label="v1.0.0" description="initial release">
  ### dispute.created webhook

  Added the `dispute.created` webhook. Rain triggers this webhook when you file a new dispute against a transaction.

  #### Payload Fields

  | Field                                  | Type                | Description                                        |
  | -------------------------------------- | ------------------- | -------------------------------------------------- |
  | `id`                                   | `string`            | Webhook ID                                         |
  | `resource`                             | `string`            | Always `"dispute"`                                 |
  | `action`                               | `string`            | Always `"created"`                                 |
  | `version`                              | `string`            | The webhook version                                |
  | `body.id`                              | `string`            | The dispute ID                                     |
  | `body.transactionId`                   | `string`            | The ID of the disputed transaction                 |
  | `body.status`                          | `string`            | Dispute status (see values below)                  |
  | `body.disputeType`                     | `string` (optional) | Type of dispute (see values below)                 |
  | `body.textEvidence`                    | `string` (optional) | Text evidence provided for the dispute             |
  | `body.createdAt`                       | `string`            | ISO 8601 timestamp of dispute creation             |
  | `body.updatedAt`                       | `string` (optional) | ISO 8601 timestamp of last update                  |
  | `body.resolvedAt`                      | `string` (optional) | ISO 8601 timestamp of resolution                   |
  | `body.transaction`                     | `object` (optional) | Details of the disputed transaction                |
  | `body.transaction.id`                  | `string`            | Transaction ID                                     |
  | `body.transaction.cardholderUserId`    | `string` (optional) | Cardholder's user ID                               |
  | `body.transaction.cardholderFirstName` | `string` (optional) | Cardholder's first name                            |
  | `body.transaction.cardholderLastName`  | `string` (optional) | Cardholder's last name                             |
  | `body.transaction.amount`              | `number`            | Transaction amount in USD cents                    |
  | `body.transaction.merchantName`        | `string` (optional) | Merchant name                                      |
  | `body.transaction.postedAt`            | `string` (optional) | ISO 8601 timestamp when the transaction was posted |

  #### Dispute Status Values

  | Status               | Description                                                      |
  | -------------------- | ---------------------------------------------------------------- |
  | `pending`            | Dispute has been submitted and is awaiting review                |
  | `inReview`           | Dispute is being reviewed                                        |
  | `accepted`           | Dispute was accepted in favor of the cardholder                  |
  | `rejected`           | Dispute was rejected                                             |
  | `canceled`           | Dispute was canceled                                             |
  | `resolvedByMerchant` | Dispute was resolved because the merchant issued a direct refund |

  #### Dispute Type Values

  | Type                 | Description                            |
  | -------------------- | -------------------------------------- |
  | `fraud`              | Unauthorized or fraudulent transaction |
  | `creditNotProcessed` | A credit/refund was not processed      |
  | `serviceNotReceived` | Service was not received               |
  | `merchandiseIssue`   | Issue with merchandise received        |
  | `other`              | Other dispute reason                   |

  #### Example Payload

  ```json theme={null}
  {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resource": "dispute",
      "action": "created",
      "version": "1.0.0",
      "body": {
          "id": "dispute_abc123",
          "transactionId": "txn_def456",
          "status": "pending",
          "disputeType": "fraud",
          "textEvidence": "I did not authorize this transaction",
          "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"
          }
      }
  }
  ```
</Update>