Tools/
Disputes/
PayPal Disputes

Managing PayPal Disputes via the API

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 evidenceAnchorIcon

Follow the steps below to manage a PayPal dispute via the API:
  1. 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
  2. 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
  3. 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
  4. Repeat as many times as necessary
  5. 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.

Specifying an evidence typeAnchorIcon

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 typeAnchorIcon

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.
  1. Ruby
result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "EVIDENCE_TYPE",
  content: "PROOF_OF_FULFILLMENT"
)

result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "CARRIER_NAME",
  content: "USPS",
  sequence_number: "1"
)

result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "TRACKING_NUMBER",
  content: "a_tracking_number",
  sequence_number: "1"
)

result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "CARRIER_NAME",
  content: "FEDEX",
  sequence_number: "2"
)

result = gateway.dispute.add_text_evidence(
  "a_dispute_id",
  category: "TRACKING_URL",
  content: "https://example.tracking.com/a_tracking_number",
  sequence_number: "2"
)

Proof of refund evidence typeAnchorIcon

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.
  1. Ruby
result = gateway.dispute.add_text_evidence(
    "a_dispute_id",
    category: "EVIDENCE_TYPE",
    content: "PROOF_OF_REFUND"
);

result = gateway.dispute.add_text_evidence(
    "a_dispute_id",
    category: "REFUND_ID",
    content: "a_refund_id"
);

Other evidence typeAnchorIcon

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.
  1. Ruby
result = gateway.dispute.add_text_evidence(
    "a_dispute_id",
    category: "EVIDENCE_TYPE",
    content: "OTHER"
);

Argument referenceAnchorIcon

Below are all the evidence types and categories you can use on Dispute: Add Text Evidence:
ArgumentsTypeDescription
categorystring The category that describes the content you're providing in this call. Possible values:
  • EVIDENCE_TYPE
  • CARRIER_NAME
  • TRACKING_URL
  • TRACKING_NUMBER
  • REFUND_ID
contentstring 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_numberinteger The sequence number to identify groups of related evidence (e.g CARRIER_NAME and TRACKING_NUMBER).