Disputes (1)

Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can create a dispute with PayPal. PayPal merchants, partners, and external developers can use the PayPal Disputes API to manage customer disputes.

Note: In the live environment, merchants cannot create disputes but can only respond to customer-created disputes. However, merchants can create disputes in the sandbox environment. When you create an app, enable Disputes in the App feature options section.
A customer can also ask his or her bank or credit card company to dispute and reverse a charge, which is known as a chargeback. For more information, see Disputes, claims, chargebacks, and bank reversals.

When a customer disputes a charge, you can use this API to provide evidence that the charge is legitimate. To provide evidence or appeal a dispute, you submit a proof of delivery or proof of refund document or notes, which can include logs.

Normally, an agent at PayPal creates a dispute, updates the dispute status, and settles disputes, but now you can run test cases in the sandbox that complete these operations.

Important: The create, cancel, compute metrics, change reason, and validate eligibility methods are available as a limited-release solution at this time. For more information, reach out to your PayPal account manager.

For details, see Disputes Overview documentation.

Acknowledge returned item

post/v1/customer/disputes/{id}/acknowledge-return-item

Acknowledges that the customer returned an item for a dispute, by ID. A merchant can make this request for disputes with the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED reason. Allowed acknowledgement_type values for the request is available in dispute details allowed response options object. For constraints and rules regarding documents, see documents.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to acknowledge the return of disputed item.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
acknowledgement_document
string <binary>

A file with evidence.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/acknowledge-return-item \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-d '{
  "note": "I have received the item back.",
  "acknowledgement_type": "ITEM_RECEIVED"
}'
Response samples
application/json
{}

Provide evidence

post/v1/customer/disputes/{id}/provide-evidence

Provides evidence for a dispute, by ID. A merchant can provide evidence for disputes with the WAITING_FOR_SELLER_RESPONSE status while customers can provide evidence for disputes with the WAITING_FOR_BUYER_RESPONSE status. Evidence can be a proof of delivery or proof of refund document or notes, which can include logs. A proof of delivery document includes a tracking number while a proof of refund document includes a refund ID. For other evidence type, notes and documents can be given. Evidences requested from you can be found by checking the type of evidence for the corresponding source under the evidence section of the show dispute details response. The source will be REQUESTED_FROM_SELLER for evidences requested from the merchant while it will be REQUESTED_FROM_BUYER for evidences requested from the customer. For constraints and rules regarding documents, see documents.
To make this request, specify the evidence in the JSON request body and use the provide-evidence link in the HATEOAS links of the show dispute details response. In case the link is not present in the response, you can't provide evidence for the dispute. For information about dispute reasons, see dispute reasons.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to submit evidence.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
evidence-file
string <binary>

A file with evidence.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-evidence \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-H 'Content-Type: multipart/related; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'  \
-F 'input={"evidences":[{"evidence_type":"PROOF_OF_FULFILLMENT","evidence_info":{"tracking_info":[{"carrier_name":"FEDEX","tracking_number":"122533485"}]},"notes":"Test"}]};type=application/json'\
-F 'file1=@NewDoc.pdf'
Response samples
application/json
{}

Show dispute details

get/v1/customer/disputes/{id}

Shows details for a dispute, by ID.

Note: The fields that appear in the response depend on the access. For example, if the merchant requests shows dispute details, the customer's email ID does not appear.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to show details.

