Disputes

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`	A new dispute is opened.
`dispute.updated`	A dispute changes status or you update evidence.
`dispute.evidenceRequested`	Rain requests additional evidence for a dispute.
`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.

Webhook Rain sends youYour handler (ack 2xx)Action / API callCard networkConditional stepException (dispute)

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

Payload

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

Payload

{
    "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, 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:

A cardholder files a dispute on a transaction (status: "pending" or "inReview")
The merchant independently processes a refund for that transaction
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.

Payload

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

Payload

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

The card network accepts a dispute (status changes to "accepted")
Rain creates the reimbursement transaction
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 for the thresholds, effective dates, and fee details. When the reimbursement is processed, you will receive two webhooks:

dispute.chargebackCreated - Links the chargeback transaction directly to the dispute (see above)
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

Handle disputes & refunds

Walk through filing a dispute, the reimbursement process, and common questions.

Decline reasons

Look up what a declinedReason value means and what to do about it.

Overview

Compliance

Cards

Payments

Webhooks

Webhook Events

`dispute.created`

`dispute.updated`

Status values

Automatic resolution from merchant refunds

`dispute.evidenceRequested`

`dispute.chargebackCreated`

When is this webhook sent?

Dispute reimbursement

Identify reimbursement transactions

What’s next

Handle disputes & refunds

Decline reasons

​dispute.created

​dispute.updated

​Status values

​Automatic resolution from merchant refunds

​dispute.evidenceRequested

​dispute.chargebackCreated

​When is this webhook sent?

​Dispute reimbursement

​Identify reimbursement transactions

​What’s next

Handle disputes & refunds

Decline reasons

`dispute.created`

`dispute.updated`

Status values

Automatic resolution from merchant refunds

`dispute.evidenceRequested`

`dispute.chargebackCreated`

When is this webhook sent?

Dispute reimbursement

Identify reimbursement transactions

What’s next