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. Navigate to Settings > Processing
  3. Next to PayPal, click Options
  4. Check the box next to Manage PayPal Disputes in the Braintree Control Panel
  5. Click Update

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, navigate to Account > Merchant Account Info > Time Zone.

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. Navigate to Settings > Processing > Dispute Notifications
  3. Click Options

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. Under Transactions, click Disputes
  3. Click Search next to the Kind field
  4. Under Payment Instrument Type, keep only PayPal checked
  5. If you're looking for a specific case, include any relevant timeframe or parameters
  6. Click Search

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 Accept
  3. Confirm your acceptance by clicking OK

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

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 evidence has been submitted and the case is being evaluated
  • 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

Next Page: Funding and Reconciliation →

Still have questions?

If you can’t find an answer, contact us