Reason mapping

Every processor describes dispute reasons in its own words. Reason mapping translates those raw reason strings into DisputeDash’s internal categories, which decide what evidence is gathered and which rebuttal letter is used. Known reasons for every processor are pre-configured, so this usually runs automatically — you only step in when a brand-new reason appears.

Admin only

Reason mapping requires the Admin role.

When you need it

If a dispute arrives with a reason code DisputeDash has never seen, the case pauses at Unmapped and no evidence is gathered until the reason is mapped. You’ll see these on the Reason Mapping screen, flagged as needing attention.

📷 Screenshot

The Settings → Reason Mapping table showing processor, raw reason string, category dropdown, and stuck-case count. Replace this note with: ![Reason mapping table](/images/automation/reason-mapping.png)

Map a reason and clear stuck cases

1. Go to Settings → Reason Mapping.
2. Find the unmapped reason (each row shows the processor, the raw reason string, and how many cases are waiting on it).
3. Assign it to the correct reason category.
4. Select Resolve to release the waiting cases — they immediately start gathering evidence.

Mapping one reason clears every case waiting on that same reason at once.

Good to know

• Use Show all to review every mapping, not just the ones needing attention.
• Choosing the right category matters — it determines both the evidence gathered (evidence configuration) and the rebuttal letter used.
• A case stuck at Unmapped isn’t lost; it just waits. Map the reason before the reply-by deadline and it proceeds normally. See Case statuses.