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.

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

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:
application/json

note	string [ 1 .. 2000 ] characters ^(.\|\r?\n)*$ 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

Payload
cURL
Node.js
Java
Python

{"note": "Escalating to PayPal claim for resolution."
}

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
}
]
}

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` is	The `status` updates to
`BUYER_EVIDENCE`	`WAITING_FOR_BUYER_RESPONSE`
`SELLER_EVIDENCE`	`WAITING_FOR_SELLER_RESPONSE`

SecurityOauth2

Request

path Parameters

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:
application/json

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

Payload
cURL
Node.js
Java
Python

{"action": "BUYER_EVIDENCE"
}

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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`-`dd``T``HH`:`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`-`dd``T``HH`:`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`-`dd``T``HH`:`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
Node.js
Java
Python

curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes?outcomes=WON,PAID_OUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK'

Response samples

application/json

{"items": [{"dispute_id": "PP-D-208454",
"create_time": "2023-07-22T01:34:47.000Z",
"update_time": "2023-07-22T02:14:29.000Z",
"disputed_transactions": [{"buyer_transaction_id": "54M94084LL945391E",
"buyer": {"payer_id": "APFXN3NMGTFEU"
},
"seller": {"merchant_id": "6C6TADF69U7Q6"
}
}
],
"reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
"status": "RESOLVED",
"dispute_state": "RESOLVED",
"dispute_amount": {"currency_code": "USD",
"value": "16.00"
},
"outcome": "WON",
"dispute_life_cycle_stage": "CHARGEBACK",
"dispute_channel": "INTERNAL",
"dispute_flow": "OTHER",
"links": [{"href": "https://te-elmo-test.qa.paypal.com:19387/v1/customer/disputes/PP-D-208454",
"rel": "self",
"method": "GET"
}
]
},
{"dispute_id": "PP-D-208420",
"create_time": "2023-07-21T14:24:12.000Z",
"update_time": "2023-07-21T14:29:53.000Z",
"disputed_transactions": [{"buyer_transaction_id": "59055077FC437070A",
"buyer": {"payer_id": "APFXN3NMGTFEU"
},
"seller": {"merchant_id": "6C6TADF69U7Q6"
}
}
],
"reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
"status": "RESOLVED",
"dispute_state": "RESOLVED",
"dispute_amount": {"currency_code": "USD",
"value": "12.00"
},
"outcome": "WON",
"dispute_life_cycle_stage": "CHARGEBACK",
"dispute_channel": "INTERNAL",
"dispute_flow": "OTHER",
"links": [{"href": "https://te-elmo-test.qa.paypal.com:19387/v1/customer/disputes/PP-D-208420",
"rel": "self",
"method": "GET"
}
]
}
],
"links": [{"href": "https://te-elmo-test.qa.paypal.com:19387/v1/customer/disputes?outcomes=WON,PAID_OUT",
"rel": "self",
"method": "GET"
},
{"href": "https://te-elmo-test.qa.paypal.com:19387/v1/customer/disputes?outcomes=WON,PAID_OUT",
"rel": "first",
"method": "GET"
}
]
}

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

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
Node.js
Java
Python

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: multipart/related; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'  \
-F 'input={"notes" : "Sample notes"};type=application/json'\
-F 'file1=@doc.pdf'

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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

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
Node.js
Java
Python

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 with item return.",
  "return_shipping_address": {
    "address_line_1": "14,Kimberly st",
    "address_line_2": "Open Road North",
    "country_code": "US",
    "admin_area_1": "Gotham City",
    "admin_area_2": "Gotham",
    "postal_code": "124566"
  },
  "return_shipment_info": [
    {
      "shipment_label": {
        "id": "10-006-01-001-96571189-0702-49ce-a866-faad20e29731",
        "name": "file1.pdf"
      },
      "tracking_info": {
        "carrier_name": "FEDEX",
        "tracking_number": "122533485"
      }
    }
  ]
}'

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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

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
Node.js
Java
Python

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/send-message \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-H 'Content-Type: multipart/related; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'  \
-F 'input={"message" : "Sample message"};type=application/json'\
-F 'file1=@doc.pdf'

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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

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:
application/json

note

required

string [ 1 .. 2000 ] characters ^(.|\r?\n)*$

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

Payload
cURL
Node.js
Java
Python

{"note": "refund offer is very low."
}

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
}
]
}

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

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
Node.js
Java
Python

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": [{"posted_by": "BUYER",
"time_posted": "2019-04-11T04:18:04.000Z",
"content": "SNAD case created through automation",
"documents": [{"name": "SNAD_Issue.pdf",
"url": "https://api-m.paypal.com/v2/content/documents/DIS-010-4c465d94-241c-4e1f-b384-9de78f7200bb/files/1/download"
}
]
}
],
"extensions": {"merchandize_dispute_properties": {"issue_type": "SERVICE",
"service_details": {"sub_reasons": ["INCOMPLETE"
],
"purchase_url": "https://ebay.in"
}
}
},
"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": [{"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-4012",
"rel": "self",
"method": "GET"
}
]
}

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

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:
application/json

Array

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:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain 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.
objects	Contain 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

any (Patch Value)

The value to apply. The remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified.

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

Payload
cURL
Node.js
Java
Python

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

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

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
Node.js
Java
Python

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customers/disputes/PP-R-FJD-2239769/provide-evidence \
-H 'Authorization: Bearer A101.OLQiCxMmoVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_Nliuq_lfZdU.P3gvkY3PO28akjKYaDorm12QdfK' \
-H 'Content-Type: multipart/related'  \
-F 'input={"evidences":[{"item_id":"Item1000","evidence_type":"PROOF_OF_FULFILLMENT","evidence_info":{"tracking_info":[{"carrier_name":"FEDEX","tracking_number":"678765432", "tracking_url": "https://www.trackerexample.com/track/YDH0004TEST538AZ", "tracking_status": "DELIVERED"},{"carrier_name":"UPS","tracking_number":"98765432", "tracking_url": "https://www.trackerexample.com/track/TEST538AZ", "tracking_status": "IN_TRANSIT"}]},"notes":"Test"},{"item_id":"Item2000","evidence_type":"PROOF_OF_REFUND","evidence_info":{"refund_ids":["5WG70110TE909641H"]},"notes":"Test"},{"item_id":"Item3000","evidence_type":"OTHER","notes":"Test OTHER"},{"item_id":"Item4000","evidence_type":"POLICE_REPORT","notes":"Test POLICE_REPORT"}]};type=application/json'

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.paypal.com/v1/customers/disputes/PP-R-FJD-2239769"
}
]
}

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

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:
application/json

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

Payload
cURL
Node.js
Java
Python

{"adjudication_outcome": "BUYER_FAVOR"
}

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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

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:
application/json

note

required

string [ 1 .. 2000 ] characters ^(.|\r?\n)*$

The merchant's notes about the offer.

invoice_id

string [ 1 .. 127 ] characters ^.*$

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

Payload
cURL
Node.js
Java
Python

{"note": "Offer refund with replacement item.",
"offer_type": "REFUND_WITH_REPLACEMENT",
"offer_amount": {"currency_code": "USD",
"value": "23"
}
}

Response samples

application/json

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
}
]
}

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

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
Node.js
Java
Python

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

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
}
]
}

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

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
Node.js
Java
Python

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

{"links": [{"rel": "self",
"method": "GET",
"href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
}
]
}

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

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:
application/json

note	string [ 1 .. 2000 ] characters ^(.\|\r?\n)*$ The customer notes about accepting of offer. PayPal can but the merchant cannot view these notes.

Responses

202

A successfully accepted request returns the HTTP 202 Accepted status code and a JSON response body that includes a HATEOAS link to the ID of the request. The request returns 202 Accepted status in case money movement for the offer is delayed due to some internal reasons.

Request samples

Payload
cURL
Node.js
Java
Python

{"note": "I am ok with the refund offered."
}

Response samples

application/json

{"links": [{"href": "https://api-m.sandbox.paypal.com/v1/apis/requests/84880ea1-6d89-4ac2-982e-821cce7db87e",
"rel": "self",
"method": "GET"
}
]
}

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.

FUNDING_INSTRUMENT_PREFERENCE_NOT_ALLOWED

Message:
This action is not allowed for this dispute ID.

Description: You cannot specify the refund funding instrument preference, As this option not present in allowed_action_options.

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.

PROVISIONAL_CREDIT_PREFERENCE_NOT_ALLOWED

Message:
This action is not allowed for this dispute ID.

Description: You cannot specify the provisional credit preference, As this option not present in allowed_action_options.

REFUND_DECLINED_BY_COMPLIANCE_SCANNING

Message:
The refund has been declined by compliance scanning.

Description: Refund declined by Compliance Scanning.

REFUND_PREFERENCE_MUTUALLY_EXCLUSIVE

Message:
Invalid request - see details.

Description: You should not provide preference for funding instrument and provisional credit in same request. Any one preference should be passed per request based on allowed_action_options.

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 ^(.|\r?\n)*$

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 ^.*$

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)

To accept a customer's claim, the amount that the merchant agrees to refund the customer. The subsequent action depends on the amount:

If this amount is less than the customer-requested amount, the dispute updates to require customer acceptance.
If this amount is equal to or greater than the customer-requested amount, this amount is automatically refunded to the customer and the dispute closes.

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": {"name": "string",
"url": "http://example.com"
},
"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 ^(.\|\r?\n)*$ 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 ^(.|\r?\n)*$

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": [{"name": "string",
"url": "http://example.com"
}
]
}
],
"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": [{"name": "string",
"url": "http://example.com"
}
]
}

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_]+$

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.

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`.

{"adjudication_outcome": "BUYER_FAVOR"
}

adjudication

The Adjudication details for the dispute.

type

required

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

The type of adjudication.

Enum:	Description
DENY_BUYER	The decision is to deny the buyer for the dispute.
PAYOUT_TO_BUYER	The decision is to payout to the buyer.
PAYOUT_TO_SELLER	The decision is to payout to the seller if the seller was debited earlier.
RECOVER_FROM_SELLER	The decision is to charge the seller for the dispute if the seller was not debited already.

adjudication_time

required

string <ppaas_date_time_v3> (date_time) [ 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 adjudication was done, in Internet date and time format.

reason

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

The reason for the adjudication type.

Enum:	Description
AMOUNT_DIFFERENCE_EXPECTED_DUE_TO_FEES	Seller submitted proof of correct charge.
BILLING_AGREEMENT_CHANGE_DISCLOSED	Seller had disclosed billing agreement changes upfront.
BILLING_AGREEMENT_CHANGE_NOT_DISCLOSED	Seller had not disclosed billing agreement changes upfront.
BILLING_AGREEMENT_DATE_CHANGE_DISCLOSED	Seller had shared change in billing agreement date upfront.
BILLING_AGREEMENT_DATE_CHANGE_NOT_DISCLOSED	Seller had not shared change in billing agreement date upfront.
BUYER_ATTEMPTED_RETURN	Buyer has attempted to return the item.
BUYER_BILLED_ONLY_ONCE	Buyer was charged only once and did not submit sufficient evidence of duplicate charge.
BUYER_CANCELLED_CASE	Buyer cancelled the case.
BUYER_CANCELLED_SERVICE	Buyer cancelled the service or recurring transaction.
BUYER_FAILED_TO_DESCRIBE_ISSUE	Buyer did not describe the issue to justify the refund.
BUYER_HAS_POSSESSION_OF_THE_MERCHANDISE_OR_SERVICE	Buyer continues to possess the item or has received the service.
BUYER_MADE_NO_ATTEMPT_TO_RESOLVE_WITH_SELLER	Buyer did not attempt to resolve the issue with the seller.
BUYER_NOT_IN_POSSESSION_OF_ITEM_TO_RETURN	Buyer is not in possession of the item to be returned.
BUYER_PROVIDED_CREDIT_RECEIPT	Buyer provided credit receipt or relevant documentation.
BUYER_RECEIVED_DUPLICATE_REFUND	Buyer received the refund twice.
CANCELLED_PER_TERMS_OF_BILLING_AGREEMENT	Billing agreement was cancelled as per agreed terms.
CARD_NOT_STOLEN	Buyer in possession of the card which was reported as stolen or lost.
CARD_NOT_STOLEN_BEFORE_AUTH	Buyer reported card as lost or stolen after the authorization date.
CUSTOMER_RECOGNIZES_TRANSACTION	Buyer recognizes the transaction as valid.
DECISION_BASED_ON_AVAILABLE_INFORMATION	Case decision was made as per available information when specific reasons are not applicable.
DELIVERY_AFTER_EXPECTED_DELIVERY_DATE	Item or service was delivered after the expected delivery date had passed.
DELIVERY_DUE_WITHIN_EXPECTED_DELIVERY_DATE	Delivery of the item or service is due within the expected delivery date.
DELIVERY_OR_SERVICE_REFUSED	Seller refused delivery or service of the item.
DOCUMENTATION_MATCHES_AMOUNT_CHARGED	Documentation provided supports the amount that was charged.
DOCUMENTATION_MATCHES_AMOUNT_IN_PAYPAL_ACCOUNT	Documentation provided supports the amount charged on buyer's account.
DUPLICATE_ADD_FUNDS	Buyer submitted sufficient proof of duplicate charge.
EFFORTLESS_SELLER_PROTECTION	The case is decided based on Protection Policy.

Disputes (1)

Escalate dispute to claim

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Update dispute status

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

List disputes

query Parameters

header Parameters

Provide supporting information for dispute

path Parameters

header Parameters

Request Body schema: multipart/form-data

Accept claim

path Parameters

header Parameters

Request Body schema: multipart/form-data

Send message about dispute to other party

path Parameters

header Parameters

Request Body schema: multipart/form-data

Deny offer to resolve dispute

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Show dispute details

path Parameters

header Parameters

Partially update dispute

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Provide evidence

path Parameters

header Parameters

Request Body schema: multipart/form-data

Settle dispute

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Make offer to resolve dispute

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Appeal dispute

path Parameters

header Parameters

Request Body schema: multipart/form-data

Acknowledge returned item

path Parameters

header Parameters

Request Body schema: multipart/form-data

Accept offer to resolve dispute

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Errors

ACTION_NOT_ALLOWED_IN_CURRENT_DISPUTE_STATE

AMOUNT_SHOULD_NOT_BE_PASSED

AUTHORIZATION_ERROR

DATE_CAN_NOT_BE_IN_FUTURE

DISPUTE_REASON_NOT_ELIGIBLE

FUNDING_INSTRUMENT_PREFERENCE_NOT_ALLOWED

INSUFFICIENT_FUNDS

INTANGIBLE_ITEM_CANNOT_BE_RETURNED

INTERNAL_SERVICE_ERROR

INVALID_EVIDENCE_FILE

INVALID_EVIDENCE_TYPE_PROOF_OF_FULFILLMENT

INVALID_PAGE_SIZE

INVALID_RETURN_SHIPPING_ADDRESS_FORMAT

INVALID_START_TIME_FORMAT

INVALID_START_TIME_RANGE

ITEM_ID_IS_MANDATORY_FOR_MULTIPLE_EVIDENCES

MANDATORY_PARAMETER_MISSING

MISSING_EVIDENCE_INFO

MISSING_EVIDENCE_TYPE

MISSING_REASON_CODE

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json