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

This article covers how to manage your PayPal disputes via the Braintree Control Panel. For more detailed information on the PayPal disputes process via the PayPal Resolution Center, see this PayPal article.


In order to manage your PayPal disputes via the Braintree gateway, you'll need to have a full PayPal integration with Braintree. If you're not already processing PayPal transactions through Braintree, see our PayPal support articles for details and setup instructions.

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

  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 stages

With PayPal, disputes 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 a retrieval is initiated, 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 account was established during the application process; to see 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 the 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. See our PayPal article for more information.


When one of your PayPal customers initiates a dispute, you’ll receive an email from 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.

Any merchant accounts that do not currently have a recipient designated will be listed in the Control Panel as well. While not all merchant accounts will generate dispute notifications, we recommend that you assign notification recipients to as many merchant accounts as possible.

Updating notification settings

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

You can adjust the frequency of the notifications and designate who receives them. When designating recipients, you have two options – adding a User Recipient, or using the Email Address field.

User Recipients

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 their 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 Address

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 webhooks

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.


Fees for PayPal disputes are determined by the way the dispute was initiated, and whether or not it is escalated to the customer's bank or credit card issuer.

For retrievals and claims initiated and resolved through PayPal or your Braintree gateway, no dispute fees are assessed.

If your customer either initiates the dispute or escalates a claim through their credit card issuer or bank account provider, you will be subject to any fees that the issuer or bank account provider assess.

Managing in the Braintree Control Panel

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. You will need to continue managing your credit card disputes through your normal workflow. Contact us with any questions.

To locate your PayPal disputes:

  1. Log into the Control Panel
  2. Click on Transactions in the navigation bar
  3. Click on the Disputes tab
  4. Click the Search link located to the right of the Kind field at the top of the page
  5. Under Payment Instrument Type, keep only the PayPal box checked
  6. If you're looking for a specific case, include any relevant timeframe or parameters
  7. 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've labeled Dispute stage issues as Retrievals in your Control Panel.

In most cases, the easiest way to settle a dispute is for you to connect directly with your customer and work together to solve it. For retrievals, 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. 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 PayPal


In general, it's best to attempt to resolve retrievals with your customers directly; we only recommend escalating 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. The retrieval will be closed, and a new dispute will be opened in your Braintree Control Panel. The original retrieval will be linked to the new dispute 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's claim.

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. Click the Dispute button
  3. Complete the evidence requirements
  4. Click the Submit Dispute button

Uploading evidence

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
  • 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 statuses

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 →