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.

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 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 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
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 to the user.
3. File 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.

What’s next

Transaction events

See the full webhook payload and field reference for every transaction event.

Disputes

See the dispute lifecycle events and their trigger conditions.