Disputes

Managing PayPal Disputes via the API

Availability

Managing disputes via the API is only available to merchants who can access disputes in the Braintree Control Panel.

Once a PayPal dispute is reflected in the Braintree gateway, managing it via the API is similar to managing a credit card dispute. You can use the same API calls to find or search for the dispute, check its status, and respond to it. You can also take advantage of webhooks to automate your workflow. The key difference with managing PayPal disputes via the API is the evidence you must provide. For PayPal disputes, you must declare an evidence type and submit additional categorized evidence using the optional arguments in the Dispute: Add Text Evidence call. To learn more about disputes in general, visit the Overview. For more information on the PayPal dispute process and how to manage them in the Control Panel, see our support articles.

Responding with evidence

Follow the steps below to manage a PayPal dispute via the API:

Specify an evidence type by using Dispute: Add Text Evidence and:
- Setting category to EVIDENCE_TYPE
- Setting content to PROOF_OF_FULFILLMENT , PROOF_OF_REFUND, or OTHER
Add any necessary text-based evidence using (Dispute: Add Text Evidence)[https://developer.paypal.com/braintree/docs/reference/request/dispute/add-text-evidence] and setting category to the appropriate values
Add any file-based evidence, like an image or PDF, by:
1. Uploading it to Braintree in a Document Upload: Create request
2. Attaching the uploaded file to the dispute using Dispute: Add File Evidence
Repeat as many times as necessary
Finalize the dispute using Dispute: Finalizebefore the reply-by date indicated in the dispute details

Once you've finalized the dispute, we'll send your response and evidence along for review.

Important

Braintree will not forward your response to the deciding party unless you have finalized it before the reply-by date passes.

Specifying an evidence type

For each dispute, you must choose one of three possible evidence types to categorize the evidence you're providing:

PROOF_OF_FULFILLMENT
PROOF_OF_REFUND
OTHER

You can use any processor-forwarded messages in the dispute details to figure out which is the best option, but keep in mind that some types require specific additional evidence. See the sections below for more details.

Proof of fulfillment evidence type

Use PROOF_OF_FULFILLMENT if you shipped the product to the customer, but the customer reported fraud or did not receive the product. When you specify this evidence type, you'll also need to include the following additional evidence:

CARRIER_NAME
TRACKING_NUMBER and/or TRACKING_URL

If you include more than one set of tracking information, be sure to assign a sequence_number to each set so Braintree can group the correct information together. sequence_number should be formatted as an integer.

PHP

$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'EVIDENCE_TYPE',
    'content' => 'PROOF_OF_FULFILLMENT'
  ]
);

$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'CARRIER_NAME',
    'content' => 'USPS',
    'sequenceNumber' => '1'
  ]
);

$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'TRACKING_NUMBER',
    'content' => 'a_tracking_number',
    'sequenceNumber' => '1'
  ]
);

$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'CARRIER_NAME',
    'content' => 'FEDEX',
    'sequenceNumber' => '2'
  ]
);

$result = $gateway->dispute()->addTextEvidence(
  "a_dispute_id",
  [
    'category' => 'TRACKING_URL',
    'content' => 'https://example.tracking.com/a_tracking_number',
    'sequenceNumber' => '2'
  ]
);

Proof of refund evidence type

Use PROOF_OF_REFUND if the transaction has already been refunded. When you specify this evidence type, you'll also need to include a REFUND_ID. You can provide either the Braintree Refund ID or the PayPal Refund ID. If there is more than one refund associated with the disputed transaction, add each one in a separate Dispute: Add Text Evidence request.

PHP

$result = $gateway->dispute()->addTextEvidence(
    "a_dispute_id",
    [
        'category' => 'EVIDENCE_TYPE',
        'content' => 'PROOF_OF_REFUND'
    ]
);

$result = $gateway->dispute()->addTextEvidence(
    "a_dispute_id",
    [
        'category' => 'REFUND_ID',
        'content' => 'a_refund_id'
    ]
);

Other evidence type

Use OTHER only if you don't have the required evidence for the other evidence types. When you specify this evidence type, all additional evidence categories are optional.

Note

While it's possible to use OTHER for all disputes, you can expect to win more disputes if you use PROOF_OF_FULFILLMENT and PROOF_OF_REFUND when possible.

PHP

$result = $gateway->dispute()->addTextEvidence(
    "a_dispute_id",
    [
        'category' => 'EVIDENCE_TYPE',
        'content' => 'OTHER'
    ]
);

Argument reference

Below are all the evidence types and categories you can use on Dispute: Add Text Evidence:

Arguments	Type	Description
`category`	string	The category that describes the `content` you're providing in this call. Possible values: `EVIDENCE_TYPE` `CARRIER_NAME` `TRACKING_URL` `TRACKING_NUMBER` `REFUND_ID`
`content`	string	The text-based content for the dispute evidence. When the category is set to `EVIDENCE_TYPE`, possible values are: `PROOF_OF_FULFILLMENT` `PROOF_OF_REFUND` `OTHER`
`sequence_number`	integer	The sequence number to identify groups of related evidence (e.g `CARRIER_NAME` and `TRACKING_NUMBER`).