Dispute

What this section covers

• Raise a dispute for a transaction with supporting files or notes.
• List disputes for internal operations or support teams.
• Display dispute status to merchants or finance staff.

Method mix

Prerequisites

• Capture the original transaction reference, merchant context, customer details, and dispute reason before starting the API flow.
• Define where supporting evidence files will be uploaded from and validate accepted file size and MIME types in advance.
• Align support, finance, and operations teams on the internal statuses they need to track while a dispute is open.

Implementation Checklist

• Persist dispute identifiers, related transaction references, and evidence metadata together.
• Validate upload rules before sending multipart evidence requests.
• Make every dispute update auditable so support teams can explain who changed what and when.

Success Signals

• Support teams can open a dispute from a known transaction record without manually re-entering core details.
• Evidence uploads and follow-up updates are traceable from one internal case or ticket view.
• Merchants can see a clear current dispute status instead of ambiguous support notes.

Common Pitfalls

• Starting a dispute flow without preserving the exact transaction reference and business reason that justified the case.
• Treating uploaded evidence as temporary UI state instead of storing durable references and audit history.
• Letting multiple operators overwrite dispute updates without an internal review or reconciliation trail.

Operational Notes

• Model disputes internally as cases with timeline entries so API calls, uploaded files, and operator notes remain linked.
• Add filters for open, resolved, and escalated disputes to reduce manual investigation work for support teams.
• Use webhook or scheduled polling strategies to keep internal dispute views aligned with Paymish status changes.