header Parameters
Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows dispute details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-4012 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK'
Response samples
application/json
{
  • "dispute_id": "PP-D-4012",
  • "create_time": "2019-04-11T04:18:00.000Z",
  • "update_time": "2019-04-21T04:19:08.000Z",
  • "disputed_transactions": [
    • {
      • "seller_transaction_id": "3BC38643YC807283D",
      • "create_time": "2019-04-11T04:16:58.000Z",
      • "transaction_status": "REVERSED",
      • "gross_amount": {
        • "currency_code": "USD",
        • "value": "192.00"
        },
      • "buyer": {
        • "name": "Lupe Justin"
        },
      • "seller": {
        • "email": "merchant@example.com",
        • "merchant_id": "5U29WL78XSAEL",
        • "name": "Lesley Paul"
        }
      }
    ],
  • "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
  • "status": "RESOLVED",
  • "dispute_amount": {
    • "currency_code": "USD",
    • "value": "96.00"
    },
  • "dispute_outcome": {
    • "outcome_code": "RESOLVED_BUYER_FAVOUR",
    • "amount_refunded": {
      • "currency_code": "USD",
      • "value": "96.00"
      }
    },
  • "dispute_life_cycle_stage": "CHARGEBACK",
  • "dispute_channel": "INTERNAL",
  • "messages": [],
  • "extensions": {
    • "merchandize_dispute_properties": {
      • "issue_type": "SERVICE",
      • "service_details": {}
      }
    },
  • "offer": {
    • "buyer_requested_amount": {
      • "currency_code": "USD",
      • "value": "96.00"
      },
    • "offer_type": "REFUND",
    • "history": {
      • "offer_time": "2019-04-29T07:04:54.000Z",
      • "actor": "SELLER",
      • "event_type": "PROPOSED",
      • "offer_type": "REFUND",
      • "offer_amount": {
        • "currency_code": "USD",
        • "value": "96.00"
        },
      • "notes": "Full refund offer.",
      • "dispute_life_cycle_stage": "CHARGEBACK"
      }
    },
  • "links": []
}

Partially update dispute

patch/v1/customer/disputes/{id}

Partially updates a dispute, by ID. Seller can update the communication_detail value or The partner can add the partner action information.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to update the communication detail or add the partner action.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
Array
op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

The JSON Pointer to the target document location at which to complete the operation.

value
object (Patch Value)

The value to apply. The remove operation does not require a value.

from
string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
[
  • {
    • "op": "add",
    • "path": "/partner_actions/-",
    • "value": {
      • "id": "AMX-22345",
      • "name": "ACCEPT_DISPUTE",
      • "create_time": "2018-01-12T10:41:35.000Z",
      • "status": "PENDING"
      }
    }
]

List disputes

get/v1/customer/disputes

Lists disputes with a summary set of details, which shows the dispute_id, reason, status, dispute_state, dispute_life_cycle_stage, dispute_channel, dispute_amount, create_time and update_time fields.

To filter the disputes in the response, specify one or more optional query parameters. To limit the number of disputes in the response, specify the page_size query parameter.

To list multiple disputes, set these query parameters in the request:

  • page_size=2
  • start_time instead of disputed_transaction_id

If the response contains more than two disputes, it lists two disputes and includes a HATEOAS link to the next page of results.

