PayPal disputes can be managed in either your Braintree Control Panel or your PayPal Resolution Center. Action taken on either of these platforms will be reflected across the other – including any uploaded evidence against disputed transactions.

This article covers how to manage your PayPal disputes via the Braintree Control Panel. Learn more about how to manage this process via the PayPal Resolution Center in PayPal's documentation.


In order to manage your PayPal disputes via the Braintree Control Panel, you'll need to have a full PayPal integration with Braintree. If you're not already processing PayPal transactions through Braintree, head back to our PayPal Overview to get started.

Once you have added PayPal to your integration and linked your Braintree and PayPal accounts, you can then enable PayPal disputes in the Control Panel. In order to do so, your user's role must include the Add/Edit Processing Options role permission. To enable PayPal disputes:

  1. Log into the Control Panel
  2. Click on the gear icon in the top right corner
  3. Click Processing from the drop-down menu
  4. Scroll to the Payment Methods section
  5. Next to PayPal, click the Options link
  6. Check the box next to Manage PayPal Disputes in the Braintree Control Panel
  7. Click the Update button

Dispute stagesanchor

Disputed PayPal transactions have 3 stages:

  • Retrieval: The customer initiates a dispute through PayPal, and you have the opportunity to resolve the issue with the customer directly
  • Claim: The retrieval has been escalated, and PayPal will step in to investigate the case and determine the outcome
  • Chargeback: The customer disagrees with the outcome of the claim and escalates the dispute to their bank; PayPal is now a facilitator, and the customer's bank will determine the outcome


Once your customer initiates a retrieval, the disputed transaction amount will be placed on a temporary hold. If you or your customer escalate to PayPal, the retrieval will be closed out and a new PayPal dispute will be opened in your Braintree Control Panel.

Every dispute has a reply-by date listed in the Control Panel. At 12am on this date, you will lose the opportunity to take action. The time zone for your Control Panel – and this cutoff – was established during the Braintree application process; to view your current time zone settings, click on the gear icon in the top right corner, click Business from the drop-down menu, and scroll to the Time Zone section.

Once an outcome has been determined, PayPal will release the funds to the winning party.


PayPal's Seller Protection may affect the movement of money in the event of a dispute.


When one of your PayPal customers initiates a dispute, you’ll receive an email with instructions on how to proceed. By default, the first admin user created in your gateway will receive notifications, but this can be adjusted in the Control Panel.

Updating notification settingsanchor

To edit your notifications:

  1. Log into the Control Panel
  2. Click on the gear icon in the top right corner
  3. Click Processing from the drop-down menu
  4. Scroll to the Notifications section
  5. Next to Dispute Notifications, click the Options link

Here, you can adjust the frequency of the notifications and designate who receives them. Any merchant accounts that do not currently have a recipient designated will also be listed here; while not all merchant accounts will generate dispute notifications, we recommend that you assign notification recipients to all merchant accounts.

When designating recipients, you have two options – adding a User Recipient, or using the Email Address field.

User Recipientsanchor

The User Recipients field allows you to send notifications to existing users in the Control Panel. These recipients will receive notifications based on their role and any sub-merchants they are associated with (if applicable). If the user's permissions don’t allow them to see certain transactions, or they are not associated with a certain sub-merchant, they won’t receive dispute notifications for those transactions.

Email Addressanchor

