PayTo Disputes Guide
PayTo Disputes
Manage PayTo dispute cases end-to-end using Zepto’s Investigations API, from action requests through to final resolution.
Overview
When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action. You can then retrieve the dispute, identify the active action request, upload evidence where required, and accept or reject the case.
Core objects in the dispute lifecycle
Understanding the relationship between disputes, action requests, and webhooks is essential for a clean implementation.
Dispute
The investigation case raised after a bank initiates a PayTo dispute.
Action request
A required merchant action within the dispute, such as accepting or rejecting the case.
action_request_id
The identifier required when submitting a decision or uploading supporting evidence.
Webhooks
Real-time signals that keep your platform aligned with dispute and message events.
PayTo disputes process
This is the recommended merchant flow for handling dispute action requests in Zepto.
Receive the action request webhook
Zepto notifies your platform when a dispute requires merchant attention.
Fetch dispute details
Retrieve the latest dispute data so your team can review the current case state and identify the required next action.
Locate the active action request
Accept, reject, and upload actions all operate on the
action_request_id, not the dispute ID.
action_request_id.
Upload evidence when needed
Attach any supporting material such as proof of service, signed agreements, or refund confirmation before finalising the response.
Accept or reject the dispute
Submit the final merchant decision through the appropriate action endpoint.
Use when the dispute is valid and funds should be returned.
Use when the dispute is invalid and you have evidence to support the case.
Track investigation messages
Subscribe to message webhooks to maintain an audit trail and surface updates to internal teams.
Close the dispute internally
Once the final outcome is reflected in the dispute, reconcile the case and mark it closed in your internal systems.
Recommended pattern
Treat disputes as a stateful workflow. Use webhooks as the trigger,
persist both dispute_id and action_request_id,
and route decisions through an internal review process where required.
Simulate the incoming dispute workflow
Test your webhook handling, merchant review flow, and dispute resolution process in sandbox before going live.
Simulate incoming investigation message
Use this endpoint to trigger a sandbox dispute-style workflow and verify your end-to-end handling.
Visual process overview
This diagram shows the end-to-end PayTo disputes journey across the merchant, Zepto, and bank.
Updated about 1 hour ago