SecurityOauth2
Request
query Parameters
start_time
string [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
Default: "Current date and time"

Filters the disputes in the response by a creation date and time. The start time must be within the last 180 days. Value is in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

You can specify either but not both the start_time and disputed_transaction_id query parameters.

disputed_transaction_id
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Filters the disputes in the response by a transaction, by ID.

You can specify either but not both the start_time and disputed_transaction_id query parameter.

page_size
integer [ 1 .. 50 ]
Default: 10

Limits the number of disputes in the response to this value.

next_page_token
string [ 1 .. 255 ] characters ^[A-Za-z0-9+\/=]+$
Default: "The first page of data"

The token that describes the next page of results to fetch. The list disputes call returns this token in the HATEOAS links in the response.

dispute_state
string [ 1 .. 2000 ] characters ^[0-9A-Z_]+$

Filters the disputes in the response by a state. Separate multiple values with a comma (,). When you specify more than one dispute_state, the response lists disputes that belong to any of the specified dispute_state.

update_time_before
string <ppaas_date_time_v3> [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ. update_time_before must be within the last 180 days and the default is the current time.

update_time_after
string <ppaas_date_time_v3> [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ. update_time_after must be within the last 180 days and the default is the maximum time (180 days) supported.

header Parameters
Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists disputes with a full or summary set of details. Default is a summary set of details, which shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields for each dispute.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK'
Response samples
application/json
{}

Provide supporting information for dispute

post/v1/customer/disputes/{id}/provide-supporting-info

Provides supporting information for a dispute, by ID. A merchant or buyer can make this request for disputes if they find the provide-supporting-info link in the HATEOAS links in the list disputes response. The party can provide the supporting information to PayPal to defend themselves only when the dispute_life_cycle_stage is CHARGEBACK, PRE_ARBITRATION, or ARBITRATION. They can provide a note that describes their part with details or upload any supporting documents to support their side. For constraints and rules regarding documents, see documents.
To make this request, specify the dispute ID in the URI and specify the notes in the JSON request body. This method differs from the provide evidence method which supports only multipart request, where PayPal asks the concerned party for evidence.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to provide the supporting information.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
supporting document
string <binary>

A file with evidence.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-supporting-info \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-H 'Content-Type: application/json' \
-d '{
  "notes": "Sample notes"
}'
Response samples
application/json
{}

Make offer to resolve dispute

post/v1/customer/disputes/{id}/make-offer

Makes an offer to the other party to resolve a dispute, by ID. To make this call, the stage in the dispute lifecycle must be INQUIRY. If the customer accepts the offer, PayPal automatically makes a refund. Allowed offer_type values for the request is available in dispute details allowed response options object.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to make an offer.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
note
required
string [ 1 .. 2000 ] characters

The merchant's notes about the offer.

invoice_id
string [ 1 .. 127 ] characters ^[A-Za-z0-9:\-|]+$

The merchant-provided ID of the invoice for the refund. This optional value maps the refund to an invoice ID in the merchant's system.

object (Money)

The amount proposed to resolve the dispute.

object (Portable Postal Address (Medium-Grained))

The return address for the item. Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason, especially if the refund amount is less than the dispute amount.

offer_type
required
string (offer_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The merchant-proposed offer type for the dispute.

Enum: Description
REFUND

The merchant must refund the customer without any item replacement or return. This offer type is valid in the inquiry phase and occurs when a merchant is willing to refund a specific amount. Buyer acceptance is needed for partial refund offers and dispute is auto closed for full refunds. Include the offer_amount but omit the return_shipping_address parameters from the make offer request.

REFUND_WITH_RETURN

The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the inquiry phase and occurs when a merchant is willing to refund a specific amount and requires the customer to return the item. Include the return_shipping_address parameter and the offer_amount parameter in the make offer request.

REFUND_WITH_REPLACEMENT

The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer request.

REPLACEMENT_WITHOUT_REFUND

The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer request.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "note": "Offer refund with replacement item.",
  • "offer_type": "REFUND_WITH_REPLACEMENT",
  • "offer_amount": {
    • "currency_code": "USD",
    • "value": "23"
    }
}
Response samples
application/json
{}

Escalate dispute to claim

post/v1/customer/disputes/{id}/escalate

Escalates the dispute, by ID, to a PayPal claim. To make this call, the stage in the dispute lifecycle must be INQUIRY.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute to escalate to a claim.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
note
required
string [ 1 .. 2000 ] characters

The notes about the escalation of the dispute to a claim.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "note": "Escalating to PayPal claim for resolution."
}
Response samples
application/json
{}

Accept offer to resolve dispute

post/v1/customer/disputes/{id}/accept-offer

The customer accepts the offer from merchant to resolve a dispute, by ID. PayPal automatically refunds the amount proposed by merchant to the customer.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to accept an offer.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
note
string [ 1 .. 2000 ] characters

The customer notes about accepting of offer. PayPal can but the merchant cannot view these notes.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "note": "I am ok with the refund offered."
}
Response samples
application/json
{}

Accept claim

post/v1/customer/disputes/{id}/accept-claim

Accepts liability for a claim, by ID. When you accept liability for a claim, the dispute closes in the customer’s favor and PayPal automatically refunds money to the customer from the merchant's account. Allowed accept_claim_type values for the request is available in dispute details allowed response options object.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to accept a claim.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
accept-claim-document
string <binary>

A file with evidence.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/accept-claim \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-d '{
  "note": "Full refund to the customer."
}'
Response samples
application/json
{}

Update dispute status