The Email Address field allows you to send notifications to any email address, regardless of whether the email is associated with a user in the Control Panel. This can be particularly helpful if you use internal distribution lists to manage disputes (e.g. Emails entered in this field will receive all dispute notifications – even if the address corresponds to a user with limited permissions, they will still receive notifications for all disputes.

Dispute webhooksanchor

In addition to email notifications, you can set up webhooks to notify you if a dispute's status is updated to Open, Won, or Lost. For more information on setting up webhooks, see our webhooks guide.


How a PayPal dispute is initiated, and whether or not it is escalated to the customer's bank or credit card issuer, will determine which fees you incur.

Retrievals and claims initiated and resolved through PayPal or your Braintree gateway do not incur dispute fees. However, you will be subject to any fees assessed by the issuer or bank account provider if the dispute is escalated to a chargeback or the customer initiates a claim directly through the issuer or bank account provider.

Managing in the Braintree Control Panelanchor

You can locate your PayPal disputes in the Control Panel alongside your credit card disputes. If your credit card disputes are not currently managed in the Control Panel, then only your PayPal disputes will be listed here, and you will need to continue managing your credit card disputes through your normal workflow. Contact us with any questions.

We're currently rolling out some changes to our user interface for managing chargebacks, retrievals, and pre-arbs in the Control Panel.

If you recently received a notice that the Disputes section of your Control Panel has been updated, follow these steps to manage your disputes:

  1. Log into the Control Panel
  2. Click on Disputes in the navigation bar
  3. Click the filter button in the upper left corner of the disputes list page and select PayPal under Payment Instrument Type
  4. If you're looking for a specific case, include any relevant timeframe or parameters
  5. To view more information or take action on a dispute, click that dispute's row in the results list or the expand button on the far right side of the row. From this menu, select from the following options:
    • Submit Evidence: Go to the evidence submission page, where you can upload and submit evidence
    • Accept: Accept the dispute
    • View Transaction: Go to the transaction against which this dispute was raised
    • View Customer: View more information about the customer who raised this dispute
    • View Dispute: View further details about this dispute, including its event history

Otherwise, follow these steps:

  1. Log into the Control Panel
  2. Click on Disputes in the navigation bar
  3. Click the Search link located to the right of the Kind field at the top of the page
  4. Under Payment Instrument Type, keep only the PayPal box checked
  5. If you're looking for a specific case, include any relevant timeframe or parameters
  6. Click the Search button

The Case Number listed in the Braintree Control Panel corresponds to the PayPal Dispute ID in the PayPal Resolution Center.



In the PayPal Resolution Center, dispute stages are labeled as Dispute, Claim, and Chargeback. In order to keep your Braintree dispute experience consistent, we label the Dispute stage as Retrievals in your Braintree Control Panel.

With each retrieval, you have 3 options for action:

  • Message with the customer
  • Send or accept an offer
  • Escalate to PayPal

To take action on a retrieval, click the button under the Disputed Date column in the Control Panel. If there is a response waiting for you from a customer, the button will say Respond. Otherwise, the button should say View.

From there, you can view the retrieval details, send messages, view your message history, accept offers, extend counter offers, or escalate the retrieval to PayPal.

Escalating to PayPalanchor


In general, it's best to attempt to resolve retrievals with your customers directly; we only recommend escalating to PayPal as a final resort.

If a retrieval can't be resolved, either you or the customer can escalate the dispute to a claim – making PayPal the decider in the case. To escalate the retrieval yourself, click the Escalate to PayPal link in the Dispute Details section of the Braintree Control Panel. The original retrieval will be closed, a new dispute will be opened, and the two will be automatically linked together for your reference.


When you accept a claim or chargeback, the funds will be returned to the customer. Accepting a PayPal dispute indicates that you don’t wish to take any further action, but it doesn’t necessarily imply that you agree with the customer.

Merchants typically accept disputes if the transaction amount is minor enough that it doesn’t justify the work of submitting evidence, or if the transaction is known to be fraudulent.

To accept a PayPal dispute:

  1. Locate the dispute in the Control Panel
  2. Click the Accept button
  3. Confirm your acceptance by clicking the OK button

The status of the dispute will be updated to Accepted in the Control Panel, and the funds will be returned to the customer.


If you believe the transaction was legitimate, you can dispute the claim or chargeback:

  1. Locate the dispute in the Control Panel
  2. In the new user interface, click the Submit Evidence button, otherwise click the Dispute button
  3. Complete the evidence requirements
  4. Click the Submit Dispute button

Uploading evidenceanchor

Every dispute is different, so the evidence you provide will vary depending on the nature of the dispute and the documents you have available. The more thorough your evidence is, the better. Evidence includes, but is not limited to:

  • Tracking information from a shipment, particularly if a signature was obtained at the time of delivery
  • Documentation of the customer's agreement to terms of service that includes both the customer's name and email address
  • Emails or other correspondence with the customer that support your case
  • Evidence of refund or replacement of goods already sent to the customer


PayPal disputes in the Braintree Control Panel have the same statuses as your credit card disputes:

  • Open: The claim or chargeback has been issued and we are awaiting your response
  • Accepted: You have opted out of providing evidence for the case and the funds will be returned to the customer
  • Auto Accepted: The dispute has been automatically accepted for the best merchant experience
  • Disputed: Your case is under review and no action is needed at this time
  • Won: The case has been ruled in your favor and the funds will be released back to you
  • Lost: The case has been ruled in the customer's favor and the funds will be returned to them
  • Expired: The reply-by date to submit evidence has passed and you have forfeited your right to dispute the case – the funds will be returned back to the customer

A note on Disputed statusesanchor

For Braintree, cases with the Disputed status can mean one of two things:

  • Your evidence has been submitted and the case is being evaluated
  • The case is currently Under Review with PayPal with no evidence required

Cases listed as Under Review in the PayPal Resolution Center have not yet had evidence submitted, but show as Disputed in the Braintree Control Panel. In cases where PayPal deems that evidence is required, the case may change from Disputed back to Open. At that point, you would need to submit evidence and dispute the case.

Next Page: Funding and Reconciliation