Handle Disputes & Refunds

​

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

​

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

See the dispute.created webhook reference for the full payload schema, field descriptions, and version history.

​

updated

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"

​

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