post/v1/customer/disputes/{id}/require-evidence
Important: This method is for sandbox use only.
Updates the status of a dispute, by ID, from UNDER_REVIEW to either:
  • WAITING_FOR_BUYER_RESPONSE
  • WAITING_FOR_SELLER_RESPONSE
This status change enables either the customer or merchant to submit evidence for the dispute. To make this call, the dispute status must be UNDER_REVIEW and require-evidence link should be available in the HATEOAS links of the show dispute details response. Specify an action value in the JSON request body to indicate whether the status change enables the customer or merchant to submit evidence:
If action isThe status updates to
BUYER_EVIDENCE WAITING_FOR_BUYER_RESPONSE
SELLER_EVIDENCE WAITING_FOR_SELLER_RESPONSE
.
SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute that requires evidence.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
action
required
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The action. Indicates whether the state change enables the customer or merchant to submit evidence.

Enum: Description
BUYER_EVIDENCE

Changes the status of the dispute to WAITING_FOR_BUYER_RESPONSE.

SELLER_EVIDENCE

Changes the status of the dispute to WAITING_FOR_SELLER_RESPONSE.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "action": "BUYER_EVIDENCE"
}
Response samples
application/json
{}

Settle dispute

post/v1/customer/disputes/{id}/adjudicate
Important: This method is for sandbox use only.
Settles a dispute in either the customer's or merchant's favor. Merchants can make this call in the sandbox to complete end-to-end dispute resolution testing, which mimics the dispute resolution that PayPal agents normally complete. To make this call, the dispute status must be UNDER_REVIEW and adjudicate link should be available in the HATEOAS links of the show dispute details response.
SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute to settle.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
adjudication_outcome
required
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The outcome of the adjudication.

Enum: Description
BUYER_FAVOR

Resolves the case in the customer's favor. Outcome is set to RESOLVED_BUYER_FAVOR.

SELLER_FAVOR

Resolves the case in the merchant's favor. Outcome is set to RESOLVED_SELLER_FAVOR.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "adjudication_outcome": "BUYER_FAVOR"
}
Response samples
application/json
{}

Send message about dispute to other party

post/v1/customer/disputes/{id}/send-message

Sends a message about a dispute, by ID, to the other party in the dispute. Merchants and customers can only send messages if the dispute_life_cycle_stage value is INQUIRY. For constraints and rules regarding documents that can be attached as part of the message, see documents. To send a message, use the send-message link in the HATEOAS links of the show dispute details response and specify the message in the JSON request body. In case the link is not present in the response you can't send a message on the dispute.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to send a message.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
message_document
string <binary>

A file that contains any additional info about the message posted.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/send-message \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-d '{
  "message": "Shipment is in progress."
}'
Response samples
application/json
{}

Appeal dispute

post/v1/customer/disputes/{id}/appeal

Appeals a dispute, by ID. To appeal a dispute, use the appeal link in the HATEOAS links from the show dispute details response. If this link does not appear, you cannot appeal the dispute. Submit new evidence as a document or notes in the JSON request body. For constraints and rules regarding documents, see documents.
To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body. For information about dispute reasons, see dispute reasons.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The PayPal dispute ID.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema: multipart/form-data
evidence-file
string <binary>

A file with evidence.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \
-H 'Content-Type: multipart/related' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK'  \
-F 'input={"evidences":[{"evidence_type":"PROOF_OF_FULFILLMENT","evidence_info":{"tracking_info":[{"carrier_name":"FEDEX","tracking_number":"122533485"}]},"notes":"Test"}]};type=application/json'\
-F 'file1=@NewDoc.pdf'
Response samples
application/json
{}

Deny offer to resolve dispute

post/v1/customer/disputes/{id}/deny-offer

Denies an offer that the merchant proposes for a dispute, by ID.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

The ID of the dispute for which to deny an offer.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters \w+\/[-+.\w]+

Content type of the request payload.

Authorization
required
string [ 1 .. 255 ] characters

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.

Request Body schema:
note
required
string [ 1 .. 2000 ] characters

