Listen for the CUSTOMER.DISPUTE.CREATED webhook event from PayPal; extract the dispute ID and the associated transaction ID from the event payload.
Call the Disputes API GET endpoint with the dispute ID to retrieve the full dispute details including the dispute reason, the disputed amount, and the response deadline.
Gather evidence relevant to the dispute reason: for item-not-received disputes, collect tracking numbers and delivery confirmation; for significantly-not-as-described disputes, collect product photos and policy documents.
Submit your evidence by calling the provide-evidence action endpoint on the dispute; attach files by uploading them as multipart form data and include a note explaining the evidence.
If you choose to accept the claim instead of contesting, call the accept-claim action endpoint; PayPal will process the refund.
Monitor the dispute status by polling the dispute GET endpoint or listening for CUSTOMER.DISPUTE.UPDATED webhooks until the status reaches RESOLVED.
Known gotchas
Response deadlines are strict; missing the deadline results in automatic resolution in the buyer's favor regardless of the merits of your evidence.
PayPal Disputes and Stripe disputes are separate from card network chargebacks; a buyer can file both a PayPal dispute and a credit card chargeback on the same transaction, requiring you to respond to two separate processes.
Evidence file size limits apply; compress images and documents before uploading to avoid rejection of your evidence submission.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp