PayPal Developer Logo
  • Docs
    OnlineIn-PersonMultiparty3rd-PartyPayoutsDisputesReportsIdentityDocs Archive
  • APIs & SDKs
    REST APIsJavaScript SDKNVP/SOAP APIsDonate SDKBraintree GraphQL API
  • Tools
    Integration BuilderSandbox Testing GuideAPI ExecutorDemo PortalCredit Card GeneratorAPI Status
  • Support
Log in to Dashboard
    Log in to Dashboard
    REST APIs
    Get Started
    Authentication
    Postman Guide
    Requests
    Responses
    Core Resources
    Overview
    Add Tracking
    Catalog Products
    Disputes
      Disputes
      post
      Acknowledge returned item
      post
      Provide evidence
      get
      Show dispute details
      patch
      Partially update dispute
      get
      List disputes
      post
      Provide supporting information for dispute
      post
      Make offer to resolve dispute
      post
      Escalate dispute to claim
      post
      Accept offer to resolve dispute
      post
      Accept claim
      post
      Update dispute status
      post
      Settle dispute
      post
      Send message about dispute to other party
      post
      Appeal dispute
      post
      Deny offer to resolve dispute
      Errors
      Definitions
    Identity
    Invoicing
    Orders
    Partner Referrals
    Payment Experience
    Payment Method Tokens
    Payments
    Payouts
    Referenced Payouts
    Subscriptions
    Transaction Search
    Webhooks Management
    Webhooks
    Overview
    Webhook event names
    Webhooks Events dashboard
    Webhooks simulator
    Integration
    Sandbox
    Overview
    Accounts
    Bulk Accounts
    Card testing
    Negative Testing
    Go Live
    Production Environment
    PayPal Application Guidelines
    PayPal Security Guidelines
    Rate Limiting Guidelines
    Idempotency
    Reference
    Currency Codes
    Country Codes
    State & Province Codes
    Locale codes
    Deprecated Resources
    Overview
    Billing Agreements
    Billing Plans
    Invoicing v1
    Orders v1
    Partner Referrals v1
    Payments v1

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
  • 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
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
      }
    ]
}

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
  • Node.js
  • Java
  • Python
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
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
}

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
  • 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
  • 200
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
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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
[
  • {
    • "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
  • Node.js
  • Java
  • Python
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
  • 200
application/json
{
  • "items": [
    • {
      • "dispute_id": "PP-000-003-648-191",
      • "create_time": "2017-01-24T10:41:35.000Z",
      • "update_time": "2017-01-24T11:40:32.000Z",
      • "status": "WAITING_FOR_SELLER_RESPONSE",
      • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
      • "dispute_state": "REQUIRED_OTHER_PARTY_ACTION",
      • "dispute_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "links": [
        • {
          • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-191",
          • "rel": "self",
          • "method": "GET"
          }
        ]
      },
    • {
      • "dispute_id": "PP-000-003-648-175",
      • "create_time": "2017-01-24T10:37:23.000Z",
      • "update_time": "2017-01-24T11:32:32.000Z",
      • "status": "UNDER_REVIEW",
      • "reason": "UNAUTHORISED",
      • "dispute_amount": {
        • "currency_code": "USD",
        • "value": "20.00"
        },
      • "links": [
        • {
          • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-175",
          • "rel": "self",
          • "method": "GET"
          }
        ]
      },
    • {
      • "dispute_id": "PP-R-003-648-191",
      • "create_time": "2022-05-24T10:41:35.000Z",
      • "update_time": "2022-05-24T11:40:32.000Z",
      • "status": "WAITING_FOR_SELLER_RESPONSE",
      • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
      • "dispute_state": "REQUIRED_OTHER_PARTY_ACTION",
      • "dispute_asset": {
        • "asset_symbol": "BTC",
        • "quantity": "5.01"
        },
      • "links": [
        • {
          • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-191",
          • "rel": "self",
          • "method": "GET"
          }
        ]
      }
    ],
  • "links": [
    • {
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes",
      • "rel": "self",
      • "method": "GET"
      },
    • {
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes",
      • "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
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
  • 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: application/json' \
-d '{
  "notes": "Sample notes"
}' 
Response samples
  • 200
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
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
  • 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
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
      }
    ]
}

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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
{
  • "note": "Escalating to PayPal claim for resolution."
}
Response samples
  • 200
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
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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
{
  • "note": "I am ok with the refund offered."
}
Response samples
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
      }
    ]
}

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
  • 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 to the customer."
}' 
Response samples
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
}

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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
{
  • "action": "BUYER_EVIDENCE"
}
Response samples
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
}

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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
{
  • "adjudication_outcome": "BUYER_FAVOR"
}
Response samples
  • 200
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
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
  • Node.js
  • Java
  • Python
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
  • 200
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
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
  • 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
  • 200
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
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
  • Payload
  • cURL
  • Node.js
  • Java
  • Python
{
  • "note": "refund offer is very low."
}
Response samples
  • 200
application/json
{
  • "links": [
    • {
      • "rel": "self",
      • "method": "GET",
      • "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
      }
    ]
}

Errors

ACTION_NOT_ALLOWED_IN_CURRENT_DISPUTE_STATE

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

AMOUNT_SHOULD_NOT_BE_PASSED

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. You cannot specify the refund amount in an accept claim call.

AUTHORIZATION_ERROR

Authorization error occurred. An authorization error occurred. Check your credentials.

DATE_CAN_NOT_BE_IN_FUTURE

The start_time is incorrect. The start_time must be earlier than the current date and time stamp. The specified start time is in the future.

DISPUTE_REASON_NOT_ELIGIBLE

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. The specified dispute reason is not valid.

INSUFFICIENT_FUNDS

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. Your account has insufficient funds for this claim.

INTANGIBLE_ITEM_CANNOT_BE_RETURNED

Return shipping address cannot be specified in accept claim for intangible item related disputes as this applies only for tangible item related transactions. You cannot specify the shipping address in an accept claim call for intangible item-related disputes.

INTERNAL_SERVICE_ERROR

An internal service error has occurred. Resend the request at another time.

INVALID_EVIDENCE_FILE

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. The evidence file is not valid.

INVALID_EVIDENCE_TYPE_PROOF_OF_FULFILLMENT

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. This evidence type is not valid for this dispute reason and status.

INVALID_PAGE_SIZE

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

INVALID_RETURN_SHIPPING_ADDRESS_FORMAT

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

INVALID_START_TIME_FORMAT

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. The start time is not in the correct date and time format.

INVALID_START_TIME_RANGE

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. The start time is outside the allowed range.

ITEM_ID_IS_MANDATORY_FOR_MULTIPLE_EVIDENCES

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

MANDATORY_PARAMETER_MISSING

When you create a dispute, a buyer_transaction_id is required but it is missing. Retry with a valid buyer_transaction_id. The customer transaction ID, or buyer_transaction_id, is missing.

MISSING_EVIDENCE_INFO

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

MISSING_EVIDENCE_TYPE

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. The evidence type is missing.

MISSING_REASON_CODE

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. A reason code is missing.

MISSING_REFUND_ID

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. A refund ID is missing. You specify PROOF_OF_REFUND in the evidence_type parameter of a provide evidence call.

MISSING_RETURN_SHIPPING_ADDRESS

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

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

You do not have the correct permission for the requested operation. You do not have the correct permissions to make this request.

REFUND_DECLINED_BY_COMPLIANCE_SCANNING

The refund has been declined by compliance scanning. Refund declined by Compliance Scanning.

RESOURCE_NOT_FOUND_ERROR

Resource not found. The requested resource is not found in the system.

SHIPPING_ADDRESS_SHOULD_NOT_BE_PASSED

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. You must specify the shipping address for MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes.

UNKNOWN_ERROR

Unknown exception occurred. An unknown error occurred.

VALIDATION_ERROR

Invalid request - see details. 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": {
        • "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

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": [
        • {
          • "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_]+$

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:

  • Acknowledgement Types
  • Accept Claim types
.

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.

IN_PERSON_DELIVERY

Seller delivered the item in person.

INELIGIBLE_BUYER_PROTECTION_POLICY

The pattern identified does not meet buyer protection eligibility.

INELIGIBLE_SELLER_PROTECTION_POLICY

The pattern identified does not meet seller protection eligibility.

INQUIRY_OFFER_ITEM_REPLACED

Seller agreed to replace the item.

INQUIRY_OFFER_PARTIAL_REFUND

Seller agreed to issue a partial refund to the buyer.

INQUIRY_OFFER_REFUND_WITH_ITEM_RETURN

Seller agreed to issue a refund for item return.

INQUIRY_OFFER_REFUND_WITH_REPLACEMENT

Seller agreed to replace the damaged item along with refunds applicable.

INVALID_APPEAL_REASON

Seller appealed twice for the same reason with invalid reason.

INVALID_CHARGEBACK_SELLER_FAVOUR

The case is decided as invalid based on external network policy.

INVALID_DELIVERY_PROOF

Seller provided invalid proof of delivery.

INVALID_DELIVERY_PROOF_SIGNATURE

Buyer's signature confirmation missing in proof of delivery.

INVALID_DOCUMENTATION

The documentation provided is not valid.

INVALID_PROOF_OF_SHIPMENT

Seller provided invalid proof of shipment.

INVALID_REFUND_PROOF

Seller provided invalid proof of refund.

INVALID_RETURN_DELIVERY_NO_SIGNATURE_PROOF

Seller's signature confirmation missing in proof of return.

INVALID_RETURN_DELIVERY_PROOF

Buyer provided invalid proof of return.

INVALID_TRACKING

Seller provided invalid tracking information.

ITEM_ALTERED_REPAIRED

Item was altered or repaired while in buyer's possession.

ITEM_NOT_AS_ADVERTISED

Item or service provided didn’t match as it was advertised.

ITEM_NOT_AS_DESCRIBED

Item or service provided didn’t match as it was described.

ITEM_NOT_DAMAGED

Item or service provided was not damaged or missing any parts.

ITEM_NOT_DELIVERED

Seller did not deliver the item to the buyer.

ITEM_NOT_RETURNED_TO_SELLER

Item was not returned to seller.

ITEM_NOT_SHIPPED

Seller did not provide verified proof of shipment or delivery.

ITEM_OF_DIFFERENT_QUALITY_OR_QUANTITY

Item sent to the buyer was of different quality, quantity, color, or size.

ITEM_OUT_OF_STOCK_AND_NOT_DELIVERED

Item was not delivered as it was no longer in stock.

ITEM_RETURNED_TO_SELLER

Buyer returned the item to seller.

ITEM_SERVICE_MISREPRESENTED

Seller's listing misrepresented the item.

ITEM_SERVICE_NOT_MISREPRESENTED

Seller's listing accurately represented the item.

ITEM_SERVICE_RECEIVED_BY_BUYER

Buyer received the item or service from the seller.

ITEM_SOLD_AS_DESCRIBED

Item was sold in the condition as described by the seller.

ITEM_VALUE_UNAFFECTED

Item value or usability was not affected significantly.

MULTIPLE_APPEALS_WITH_SAME_REASON

Seller appealed multiple times for the same reason with no additional compelling evidence.

NO_DOCUMENTATION_FROM_BUYER

No documentation received from buyer.

NO_DOCUMENTATION_SUPPORTING_DUE_OF_CREDIT

No documentation given to support that credit is due to buyer.

NO_PROOF_OF_DELIVERY

Seller did not provide proof of delivery.

NO_PROOF_OF_DELIVERY_INTANGIBLE

Seller did not provide proof of fulfillment for a service or digital good.

NO_PROTECTION_FOR_DIGITAL_GOODS_SERVICE

Digital goods, services, or other Intangibles not covered under Protection Policies.

NO_RESPONSE_FROM_BUYER

No response from buyer.

NO_RESPONSE_FROM_BUYER_FOR_ADDITIONAL_INFO_REQUEST

No response from buyer to the request for additional information.

NO_SELLER_RESPONSE

No response from seller.

NO_SELLER_RESPONSE_FOR_ADDITIONAL_INFO_REQUEST

No response from seller to the request for additional information.

NO_VALID_SHIPMENT_PROOF

Seller did not provide valid proof of shipment.

NOT_A_BILLING_ERROR

No evidence of a billing error.

NOT_AN_UNAUTHORIZED_TRANSACTION

No evidence of unauthorized account access was found.

NOT_DUPLICATE_FUNDS_ADDED_ONCE

Funds only added once and no duplication.

NOT_DUPLICATE_FUNDS_WITHDRAWN_ONCE

Funds only withdrawn once and no duplication.

NOT_SHIPPED_TO_CORRECT_ADDRESS

Seller did not ship to correct address.

PARTIAL_REFUND_ISSUED_FOR_MISSING_ITEMS

Seller issued refund for missing items.

PARTIAL_REFUND_OFFER_ACCEPTED

Buyer accepted the partial refund offer.

PAYMENT_REVERSED_ALREADY

Payment was previously refunded or reversed.

POS_SUBMITTED_INSTEAD_OF_POD

Seller submitted proof of shipment instead of proof of delivery.

PREAUTH_INSTALLMENT_DUE

Pre-authorized installment or balance is due to seller.

PROOF_OF_BILLING_AFTER_CANCELLATION_ACCEPTED

Buyer submitted proof of being billed after the billing agreement was cancelled.

PROOF_OF_DUPLICATE_DENIED_OR_INSUFFICIENT

Buyer submitted proof that this was paid by another payment method.

PROOF_OF_INCORRECT_TRANSACTION_AMOUNT_ACCEPTED

Bank or Credit does not match withdrawal amount on PayPal.

PROOF_OF_PAID_BY_OTHER_MEANS_NOT_SUBMITTED

Buyer did not provide sufficient proof of paying by other means.

PROOF_OF_TRACKING_NOT_SUBMITTED

Buyer did not provide sufficient proof of tracking for returns.

PROTECTED_BY_PAYPAL

This case is covered under Seller protection program.

REPRESENTED_BY_PAYPAL

Paypal covered the cost of the case as decided by policy.

SELLER_ACCEPTED_MULTIPLE_PAYMENTS

Seller received multiple payments for the same purchase.

SELLER_AGREED_REFUND_WITHOUT_RETURN

Seller chose to issue a refund without requiring item to be returned.

SELLER_AGREED_TO_ISSUE_CREDIT

Seller agreed to refund the buyer.

SELLER_ISSUED_CREDIT_TO_BUYER

Seller has earlier issued a credit to the buyer for the same transaction.

SELLER_ISSUED_REFUND

Seller has issued a refund.

SELLER_NOT_REACHABLE

Seller could not be reached to resolve case.

SELLER_RECEIVED_PAYMENT_TWICE_OR_FOR_REPLACEMENT

Seller received the payment twice or received payment for a replacement item.

SELLER_REFUSED_REFUND

Seller declined to issue a refund.

SELLER_REFUSED_RETURN

Seller declined to accept return of the item.

SELLER_SURCHARGED_BUYER

Surcharge was assessed to the buyer.

SERVICE_NOT_COMPLETED_AS_AGREED

Service was not completed by seller as per description in the agreement.

SHIPPING_COMPANY_WONT_SHIP

Shipping company refused to ship the item.

TRACKING_PROOF_NOT_ENOUGH

For an item which was significantly not as described, seller cannot appeal with tracking information.

TRANSACTION_AUTHORIZED_BY_CARDHOLDER

Card holder authorized the use of card for the transaction.

TRANSACTION_CANCELLED_AFTER_AUTHORIZATION_DATE

Transaction was cancelled after the authorization date.

TRANSACTION_CANCELLED_BEFORE_SHIPMENT_SERVICE_DATE

Transaction was cancelled before the shipment or service date.

TRANSACTION_MATCHES_BUYER_SPENDING_PATTERN

Transaction similar to recent spending patterns of buyer.

TRANSACTION_PROCESSED_CORRECTLY

Transaction processed correctly.

TRUSTED_BUYER_PAYOUT

Payout to the buyer decided based on their profile and policy.

UNUSED_SHIPPING_LABEL

Shipping label provided was unused.

VALID_PROOF_OF_DELIVERY

Seller provided valid proof of delivery.

VALID_PROOF_OF_DELIVERY_WITH_SIGNATURE

Seller provided valid proof of delivery with signature confirmation.

VALID_PROOF_OF_REFUND

Seller provided valid proof of refund.

VALID_PROOF_SUPPORTING_CLAIM

Buyer provided valid documents to support claim.

VALID_RETURN_DELIVERY_PROOF

Buyer provided valid proof of return delivery.

VALID_RETURN_DELIVERY_PROOF_WITH_SIGNATURE

Buyer provided valid proof of return delivery with signature confirmation.

VALID_SHIPMENT_PROOF

Seller provided valid proof of shipment.

VALUE_AFFECTED_SIGNIFICANTLY

The value of item or usability was affected significantly.

PROTECTION_POLICY_APPLIES

The case is decided based on Protection Policy.

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

The dispute life cycle stage during the adjudication.

Enum: Description
INQUIRY

A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:

  • Has not received goods or a service.
  • Reports that the received goods or service are not as described.
  • Needs more details, such as a copy of the transaction or a receipt.

CHARGEBACK

A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:

  • Accept the claim.
  • Submit evidence to challenge the claim.
  • Make an offer to the customer to resolve the claim.

PRE_ARBITRATION

The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.

ARBITRATION

The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.

{
  • "type": "DENY_BUYER",
  • "adjudication_time": "string",
  • "reason": "AMOUNT_DIFFERENCE_EXPECTED_DUE_TO_FEES",
  • "dispute_life_cycle_stage": "INQUIRY"
}

adjudication_reason

The reason for the adjudication type.

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.

IN_PERSON_DELIVERY

Seller delivered the item in person.

INELIGIBLE_BUYER_PROTECTION_POLICY

The pattern identified does not meet buyer protection eligibility.

INELIGIBLE_SELLER_PROTECTION_POLICY

The pattern identified does not meet seller protection eligibility.

INQUIRY_OFFER_ITEM_REPLACED

Seller agreed to replace the item.

INQUIRY_OFFER_PARTIAL_REFUND

Seller agreed to issue a partial refund to the buyer.

INQUIRY_OFFER_REFUND_WITH_ITEM_RETURN

Seller agreed to issue a refund for item return.

INQUIRY_OFFER_REFUND_WITH_REPLACEMENT

Seller agreed to replace the damaged item along with refunds applicable.

INVALID_APPEAL_REASON

Seller appealed twice for the same reason with invalid reason.

INVALID_CHARGEBACK_SELLER_FAVOUR

The case is decided as invalid based on external network policy.

INVALID_DELIVERY_PROOF

Seller provided invalid proof of delivery.

INVALID_DELIVERY_PROOF_SIGNATURE

Buyer's signature confirmation missing in proof of delivery.

INVALID_DOCUMENTATION

The documentation provided is not valid.

INVALID_PROOF_OF_SHIPMENT

Seller provided invalid proof of shipment.

INVALID_REFUND_PROOF

Seller provided invalid proof of refund.

INVALID_RETURN_DELIVERY_NO_SIGNATURE_PROOF

Seller's signature confirmation missing in proof of return.

INVALID_RETURN_DELIVERY_PROOF

Buyer provided invalid proof of return.

INVALID_TRACKING

Seller provided invalid tracking information.

ITEM_ALTERED_REPAIRED

Item was altered or repaired while in buyer's possession.

ITEM_NOT_AS_ADVERTISED

Item or service provided didn’t match as it was advertised.

ITEM_NOT_AS_DESCRIBED

Item or service provided didn’t match as it was described.

ITEM_NOT_DAMAGED

Item or service provided was not damaged or missing any parts.

ITEM_NOT_DELIVERED

Seller did not deliver the item to the buyer.

ITEM_NOT_RETURNED_TO_SELLER

Item was not returned to seller.

ITEM_NOT_SHIPPED

Seller did not provide verified proof of shipment or delivery.

ITEM_OF_DIFFERENT_QUALITY_OR_QUANTITY

Item sent to the buyer was of different quality, quantity, color, or size.

ITEM_OUT_OF_STOCK_AND_NOT_DELIVERED

Item was not delivered as it was no longer in stock.

ITEM_RETURNED_TO_SELLER

Buyer returned the item to seller.

ITEM_SERVICE_MISREPRESENTED

Seller's listing misrepresented the item.

ITEM_SERVICE_NOT_MISREPRESENTED

Seller's listing accurately represented the item.

ITEM_SERVICE_RECEIVED_BY_BUYER

Buyer received the item or service from the seller.

ITEM_SOLD_AS_DESCRIBED

Item was sold in the condition as described by the seller.

ITEM_VALUE_UNAFFECTED

Item value or usability was not affected significantly.

MULTIPLE_APPEALS_WITH_SAME_REASON

Seller appealed multiple times for the same reason with no additional compelling evidence.

NO_DOCUMENTATION_FROM_BUYER

No documentation received from buyer.

NO_DOCUMENTATION_SUPPORTING_DUE_OF_CREDIT

No documentation given to support that credit is due to buyer.

NO_PROOF_OF_DELIVERY

Seller did not provide proof of delivery.

NO_PROOF_OF_DELIVERY_INTANGIBLE

Seller did not provide proof of fulfillment for a service or digital good.

NO_PROTECTION_FOR_DIGITAL_GOODS_SERVICE

Digital goods, services, or other Intangibles not covered under Protection Policies.

NO_RESPONSE_FROM_BUYER

No response from buyer.

NO_RESPONSE_FROM_BUYER_FOR_ADDITIONAL_INFO_REQUEST

No response from buyer to the request for additional information.

NO_SELLER_RESPONSE

No response from seller.

NO_SELLER_RESPONSE_FOR_ADDITIONAL_INFO_REQUEST

No response from seller to the request for additional information.

NO_VALID_SHIPMENT_PROOF

Seller did not provide valid proof of shipment.

NOT_A_BILLING_ERROR

No evidence of a billing error.

NOT_AN_UNAUTHORIZED_TRANSACTION

No evidence of unauthorized account access was found.

NOT_DUPLICATE_FUNDS_ADDED_ONCE

Funds only added once and no duplication.

NOT_DUPLICATE_FUNDS_WITHDRAWN_ONCE

Funds only withdrawn once and no duplication.

NOT_SHIPPED_TO_CORRECT_ADDRESS

Seller did not ship to correct address.

PARTIAL_REFUND_ISSUED_FOR_MISSING_ITEMS

Seller issued refund for missing items.

PARTIAL_REFUND_OFFER_ACCEPTED

Buyer accepted the partial refund offer.

PAYMENT_REVERSED_ALREADY

Payment was previously refunded or reversed.

POS_SUBMITTED_INSTEAD_OF_POD

Seller submitted proof of shipment instead of proof of delivery.

PREAUTH_INSTALLMENT_DUE

Pre-authorized installment or balance is due to seller.

PROOF_OF_BILLING_AFTER_CANCELLATION_ACCEPTED

Buyer submitted proof of being billed after the billing agreement was cancelled.

PROOF_OF_DUPLICATE_DENIED_OR_INSUFFICIENT

Buyer submitted proof that this was paid by another payment method.

PROOF_OF_INCORRECT_TRANSACTION_AMOUNT_ACCEPTED

Bank or Credit does not match withdrawal amount on PayPal.

PROOF_OF_PAID_BY_OTHER_MEANS_NOT_SUBMITTED

Buyer did not provide sufficient proof of paying by other means.

PROOF_OF_TRACKING_NOT_SUBMITTED

Buyer did not provide sufficient proof of tracking for returns.

PROTECTED_BY_PAYPAL

This case is covered under Seller protection program.

REPRESENTED_BY_PAYPAL

Paypal covered the cost of the case as decided by policy.

SELLER_ACCEPTED_MULTIPLE_PAYMENTS

Seller received multiple payments for the same purchase.

SELLER_AGREED_REFUND_WITHOUT_RETURN

Seller chose to issue a refund without requiring item to be returned.

SELLER_AGREED_TO_ISSUE_CREDIT

Seller agreed to refund the buyer.

SELLER_ISSUED_CREDIT_TO_BUYER

Seller has earlier issued a credit to the buyer for the same transaction.

SELLER_ISSUED_REFUND

Seller has issued a refund.

SELLER_NOT_REACHABLE

Seller could not be reached to resolve case.

SELLER_RECEIVED_PAYMENT_TWICE_OR_FOR_REPLACEMENT

Seller received the payment twice or received payment for a replacement item.

SELLER_REFUSED_REFUND

Seller declined to issue a refund.

SELLER_REFUSED_RETURN

Seller declined to accept return of the item.

SELLER_SURCHARGED_BUYER

Surcharge was assessed to the buyer.

SERVICE_NOT_COMPLETED_AS_AGREED

Service was not completed by seller as per description in the agreement.

SHIPPING_COMPANY_WONT_SHIP

Shipping company refused to ship the item.

TRACKING_PROOF_NOT_ENOUGH

For an item which was significantly not as described, seller cannot appeal with tracking information.

TRANSACTION_AUTHORIZED_BY_CARDHOLDER

Card holder authorized the use of card for the transaction.

TRANSACTION_CANCELLED_AFTER_AUTHORIZATION_DATE

Transaction was cancelled after the authorization date.

TRANSACTION_CANCELLED_BEFORE_SHIPMENT_SERVICE_DATE

Transaction was cancelled before the shipment or service date.

TRANSACTION_MATCHES_BUYER_SPENDING_PATTERN

Transaction similar to recent spending patterns of buyer.

TRANSACTION_PROCESSED_CORRECTLY

Transaction processed correctly.

TRUSTED_BUYER_PAYOUT

Payout to the buyer decided based on their profile and policy.

UNUSED_SHIPPING_LABEL

Shipping label provided was unused.

VALID_PROOF_OF_DELIVERY

Seller provided valid proof of delivery.

VALID_PROOF_OF_DELIVERY_WITH_SIGNATURE

Seller provided valid proof of delivery with signature confirmation.

VALID_PROOF_OF_REFUND

Seller provided valid proof of refund.

VALID_PROOF_SUPPORTING_CLAIM

Buyer provided valid documents to support claim.

VALID_RETURN_DELIVERY_PROOF

Buyer provided valid proof of return delivery.

VALID_RETURN_DELIVERY_PROOF_WITH_SIGNATURE

Buyer provided valid proof of return delivery with signature confirmation.

VALID_SHIPMENT_PROOF

Seller provided valid proof of shipment.

VALUE_AFFECTED_SIGNIFICANTLY

The value of item or usability was affected significantly.

PROTECTION_POLICY_APPLIES

The case is decided based on Protection Policy.

"AMOUNT_DIFFERENCE_EXPECTED_DUE_TO_FEES"

adjudication_type

The type of adjudication.

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.

"DENY_BUYER"

Agreed Refund Details

Details of Agreed Refund between customer and merchant.

merchant_agreed_refund
boolean

Indicates whether merchant has agreed to refund the buyer or not.

merchant_agreed_refund_time
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, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "merchant_agreed_refund": true,
  • "merchant_agreed_refund_time": "string"
}

allowed_response_options

The allowed response options for the buyer/seller update actions.

object (acknowledge_return_item)

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

object (accept_claim)

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

object (make_offer)

The allowed response options when the merchant makes offer to the customer.

{
  • "acknowledge_return_item": {
    • "acknowledgement_types": [
      • "ITEM_RECEIVED"
      ]
    },
  • "accept_claim": {
    • "accept_claim_types": [
      • "REFUND"
      ]
    },
  • "make_offer": {
    • "offer_types": [
      • "REFUND"
      ]
    }
}

billing_disputes_properties

The billing issue details.

object (duplication_transaction)

The duplicate transaction details.

object (incorrect_transaction_amount)

The incorrect transaction amount details.

object (payment_by_other_means)

The payment by other means details.

object (credit_not_processed)

The credit not processed details.

object (canceled_recurring_billing)

The recurring billing canceled details.

{
  • "duplicate_transaction": {
    • "received_duplicate": true,
    • "original_transaction": {
      • "buyer_transaction_id": "string",
      • "seller_transaction_id": "string",
      • "reference_id": "string",
      • "transaction_status": "COMPLETED",
      • "invoice_number": "string",
      • "custom": "string",
      • "items": [
        • {
          • "item_id": "string",
          • "item_name": "string",
          • "item_description": "string",
          • "item_quantity": "string",
          • "partner_transaction_id": "string",
          • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
          • "notes": "string",
          • "item_type": "PRODUCT",
          • "dispute_amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        ],
      • "create_time": "stringstringstringst",
      • "gross_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "gross_asset": {
        • "asset_symbol": "BTC",
        • "quantity": "string"
        },
      • "buyer": {
        • "name": "string"
        },
      • "seller": {
        • "merchant_id": "string",
        • "name": "string",
        • "email": "string"
        }
      }
    },
  • "incorrect_transaction_amount": {
    • "correct_transaction_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "correct_transaction_asset": {
      • "asset_symbol": "BTC",
      • "quantity": "string"
      },
    • "correct_transaction_time": "string"
    },
  • "payment_by_other_means": {
    • "charge_different_from_original": true,
    • "received_duplicate": true,
    • "payment_method": "CASH",
    • "payment_instrument_suffix": "stri"
    },
  • "credit_not_processed": {
    • "issue_type": "PRODUCT",
    • "agreed_refund_details": {
      • "merchant_agreed_refund": true,
      • "merchant_agreed_refund_time": "string"
      },
    • "expected_refund": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "cancellation_details": {
      • "cancellation_number": "string",
      • "cancelled": true,
      • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
      • "cancellation_date": "string"
      },
    • "product_details": {
      • "description": "string",
      • "product_received": "YES",
      • "sub_reasons": [
        • "string"
        ],
      • "purchase_url": "http://example.com",
      • "product_received_time": "string",
      • "expected_delivery_date": "string",
      • "return_details": {
        • "mode": "SHIPPED",
        • "receipt": true,
        • "return_confirmation_number": "string",
        • "returned": true,
        • "return_time": "string"
        }
      },
    • "service_details": {
      • "description": "string",
      • "service_started": "YES",
      • "note": "string",
      • "sub_reasons": [
        • "string"
        ],
      • "purchase_url": "http://example.com"
      }
    },
  • "canceled_recurring_billing": {
    • "expected_refund": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "cancellation_details": {
      • "cancellation_number": "string",
      • "cancelled": true,
      • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
      • "cancellation_date": "string"
      }
    }
}

buyer

The details for the customer who funds the payment. For example, the customer's first name, last name, and email address.

name
string [ 1 .. 2000 ] characters ^[^~!@#$%^*()_{}:|\t\n/]+$

The customer's name.

{
  • "name": "string"
}

canceled_recurring_billing

The recurring billing canceled details.

object (Money)

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

object (cancellation_details)

The cancellation details.

{
  • "expected_refund": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "cancellation_details": {
    • "cancellation_number": "string",
    • "cancelled": true,
    • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
    • "cancellation_date": "string"
    }
}

cancellation_details

The cancellation details.

cancellation_number
string [ 1 .. 127 ] characters ^[A-Za-z0-9]+$

The cancellation number.

cancelled
boolean

Indicates whether the dispute was canceled.

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

Indicates the mode used for order cancellation.

Enum: Description
CANCELLED_PAYPAL_BILLING_AGREEMENT

Cancelled the billing agreement.

WEBSITE

The item was cancelled on the merchant's website.

PHONE

The item was cancelled through either phone or fax.

EMAIL

The item was cancelled through either email or text message.

WRITTEN

The item was cancelled via written communication.

IN_PERSON

The item was cancelled in person.

cancellation_date
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 of the cancellation, in Internet date and time format.

{
  • "cancellation_number": "string",
  • "cancelled": true,
  • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
  • "cancellation_date": "string"
}

cancellation_reason

The reason the customer cancelled the dispute.

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

The reason the customer cancelled the dispute.

Enum: Description
ITEM_RECEIVED

The customer already received the item.

REFUND_RECEIVED

The customer already received a refund for the item.

OTHER

The customer cancelled the dispute for another reason. If OTHER is specified, customer needs to specify more information in the notes field.

SHIPMENT_INFO_RECEIVED

The customer received the provided shipping tracking information and agrees to cancel.

REPLACEMENT_RECEIVED

The customer received the item replacement and agrees to cancel.

"ITEM_RECEIVED"

communication_details

The contact details that a merchant provides to the customer to use to share their evidence documents.

note
string [ 1 .. 2000 ] characters

The merchant provided notes that are visible to both the customer and PayPal.

email
string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

time_posted
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, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "note": "string",
  • "email": "string",
  • "time_posted": "string"
}

country_code

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

credit_not_processed

The credit not processed details.

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

The issue type.

Enum: Description
PRODUCT

The product has an issue.

SERVICE

The service has an issue.

object (Agreed Refund Details)

Details of Agreed Refund between customer and merchant.

object (Money)

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

object (cancellation_details)

The cancellation details.

object (product_details)

The product information.

object (service_details)

The service details.

{
  • "issue_type": "PRODUCT",
  • "agreed_refund_details": {
    • "merchant_agreed_refund": true,
    • "merchant_agreed_refund_time": "string"
    },
  • "expected_refund": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "cancellation_details": {
    • "cancellation_number": "string",
    • "cancelled": true,
    • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
    • "cancellation_date": "string"
    },
  • "product_details": {
    • "description": "string",
    • "product_received": "YES",
    • "sub_reasons": [
      • "string"
      ],
    • "purchase_url": "http://example.com",
    • "product_received_time": "string",
    • "expected_delivery_date": "string",
    • "return_details": {
      • "mode": "SHIPPED",
      • "receipt": true,
      • "return_confirmation_number": "string",
      • "returned": true,
      • "return_time": "string"
      }
    },
  • "service_details": {
    • "description": "string",
    • "service_started": "YES",
    • "note": "string",
    • "sub_reasons": [
      • "string"
      ],
    • "purchase_url": "http://example.com"
    }
}

Crypto trade details

The Crypto trade details.

trade_id
string [ 1 .. 255 ] characters ^[A-Za-z0-9]+$

The Trade id for the crypto-currency order.

{
  • "trade_id": "string"
}

Cryptocurrency

Representation of a specific amount of Cryptocurrency, denoted by its symbol and quantity.

asset_symbol
required
string (cryptocurrency_symbol) [ 1 .. 10 ] characters ^[0-9A-Za-z]{1,10}$

The Cryptocurrency ticker symbol / code as assigned by liquidity providers (exchanges).

Enum: Description
BTC

The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin

ETH

The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum

BCH

The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash

LTC

The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin

quantity
required
string (cryptocurrency_quantity) [ 1 .. 40 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Quantity of a cryptocurrency asset.
This is a decimal number with scale defined for each Cryptocurrency by the founders. For example,

  • Bitcoin(BTC) has 8 as scale,
  • Ethereum (ETH) has 18 as scale.

  • PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ehereum.

    {
    • "asset_symbol": "BTC",
    • "quantity": "string"
    }

    cryptocurrency_quantity

    Quantity of a cryptocurrency asset.
    This is a decimal number with scale defined for each Cryptocurrency by the founders. For example,

  • Bitcoin(BTC) has 8 as scale,
  • Ethereum (ETH) has 18 as scale.

  • PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ehereum.

    string (cryptocurrency_quantity) [ 1 .. 40 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

    Quantity of a cryptocurrency asset.
    This is a decimal number with scale defined for each Cryptocurrency by the founders. For example,

  • Bitcoin(BTC) has 8 as scale,
  • Ethereum (ETH) has 18 as scale.

  • PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ehereum.

    "string"

    cryptocurrency_symbol

    The Cryptocurrency ticker symbol / code as assigned by liquidity providers (exchanges).

    string (cryptocurrency_symbol) [ 1 .. 10 ] characters ^[0-9A-Za-z]{1,10}$

    The Cryptocurrency ticker symbol / code as assigned by liquidity providers (exchanges).

    Enum: Description
    BTC

    The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin

    ETH

    The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum

    BCH

    The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash

    LTC

    The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin

    "BTC"

    currency_code

    The three-character ISO-4217 currency code that identifies the currency.

    string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

    The three-character ISO-4217 currency code that identifies the currency.

    "str"

    date_time

    The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

    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, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

    "stringstringstringst"

    deny_offer

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

    note
    required
    string [ 1 .. 2000 ] characters

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

    {
    • "note": "string"
    }

    dispute

    The dispute details.

    dispute_id
    string [ 1 .. 255 ] characters ^[A-Za-z0-9-]+$

    The ID of the dispute.

    Array of objects (transaction_info) [ 1 .. 1000 ] items

    An array of transactions for which disputes were created.

    external_reason_code
    string [ 1 .. 2000 ] characters

    The code that identifies the reason for the credit card chargeback. Each card issuer follows their own standards for defining reason type, code, and its format. For more details about the external reason code, see the card issue site. Available for only unbranded transactions.

    Array of objects (adjudication) [ 1 .. 10 ] items

    The Teammate Adjudication details for the dispute.

    Array of objects (money_movement) [ 1 .. 50 ] items

    The Money movement details for the dispute.

    Array of objects (message) [ 1 .. 1000 ] items

    An array of customer- or merchant-posted messages for the dispute.

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

    An array of evidence documents.

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

    An array of all the supporting information that are associated to this dispute.

    Array of objects (Link Description) [ 1 .. 10 ] items

    An array of request-related HATEOAS links.

    create_time
    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, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

    update_time
    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, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

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

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons.

    Enum: Description
    MERCHANDISE_OR_SERVICE_NOT_RECEIVED

    The customer did not receive the merchandise or service.

    MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED

    The customer reports that the merchandise or service is not as described.

    UNAUTHORISED

    The customer did not authorize purchase of the merchandise or service.

    CREDIT_NOT_PROCESSED

    The refund or credit was not processed for the customer.

    DUPLICATE_TRANSACTION

    The transaction was a duplicate.

    INCORRECT_AMOUNT

    The customer was charged an incorrect amount.

    PAYMENT_BY_OTHER_MEANS

    The customer paid for the transaction through other means.

    CANCELED_RECURRING_BILLING

    The customer was being charged for a subscription or a recurring transaction that was canceled.

    PROBLEM_WITH_REMITTANCE

    A problem occurred with the remittance.

    OTHER

    Other.

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

    The overall status of the dispute, constant for all the parties involved at anytime during the dispute lifecycle.

    Enum: Description
    OPEN

    The dispute is open.

    WAITING_FOR_BUYER_RESPONSE

    The dispute is waiting for a response from the customer.

    WAITING_FOR_SELLER_RESPONSE

    The dispute is waiting for a response from the merchant.

    UNDER_REVIEW

    The dispute is under review with PayPal.

    RESOLVED

    The dispute is resolved.

    OTHER

    The default status if the dispute does not have one of the other statuses.

    object (Money)

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

    object (Cryptocurrency)

    The asset in the transaction that the customer disputed.

    fee_policy
    object (Fee Policy)

    Policy that determines whether the fee needs to be charged, retained or returned while moving the money as part of dispute process.

    object (dispute_outcome)

    The outcome of a dispute.

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

    The stage in the dispute lifecycle.

    Enum: Description
    INQUIRY

    A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:

    • Has not received goods or a service.
    • Reports that the received goods or service are not as described.
    • Needs more details, such as a copy of the transaction or a receipt.

    CHARGEBACK

    A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:

    • Accept the claim.
    • Submit evidence to challenge the claim.
    • Make an offer to the customer to resolve the claim.

    PRE_ARBITRATION

    The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.

    ARBITRATION

    The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.

    dispute_channel
    string (dispute_channel) [ 1 .. 255 ] characters

    The channel where the customer created the dispute.

    Enum: Description
    INTERNAL

    The customer contacts PayPal to file a dispute with the merchant.

    EXTERNAL

    The customer contacts their card issuer or bank to request a refund.

    ALERT

    Pre-chargeback alert when customer contacts their card issuer to request a refund.

    object (extensions)

    The extended properties for the dispute. Includes additional information for a dispute category, such as billing disputes, the original transaction ID, and the correct amount.

    buyer_response_due_date
    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, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

    seller_response_due_date
    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, in Internet date and time format. Seconds are required while fractional seconds are optional.

    Note: The regular expression provides guidance but does not reject all invalid dates.

    object (offer)

    The merchant-proposed offer for a dispute.

    object (response_refund_details)

    The refund details.

    object (communication_details)

    The contact details that a merchant provides to the customer to use to share their evidence documents.

    object (allowed_response_options)

    The allowed response options for the buyer/seller update actions.

    {
    • "dispute_id": "string",
    • "disputed_transactions": [
      • {
        • "buyer_transaction_id": "string",
        • "seller_transaction_id": "string",
        • "reference_id": "string",
        • "transaction_status": "COMPLETED",
        • "invoice_number": "string",
        • "custom": "string",
        • "items": [
          • {
            • "item_id": "string",
            • "item_name": "string",
            • "item_description": "string",
            • "item_quantity": "string",
            • "partner_transaction_id": "string",
            • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
            • "notes": "string",
            • "item_type": "PRODUCT",
            • "dispute_amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "create_time": "stringstringstringst",
        • "gross_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "gross_asset": {
          • "asset_symbol": "BTC",
          • "quantity": "string"
          },
        • "buyer": {
          • "name": "string"
          },
        • "seller": {
          • "merchant_id": "string",
          • "name": "string",
          • "email": "string"
          }
        }
      ],
    • "external_reason_code": "string",
    • "adjudications": [
      • {
        • "type": "DENY_BUYER",
        • "adjudication_time": "string",
        • "reason": "AMOUNT_DIFFERENCE_EXPECTED_DUE_TO_FEES",
        • "dispute_life_cycle_stage": "INQUIRY"
        }
      ],
    • "money_movements": [
      • {
        • "affected_party": "SELLER",
        • "type": "DEBIT",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "asset": {
          • "asset_symbol": "BTC",
          • "quantity": "string"
          },
        • "initiated_time": "string",
        • "reason": "DISPUTE_SETTLEMENT_FEE"
        }
      ],
    • "messages": [
      • {
        • "posted_by": "BUYER",
        • "content": "string",
        • "documents": [
          • {
            • "name": "string",
            • "url": "http://example.com"
            }
          ],
        • "time_posted": "string"
        }
      ],
    • "evidences": [
      • {
        • "evidence_type": "PROOF_OF_FULFILLMENT",
        • "documents": [
          • {
            • "name": "string",
            • "url": "http://example.com"
            }
          ],
        • "notes": "string",
        • "source": "REQUESTED_FROM_BUYER",
        • "item_id": "string",
        • "evidence_info": {
          • "tracking_info": [
            • {
              • "carrier_name": "UPS",
              • "carrier_name_other": "string",
              • "tracking_url": "http://example.com",
              • "tracking_number": "string"
              }
            ],
          • "refund_ids": [
            • "string"
            ]
          },
        • "date": "string",
        • "item_type": "PRODUCT",
        • "action_info": {
          • "action": "ACKNOWLEDGE_RETURN_ITEM",
          • "response_option": "string",
          • "mandatory": true
          },
        • "dispute_life_cycle_stage": "INQUIRY"
        }
      ],
    • "supporting_info": [
      • {
        • "notes": "string",
        • "documents": [
          • {
            • "name": "string",
            • "url": "http://example.com"
            }
          ],
        • "source": "SUBMITTED_BY_BUYER",
        • "provided_time": "string",
        • "dispute_life_cycle_stage": "INQUIRY"
        }
      ],
    • "links": [
      • {
        • "href": "string",
        • "rel": "string",
        • "method": "GET"
        }
      ],
    • "create_time": "string",
    • "update_time": "string",
    • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
    • "status": "OPEN",
    • "dispute_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "dispute_asset": {
      • "asset_symbol": "BTC",
      • "quantity": "string"
      },
    • "fee_policy": { },
    • "dispute_outcome": {
      • "outcome_code": "RESOLVED_BUYER_FAVOUR",
      • "amount_refunded": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "asset_refunded": {
        • "asset_symbol": "BTC",
        • "quantity": "string"
        }
      },
    • "dispute_life_cycle_stage": "INQUIRY",
    • "dispute_channel": "INTERNAL",
    • "extensions": {
      • "merchant_contacted": true,
      • "buyer_contacted_channel": "string",
      • "merchant_contacted_outcome": "NO_RESPONSE",
      • "merchant_contacted_time": "string",
      • "merchant_contacted_mode": "WEBSITE",
      • "buyer_contacted_time": "string",
      • "billing_dispute_properties": {
        • "duplicate_transaction": {
          • "received_duplicate": true,
          • "original_transaction": {
            • "buyer_transaction_id": "string",
            • "seller_transaction_id": "string",
            • "reference_id": "string",
            • "transaction_status": "COMPLETED",
            • "invoice_number": "string",
            • "custom": "string",
            • "items": [
              • {
                • "item_id": "string",
                • "item_name": "string",
                • "item_description": "string",
                • "item_quantity": "string",
                • "partner_transaction_id": "string",
                • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
                • "notes": "string",
                • "item_type": "PRODUCT",
                • "dispute_amount": {
                  • "currency_code": null,
                  • "value": null
                  }
                }
              ],
            • "create_time": "stringstringstringst",
            • "gross_amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "gross_asset": {
              • "asset_symbol": "BTC",
              • "quantity": "string"
              },
            • "buyer": {
              • "name": "string"
              },
            • "seller": {
              • "merchant_id": "string",
              • "name": "string",
              • "email": "string"
              }
            }
          },
        • "incorrect_transaction_amount": {
          • "correct_transaction_amount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "correct_transaction_asset": {
            • "asset_symbol": "BTC",
            • "quantity": "string"
            },
          • "correct_transaction_time": "string"
          },
        • "payment_by_other_means": {
          • "charge_different_from_original": true,
          • "received_duplicate": true,
          • "payment_method": "CASH",
          • "payment_instrument_suffix": "stri"
          },
        • "credit_not_processed": {
          • "issue_type": "PRODUCT",
          • "agreed_refund_details": {
            • "merchant_agreed_refund": true,
            • "merchant_agreed_refund_time": "string"
            },
          • "expected_refund": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "cancellation_details": {
            • "cancellation_number": "string",
            • "cancelled": true,
            • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
            • "cancellation_date": "string"
            },
          • "product_details": {
            • "description": "string",
            • "product_received": "YES",
            • "sub_reasons": [
              • "string"
              ],
            • "purchase_url": "http://example.com",
            • "product_received_time": "string",
            • "expected_delivery_date": "string",
            • "return_details": {
              • "mode": "SHIPPED",
              • "receipt": true,
              • "return_confirmation_number": "string",
              • "returned": true,
              • "return_time": "string"
              }
            },
          • "service_details": {
            • "description": "string",
            • "service_started": "YES",
            • "note": "string",
            • "sub_reasons": [
              • "string"
              ],
            • "purchase_url": "http://example.com"
            }
          },
        • "canceled_recurring_billing": {
          • "expected_refund": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "cancellation_details": {
            • "cancellation_number": "string",
            • "cancelled": true,
            • "cancellation_mode": "CANCELLED_PAYPAL_BILLING_AGREEMENT",
            • "cancellation_date": "string"
            }
          }
        },
      • "merchandize_dispute_properties": {
        • "issue_type": "PRODUCT",
        • "product_details": {
          • "description": "string"