The customer notes about the denial of offer. PayPal can but the merchant cannot view these notes.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Request samples
{
  • "note": "refund offer is very low."
}
Response samples
application/json
{}

Errors

ACTION_NOT_ALLOWED_IN_CURRENT_DISPUTE_STATE

Message:
This action is not allowed for this dispute ID. For the allowed actions, see the HATEOAS link in show dispute details.

Description: You cannot complete this action for this dispute ID.

AMOUNT_SHOULD_NOT_BE_PASSED

Message:
For MERCHANDISE_OR_SERVICE_NOT_RECEIVED disputes, refund amount cannot be specified in accept claim as this feature is not yet supported in PayPal Dispute system.

Description: You cannot specify the refund amount in an accept claim call.

AUTHORIZATION_ERROR

Message:
Authorization error occurred.

Description: An authorization error occurred. Check your credentials.

DATE_CAN_NOT_BE_IN_FUTURE

Message:
The start_time is incorrect. The start_time must be earlier than the current date and time stamp.

Description: The specified start time is in the future.

DISPUTE_REASON_NOT_ELIGIBLE

Message:
This dispute reason is not allowed for this transaction. To review the allowed reasons for this transaction, call validate transaction eligibility. Then, retry with one of the allowed reasons.

Description: The specified dispute reason is not valid.

INSUFFICIENT_FUNDS

Message:
You have insufficient funds in your account to accept a claim for this dispute. Add the appropriate balance to your PayPal account before you accept a claim for this case.

Description: Your account has insufficient funds for this claim.

INTANGIBLE_ITEM_CANNOT_BE_RETURNED

Message:
Return shipping address cannot be specified in accept claim for intangible item related disputes as this applies only for tangible item related transactions.

Description: You cannot specify the shipping address in an accept claim call for intangible item-related disputes.

INTERNAL_SERVICE_ERROR

Message:
An internal service error has occurred.

Description: Resend the request at another time.

INVALID_EVIDENCE_FILE

Message:
The evidence file is not valid. The user can upload up to 50 MB of files for a case. Individual files must be smaller than 10 MB. The supported file formats are JPG, GIF, PNG, and PDF. Correct and retry the request.

Description: The evidence file is not valid.

INVALID_EVIDENCE_TYPE_PROOF_OF_FULFILLMENT

Message:
The PROOF_OF_FULFILLMENT evidence type is not a valid evidence type for this dispute reason and status. Retry the request with a different evidence type.

Description: This evidence type is not valid for this dispute reason and status.

INVALID_PAGE_SIZE

Message:
The page_size is outside the allowed range. A valid page_size is from 1 to 50. Retry the request.

Description: The page size is outside the allowed range.

INVALID_RETURN_SHIPPING_ADDRESS_FORMAT

Message:
The format specified for the return shipping address is not valid. Correct the format and retry. See accept claim.

Description: The shipping address format is not valid.

INVALID_START_TIME_FORMAT

Message:
The start_time is not in the correct date and time format. The start_time must be in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ. Retry the request with the correct date and time format.

Description: The start time is not in the correct date and time format.

INVALID_START_TIME_RANGE

Message:
The start_time is outside the allowed range. The start_time must be within the last 180 days. Retry the request with a valid start_time.

Description: The start time is outside the allowed range.

ITEM_ID_IS_MANDATORY_FOR_MULTIPLE_EVIDENCES

Message:
An item ID is required for this dispute. Provide an item ID for each evidence document. For details, see provide evidence.

Description: An item ID is required.

MANDATORY_PARAMETER_MISSING

Message:
When you create a dispute, a buyer_transaction_id is required but it is missing. Retry with a valid buyer_transaction_id.

Description: The customer transaction ID, or buyer_transaction_id, is missing.

MISSING_EVIDENCE_INFO

Message:
The evidence information is required but it is missing for this dispute. Retry the request with valid evidence information. For details, see provide evidence.

Description: The evidence information is missing.

MISSING_EVIDENCE_TYPE

Message:
The evidence type is required but it is missing for this dispute. Retry the request with a valid evidence type. For details, see provide evidence.

Description: The evidence type is missing.

MISSING_REASON_CODE

Message:
To add or update a reason code, you must provide a reason code but it is missing. Retry the request with a valid reason code.

Description: A reason code is missing.

MISSING_REFUND_ID

Message:
For PROOF_OF_REFUND, at least one refund ID is required but it is missing. Retry the request with a valid refund ID. For information, For details, see provide evidence.

Description: A refund ID is missing. You specify PROOF_OF_REFUND in the evidence_type parameter of a provide evidence call.

MISSING_RETURN_SHIPPING_ADDRESS

Message:
For MERCHANDISE_OR_SERVICE_NOT_RECEIVED cases, return shipping address cannot be specified in accept claim as this applies only for MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes.

Description: You cannot specify the return shipping address in an accept claim call because the shipping address applies to only MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes.

MISSING_TRACKING_INFO

Message:
For PROOF_OF_FULFILLMENT, the tracking number and carrier name are required but they are missing. Retry the request. For information, see response_tracking_info.

Description: The tracking number and carrier name are missing. You specify PROOF_OF_FULFILLMENT in the evidence_type parameter of a provide evidence call.

PERMISSION_DENIED

Message:
You do not have the correct permission for the requested operation.

Description: You do not have the correct permissions to make this request.

REFUND_DECLINED_BY_COMPLIANCE_SCANNING

Message:
The refund has been declined by compliance scanning.

Description: Refund declined by Compliance Scanning.

RESOURCE_NOT_FOUND_ERROR

Message:
Resource not found.

Description: The requested resource is not found in the system.

SHIPPING_ADDRESS_SHOULD_NOT_BE_PASSED

Message:
If seller proposed offer is less than buyer requested refund amount, shipping address must be specified for MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes. PayPal may use this in case buyer denies the offer and requests buyer to return the item to resolve the dispute.

Description: You must specify the shipping address for MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes.

UNKNOWN_ERROR

Message:
Unknown exception occurred.

Description: An unknown error occurred.

VALIDATION_ERROR

Message:
Invalid request - see details.

Description: One or more validation errors occurred. See the details for specific validation errors.

Definitions

Accept Claim Type

The refund type proposed by the merchant for the dispute.

string (Accept Claim Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The refund type proposed by the merchant for the dispute.

Enum: Description
REFUND

The merchant must refund the customer without any item replacement or return. This type is applicable when a merchant is willing to refund the entire dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.

REFUND_WITH_RETURN

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

PARTIAL_REFUND

The merchant proposes a partial refund for the dispute.This type is applicable when a merchant is willing to refund an amount lesser than dispute amount. Include the refund_amount parameter.

REFUND_WITH_RETURN_SHIPMENT_LABEL

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item using the shipment label provided by the merchant. Include the return_shipment_info and return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

"REFUND"

accept_claim

A request by a merchant to accept a customer's merchandise claim.

note
required
string [ 1 .. 2000 ] characters

The merchant's notes about the claim. PayPal can, but the customer cannot, view these notes.

accept_claim_reason
string (accept_claim_reason) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The merchant's reason for acceptance of the customer's claim.

Enum: Description
DID_NOT_SHIP_ITEM

Merchant is accepting customer's claim as they could not ship the item back to the customer

TOO_TIME_CONSUMING

Merchant is accepting customer's claim as it is taking too long for merchant to fulfil the order

LOST_IN_MAIL

Merchant is accepting customer's claim as the item is lost in mail or transit

NOT_ABLE_TO_WIN

Merchant is accepting customer's claim as the merchant is not able to find sufficient evidence to win this dispute

COMPANY_POLICY

Merchant is accepting customer’s claims to follow their internal company policy

REASON_NOT_SET

This is the default value merchant can use if none of the above reasons apply

invoice_id
string [ 1 .. 127 ] characters ^[A-Za-z0-9:\-|]+$

The merchant-provided ID of the invoice for the refund. This optional value is used to map the refund to an invoice ID in the merchant's system.

Array of objects (response_shipment_info) [ 1 .. 100 ] items

An array of relevant shipment information for the items.

Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason using the shipment label provided by the merchant.

object (Portable Postal Address (Medium-Grained))

The return address for the item.

Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason, especially if the refund amount is less than the dispute amount.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

accept_claim_type
string (Accept Claim Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The refund type proposed by the merchant for the dispute.

Enum: Description
REFUND

The merchant must refund the customer without any item replacement or return. This type is applicable when a merchant is willing to refund the entire dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.

REFUND_WITH_RETURN

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

PARTIAL_REFUND

The merchant proposes a partial refund for the dispute.This type is applicable when a merchant is willing to refund an amount lesser than dispute amount. Include the refund_amount parameter.

REFUND_WITH_RETURN_SHIPMENT_LABEL

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item using the shipment label provided by the merchant. Include the return_shipment_info and return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

{
  • "note": "string",
  • "accept_claim_reason": "DID_NOT_SHIP_ITEM",
  • "invoice_id": "string",
  • "return_shipment_info": [
    • {
      • "shipment_label": {},
      • "tracking_info": {
        • "carrier_name": "UPS",
        • "carrier_name_other": "string",
        • "tracking_url": "http://example.com",
        • "tracking_number": "string"
        }
      }
    ],
  • "return_shipping_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      }
    },
  • "refund_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "accept_claim_type": "REFUND"
}

accept_claim

The allowed response options when the merchant is accepting the claim.

accept_claim_types
Array of strings (Accept Claim Type) [ 1 .. 10 ] items

The types of refund the merchant can provide the customer.

Items Enum: Description
REFUND

The merchant must refund the customer without any item replacement or return. This type is applicable when a merchant is willing to refund the entire dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.

REFUND_WITH_RETURN

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

PARTIAL_REFUND

The merchant proposes a partial refund for the dispute.This type is applicable when a merchant is willing to refund an amount lesser than dispute amount. Include the refund_amount parameter.

REFUND_WITH_RETURN_SHIPMENT_LABEL

The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item using the shipment label provided by the merchant. Include the return_shipment_info and return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.

{
  • "accept_claim_types": [
    • "REFUND"
    ]
}

accept_claim_reason

The merchant's reason for acceptance of the customer's claim.

string (accept_claim_reason) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The merchant's reason for acceptance of the customer's claim.

Enum: Description
DID_NOT_SHIP_ITEM

Merchant is accepting customer's claim as they could not ship the item back to the customer

TOO_TIME_CONSUMING

Merchant is accepting customer's claim as it is taking too long for merchant to fulfil the order

LOST_IN_MAIL

Merchant is accepting customer's claim as the item is lost in mail or transit

NOT_ABLE_TO_WIN

Merchant is accepting customer's claim as the merchant is not able to find sufficient evidence to win this dispute

COMPANY_POLICY

Merchant is accepting customer’s claims to follow their internal company policy

REASON_NOT_SET

This is the default value merchant can use if none of the above reasons apply

"DID_NOT_SHIP_ITEM"

accept_offer

A customer request to accept the offer made by the merchant.

note
string [ 1 .. 2000 ] characters

The customer notes about accepting of offer. PayPal can but the merchant cannot view these notes.

{
  • "note": "string"
}

acknowledge_return_item

A merchant request to acknowledge receipt of the disputed item that the customer returned.

note
string [ 1 .. 2000 ] characters

The merchant provided notes. PayPal can but the consumer cannot view these notes.

Array of objects (acknowledge_return_item_evidence) [ 1 .. 100 ] items

An array of evidence documents.

acknowledgement_type
string (acknowledgement_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The type of acknowledgement given by the merchant.

Enum: Description
ITEM_RECEIVED

The merchant has received the item returned by the customer.

ITEM_NOT_RECEIVED

The merchant has not received the item.

DAMAGED

The items returned by the customer were damaged.

EMPTY_PACKAGE_OR_DIFFERENT

The package was empty or the goods were different from what was expected.

MISSING_ITEMS

The package did not have all the items that were expected.

{
  • "note": "string",
  • "evidences": [
    • {
      • "evidence_type": "PROOF_OF_DAMAGE",
      • "documents": []
      }
    ],
  • "acknowledgement_type": "ITEM_RECEIVED"
}

acknowledge_return_item

The allowed response options when the seller acknowledges that the buyer has returned an item for the dispute.

acknowledgement_types
Array of strings (acknowledgement_type) [ 1 .. 10 ] items

The types of response when the merchant acknowledges a returned item.

Items Enum: Description
ITEM_RECEIVED

The merchant has received the item returned by the customer.

ITEM_NOT_RECEIVED

The merchant has not received the item.

DAMAGED

The items returned by the customer were damaged.

EMPTY_PACKAGE_OR_DIFFERENT

The package was empty or the goods were different from what was expected.

MISSING_ITEMS

The package did not have all the items that were expected.

{
  • "acknowledgement_types": [
    • "ITEM_RECEIVED"
    ]
}

acknowledge_return_item_evidence

An evidence submitted by the merchant when acknowledging a returned item.

evidence_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The evidence type.

Enum: Description
PROOF_OF_DAMAGE

Documentation supporting the claim that the item is damaged.

THIRDPARTY_PROOF_FOR_DAMAGE_OR_SIGNIFICANT_DIFFERENCE

Proof should be provided by an unbiased third-party, such as a dealer, appraiser or another individual or organisation that's qualified in the area of the item in question (other than yourself), and detail the extent of the damage or clearly explain how the item received significantly differs from the item advertised.

DECLARATION

Signed declaration about the information provided.

PROOF_OF_MISSING_ITEMS

Image of open box with returned items and shipping label clearly visible.

PROOF_OF_EMPTY_PACKAGE_OR_DIFFERENT_ITEM

Image of empty box or returned items that are different from what were expected and shipping label clearly visible.

PROOF_OF_ITEM_NOT_RECEIVED

Any proof about the non receipt of the item, such as screenshot of tracking info.

required
Array of objects (document) [ 1 .. 100 ] items

An array of evidence documents.

{
  • "evidence_type": "PROOF_OF_DAMAGE",
  • "documents": []
}

acknowledgement_type

The type of acknowledgement allowed for the merchant after the customer has returned the item. The merchant can update whether the item was received and is as expected or if the item was not received.

string (acknowledgement_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The type of acknowledgement allowed for the merchant after the customer has returned the item. The merchant can update whether the item was received and is as expected or if the item was not received.

Enum: Description
ITEM_RECEIVED

The merchant has received the item returned by the customer.

ITEM_NOT_RECEIVED

The merchant has not received the item.

DAMAGED

The items returned by the customer were damaged.

EMPTY_PACKAGE_OR_DIFFERENT

The package was empty or the goods were different from what was expected.

MISSING_ITEMS

The package did not have all the items that were expected.

"ITEM_RECEIVED"

action_info

The extended properties for a evidence. Includes additional information such as the action for which the evidence was requested/submitted, and whether the evidence is mandatory.

action
string [ 1 .. 255 ] characters ^[A-Z_]+$

The action for which the evidence was requested or submitted.

Enum: Description
ACKNOWLEDGE_RETURN_ITEM

The evidence corresponds to action acknowledge_return_item.

ACCEPT_CLAIM

The evidence corresponds to action accept_claim.

PROVIDE_EVIDENCE

The evidence corresponds to action provide_evidence.

APPEAL

The evidence corresponds to action appeal.

CANCEL

The evidence corresponds to action cancel.

CHANGE_REASON

The evidence corresponds to action change_reason.

ESCALATE

The evidence corresponds to action escalate.

response_option
string [ 1 .. 255 ] characters ^[A-Z_]+$

The response option for the corresponding action. Possible values:

.

mandatory
boolean

Indicates whether the evidence is mandatory for the corresponding action and response option.

{
  • "action": "ACKNOWLEDGE_RETURN_ITEM",
  • "response_option": "string",
  • "mandatory": true
}

adjudicate

A request to settle a dispute in either the customer's or merchant's favor.

adjudication_outcome
required
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The outcome of the adjudication.

E