Customer Disputes API

Important: PayPal Customer Disputes API is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

PayPal merchants, partners, and external developers can use the PayPal Customer Disputes API to list disputes, provide evidence, accept claims, show dispute details, and appeal disputes.

Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can file a case with PayPal or ask his or her bank or credit card company to reverse a charge. A charge reversal is also known as a chargeback. For more information, see Disputes, claims, chargebacks, and bank reversals.
Note: Merchants cannot create disputes but can only respond to customer-created disputes.

When a customer disputes your charge, you can provide evidence to show that the charge is legitimate. To provide new evidence or appeal a dispute, you submit a proof of delivery or proof of refund document or notes, which can include logs.
For details, see Customer Disputes and the Marketplace Disputes Integration Guide.

Disputes (resource group)

Use the /customer/disputes/ resource to list all or a filtered set of disputes, provide evidence, accept a claim, show dispute details, and appeal disputes.

List disputes

GET /v1/customer/disputes
Lists disputes. 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.

Query parameters

  • start_time

    string

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

    string

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

    integer

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

    Default: 10.

    Minimum value: 1.

    Maximum value: 50.

  • next_page_token

    string

    The token that describes the next page of results to fetch. This token comes from the response of another API call. If you omit this parameter, the API returns the first page of data.
  • total_required

    boolean

    Indicates whether to include the total number of items in the response.
  • dispute_state

    enum

    Filters the disputes that are returned in the response by a state.

    Allowed values: REQUIRED_ACTION, REQUIRED_OTHER_PARTY_ACTION, UNDER_PAYPAL_REVIEW, RESOLVED, OPEN_INQUIRIES.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=965038709E474252Y \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists disputes with the dispute_id, reason, status, dispute_amount, create_time, and update_time fields for each dispute.
  • items

    array (contains the dispute object)

    An array of disputes that match the filter criteria. Sorted from latest to earliest creation time order.
  • total_items

    integer

    The total number of items. If total_required=true was specified in the request, appears in the response.

    Read only.

  • total_pages

    integer

    The total number of pages. If total_required=true was specified in the request, appears in the response.

    Read only.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "items": [
    {
      "dispute_id": "PP-000-003-648-051",
      "create_time": "2017-01-24T05:54:03.000Z",
      "update_time": "2017-01-26T09:61:11.000Z",
      "disputed_transactions": [
        {
          "buyer_transaction_id": "965038709E474252Y",
          "seller_transaction_id": "3VU62368U29897744",
          "create_time": "2017-01-24T05:52:11.000Z",
          "transaction_status": "COMPLETED",
          "gross_amount": {
            "currency_code": "GBP",
            "value": "10.00"
          },
          "buyer": {
            "email": "buyer@example.com",
            "name": "June Buyer"
          },
          "seller": {
            "email": "merchant@example.com",
            "merchant_id": "MDLV8MPZEEXVJ",
            "name": "Total Attraction"
          }
        }
      ],
      "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
      "status": "RESOLVED",
      "dispute_amount": {
        "currency_code": "GBP",
        "value": "10.00"
      },
      "dispute_outcome": {
        "outcome_code": "RESOLVED_SELLER_FAVOUR"
      },
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-051",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=965038709E474252Y",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=965038709E474252Y",
      "rel": "first",
      "method": "GET"
    }
  ]
}

Show dispute details

GET /v1/customer/disputes/{dispute_id}
Shows details for a dispute, by ID.
Note: The fields that appear in the response depend on whether you access this call through first- or third-party access. For example, if the merchant shows dispute details through third-party access, the customer's email ID does not appear.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute for which to show details.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-191 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body with dispute details.
  • dispute_id

    string

    The ID of the dispute.

    Read only.

  • create_time

    string

    The date and time when the dispute was created, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • update_time

    string

    The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • disputed_transactions

    array (contains the transaction_info object)

    An array of transactions for which the disputes were created.
  • reason

    enum

    The reason for the item-level dispute. Value is:
    • 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 was not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit wasn't 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.
    For information about the required information for each dispute reason and associated evidence type, see dispute reason codes.

    Possible values: MERCHANDISE_OR_SERVICE_NOT_RECEIVED, MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED, UNAUTHORISED, CREDIT_NOT_PROCESSED, DUPLICATE_TRANSACTION, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, CANCELED_RECURRING_BILLING, PROBLEM_WITH_REMITTANCE, OTHER.

  • status

    enum

    The status of the dispute. Value is:
    • OPEN. 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.
    • RESOLVED. The dispute is resolved.
    • OTHER. Another reason.

    Read only.

    Possible values: OPEN, WAITING_FOR_BUYER_RESPONSE, WAITING_FOR_SELLER_RESPONSE, UNDER_REVIEW, RESOLVED, OTHER.

  • dispute_amount

    object

    The amount in the transaction that the customer originally disputed. Because customers can sometimes dispute only part of the payment, the disputed amount might be different from the total gross or net amount of the original transaction.
  • dispute_outcome

    object

    The outcome of a dispute.

    Read only.

  • messages

    array (contains the message object)

    An array of messages that were posted by the customer and merchant.
  • seller_response_due_date

    string

    The date and time by when the merchant must respond to the dispute, in Internet date and time format. If the merchant does not respond by this date and time, the dispute is closed in the customer's favor. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • offer

    object

    The information for the offer that a buyer or seller proposes for the dispute.

    Read only.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "dispute_id": "PP-000-003-648-191",
  "create_time": "2017-01-24T10:41:35.000Z",
  "update_time": "2017-01-24T11:40:32.000Z",
  "disputed_transactions": [
    {
      "buyer_transaction_id": "965038709E474252Y",
      "seller_transaction_id": "3VU62368U29897744",
      "create_time": "2017-01-24T05:52:11.000Z",
      "transaction_status": "COMPLETED",
      "gross_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "buyer": {
        "email": "buyer@example.com",
        "name": "June Buyer"
      },
      "seller": {
        "email": "merchant@example.com",
        "merchant_id": "MDLV8MPZEEXVJ",
        "name": "Total Attraction"
      }
    }
  ],
  "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
  "status": "WAITING_FOR_SELLER_RESPONSE",
  "dispute_amount": {
    "currency_code": "USD",
    "value": "50.00"
  },
  "offer": {
    "buyer_requested_amount": {
      "currency_code": "USD",
      "value": "50.00"
    }
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-191",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Accept claim

POST /v1/customer/disputes/{dispute_id}/accept-claim
Accepts a claim for a dispute, by ID. Accepts liability for a claim, which closes the dispute in the customer’s favor. PayPal refunds money to the customer from the merchant's account.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • note

    string

    The merchant's notes about acceptance of the customer's claim.

    Minimum length: 1.

    Maximum length: 2000.

  • accept_claim_reason

    enum

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

    Allowed values: DID_NOT_SHIP_ITEM, TOO_TIME_CONSUMING, LOST_IN_MAIL, NOT_ABLE_TO_WIN, COMPANY_POLICY, REASON_NOT_SET.

  • invoice_id

    string

    The ID of the invoice for the refund.
  • return_shipping_address

    object

    The address to which to return the item to process the refund.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/accept-claim \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Refund to the customer."
}'

Response

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

Sample Response

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

Settle dispute

POST /v1/customer/disputes/{dispute_id}/adjudicate
Settles a dispute, by ID, in either the buyer's or seller's favor.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute to settle.

Request body

  • adjudication_outcome

    enum

    The outcome of the adjudication.

    Allowed values: BUYER_FAVOR, SELLER_FAVOR.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/adjudicate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "adjudication_outcome": "BUYER_FAVOR"
}'

Response

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

Sample Response

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

Appeal dispute

POST /v1/customer/disputes/{dispute_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.

Path parameters

  • dispute_id

    string

    required

    The PayPal dispute ID.

Request body

  • evidences

    array (contains the evidence object)

    An array of evidences for the dispute.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \
-H "Content-Type: multipart/related" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "evidences": [
  {
    "item_id": "12345",
    "notes": "Consider the following evidence.",
    "evidence_info": {
    "tracking_info": [
      {
      "tracking_number": "ABX123",
      "carrier_name": "DHL"
      }
    ]
    }
  }
  ]
}'

Response

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

Sample Response

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

Provide evidence

POST /v1/customer/disputes/{dispute_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. The following rules apply to document file types and sizes:
  • The seller can upload up to 10 MB of files for a case.
  • Individual files must be smaller than 5 MB.
  • The supported file formats are JPG, GIF, PNG, and PDF.

To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute for which to submit evidence.

FormData parameters

  • evidence

    file

    required

    A file with evidence.

Sample Request

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

Response

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

Sample Response

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

Update dispute state

POST /v1/customer/disputes/{dispute_id}/require-evidence
Updates the state of a dispute, by ID, to either WAITING_FOR_BUYER_RESPONSE or WAITING_FOR_SELLER_RESPONSE. This state change enables either the buyer or seller to submit evidence for the dispute. If the action is BUYER_EVIDENCE, the state updates to WAITING_FOR_BUYER_RESPONSE. If the action is ,SELLER_EVIDENCE, the state updates to WAITING_FOR_SELLER_RESPONSE.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute that requires evidence.

Request body

  • action

    enum

    The action to complete.

    Allowed values: BUYER_EVIDENCE, SELLER_EVIDENCE.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/require-evidence \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "action": "BUYER_EVIDENCE"
}'

Response

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

Sample Response

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

Common object definitions

accept_claim_request

  • note

    string

    The merchant's notes about acceptance of the customer's claim.

    Minimum length: 1.

    Maximum length: 2000.

  • accept_claim_reason

    enum

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

    Possible values: DID_NOT_SHIP_ITEM, TOO_TIME_CONSUMING, LOST_IN_MAIL, NOT_ABLE_TO_WIN, COMPANY_POLICY, REASON_NOT_SET.

  • invoice_id

    string

    The ID of the invoice for the refund.
  • return_shipping_address

    object

    The address to which to return the item to process the refund.

address_details

  • street_number

    string

    The street number.

    Maximum length: 300.

  • street_name

    string

    The street name. Just Drury in Drury Lane.

    Maximum length: 300.

  • street_type

    string

    The street type. For example, avenue, boulevard, road, or expressway.

    Maximum length: 300.

  • delivery_service

    string

    The delivery service. Post office box, bag number, or post office name.

    Maximum length: 300.

  • building_name

    string

    A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.

    Maximum length: 300.

  • sub_building

    string

    The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.

    Maximum length: 300.

address_portable

  • address_line_1

    string

    The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

    Maximum length: 300.

  • address_line_2

    string

    The second line of the address. For example, suite or apartment number.

    Maximum length: 300.

  • address_line_3

    string

    The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

    Maximum length: 300.

  • admin_area_4

    string

    The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
    • The postal sorting code that is used in Guernsey and many French territories, such as French Guiana.
    • The fine-grained administrative levels in China.

    Maximum length: 300.

  • admin_area_3

    string

    A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
    • Brazil. Suburb, bairro, or neighborhood.
    • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

    Maximum length: 300.

  • admin_area_2

    string

    A city, town, or village. Smaller than admin_area_level_1.

    Maximum length: 300.

  • admin_area_1

    string

    The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
    • UK. A county.
    • US. A state.
    • Canada. A province.
    • Japan. A prefecture.
    • Switzerland. A kanton.

    Maximum length: 300.

  • postal_code

    string

    The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

    Maximum length: 60.

  • country_code

    string

    required

    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.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • address_details

    object

    The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and opensource. Redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number and street_name and street_type.

adjudicate_request

  • adjudication_outcome

    enum

    The outcome of the adjudication.

    Possible values: BUYER_FAVOR, SELLER_FAVOR.

buyer

  • email

    string

    The email address that is associated with the customer's PayPal account.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • name

    string

    The customer's name.

cancel_request

  • note

    string

    Optional. A note.

    Maximum length: 1048576.

  • transaction_ids

    array (contains the transaction_id object)

    An array of encrypted transaction IDs for a canceled unauthorized dispute. If you omit this ID for unauthorized disputes, the issue is automatically canceled. Optional for other dispute types.

change_reason_request

  • reason

    object

    The reason for the item-level dispute. Value is:
    • 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 was not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit wasn't 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.
    For information about the required information for each dispute reason and associated evidence type, see dispute reason codes.
  • note

    string

    Optional. A note.

    Maximum length: 1048576.

  • transaction_ids

    array (contains the transaction_id object)

    An array of transaction IDs to add to the unauthorized issue.

country_code

  • country_code

    string

    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.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

currency_code

date_time

  • date_time

    string

    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.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

dispute

  • dispute_id

    string

    The ID of the dispute.

    Read only.

  • create_time

    string

    The date and time when the dispute was created, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • update_time

    string

    The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • disputed_transactions

    array (contains the transaction_info object)

    An array of transactions for which the disputes were created.
  • reason

    enum

    The reason for the item-level dispute. Value is:
    • 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 was not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit wasn't 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.
    For information about the required information for each dispute reason and associated evidence type, see dispute reason codes.

    Possible values: MERCHANDISE_OR_SERVICE_NOT_RECEIVED, MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED, UNAUTHORISED, CREDIT_NOT_PROCESSED, DUPLICATE_TRANSACTION, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, CANCELED_RECURRING_BILLING, PROBLEM_WITH_REMITTANCE, OTHER.

  • status

    enum

    The status of the dispute. Value is:
    • OPEN. 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.
    • RESOLVED. The dispute is resolved.
    • OTHER. Another reason.

    Read only.

    Possible values: OPEN, WAITING_FOR_BUYER_RESPONSE, WAITING_FOR_SELLER_RESPONSE, UNDER_REVIEW, RESOLVED, OTHER.

  • dispute_amount

    object

    The amount in the transaction that the customer originally disputed. Because customers can sometimes dispute only part of the payment, the disputed amount might be different from the total gross or net amount of the original transaction.
  • dispute_outcome

    object

    The outcome of a dispute.

    Read only.

  • messages

    array (contains the message object)

    An array of messages that were posted by the customer and merchant.
  • seller_response_due_date

    string

    The date and time by when the merchant must respond to the dispute, in Internet date and time format. If the merchant does not respond by this date and time, the dispute is closed in the customer's favor. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

    Read only.

    Minimum length: 20.

    Maximum length: 64.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

  • offer

    object

    The information for the offer that a buyer or seller proposes for the dispute.

    Read only.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

dispute_create_response

dispute_outcome

  • outcome_code

    enum

    The outcome of a resolved dispute. Value is:
    • RESOLVED_BUYER_FAVOUR. The dispute was resolved in the customer's favor.
    • RESOLVED_SELLER_FAVOUR. The dispute was resolved in the merchant's favor.
    • RESOLVED_WITH_PAYOUT. PayPal provided the merchant or customer with protection and the case is resolved.
    • CANCELED_BY_BUYER. The customer canceled the dispute.
    • ACCEPTED. The dispute was accepted.
    • DENIED. The dispute was denied.
    • Empty. The dispute was not resolved.

    Possible values: RESOLVED_BUYER_FAVOUR, RESOLVED_SELLER_FAVOUR, RESOLVED_WITH_PAYOUT, CANCELED_BY_BUYER, ACCEPTED, DENIED.

  • amount_refunded

    object

    The amount that either the merchant or PayPal refunds the customer.

dispute_reason

  • dispute_reason

    enum

    The reason for the item-level dispute. Value is:
    • 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 was not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit wasn't 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.
    For information about the required information for each dispute reason and associated evidence type, see dispute reason codes.

    Possible values: MERCHANDISE_OR_SERVICE_NOT_RECEIVED, MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED, UNAUTHORISED, CREDIT_NOT_PROCESSED, DUPLICATE_TRANSACTION, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, CANCELED_RECURRING_BILLING, PROBLEM_WITH_REMITTANCE, OTHER.

dispute_search_response

  • items

    array (contains the dispute object)

    An array of disputes that match the filter criteria. Sorted from latest to earliest creation time order.
  • total_items

    integer

    The total number of items. If total_required=true was specified in the request, appears in the response.

    Read only.

  • total_pages

    integer

    The total number of pages. If total_required=true was specified in the request, appears in the response.

    Read only.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

disputes_change_reason_response

document

  • name

    string

    The document name.
  • size

    string

    The document size.
  • url

    string

    The document URI.

    Read only.

eligibility_request

  • encrypted_transaction_id

    string

    The encrypted transaction ID. The response lists the eligible and ineligible dispute reasons.
  • dispute_id

    string

    The ID of the dispute. The response lists the eligible and ineligible dispute reasons; the eligible reasons are the ones to which the customer can update the dispute.

email_address

  • email_address

    string

    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.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

error

  • name

    string

    required

    The human-readable, unique name of the error.
  • message

    string

    required

    The message that describes the error.
  • debug_id

    string

    required

    The PayPal internal ID that is used for correlation purposes.
  • information_link

    string

    The information link, or URI, that shows detailed information about this error for the developer.

    Read only.

  • details

    array (contains the error_details object)

    An array of additional details about the error.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

error_details

  • field

    string

    The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
  • value

    string

    The value of the field that caused the error.
  • location

    string

    The location of the field that caused the error. A valid value is body, path, or query. Default is body.
  • issue

    string

    required

    The unique and fine-grained application-level error code.
  • description

    string

    The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.

evidence

  • evidence_type

    enum

    The type of evidence.

    Possible values: PROOF_OF_FULFILLMENT, PROOF_OF_REFUND, PROOF_OF_DELIVERY_SIGNATURE, PROOF_OF_RECEIPT_COPY, RETURN_POLICY, BILLING_AGREEMENT, PROOF_OF_RESHIPMENT, ITEM_DESCRIPTION, POLICE_REPORT, AFFIDAVIT, PAID_WITH_OTHER_METHOD, COPY_OF_CONTRACT, TERMINAL_ATM_RECEIPT, PRICE_DIFFERENCE_REASON, SOURCE_CONVERSION_RATE, BANK_STATEMENT, CREDIT_DUE_REASON, REQUEST_CREDIT_RECEIPT, PROOF_OF_RETURN, CREATE, CHANGE_REASON, OTHER.

  • evidence_info

    object

    The evidence-related information.
  • documents

    array (contains the document object)

    An array of documents that were submitted as evidence.
  • notes

    string

    Any evidence-related notes.
  • source

    enum

    The source of the evidence. Indicates whether PayPal requested the evidence, the customer submitted the evidence, or the merchant submitted the evidence.

    Read only.

    Possible values: REQUESTED_FROM_BUYER, REQUESTED_FROM_SELLER, SUBMITTED_BY_BUYER, SUBMITTED_BY_SELLER.

  • date

    object

    The date and time when the evidence was received, in Internet date and time format.

    Read only.

  • item_id

    string

    The ID of the item.

evidence_info

  • tracking_info

    array (contains the tracking_info object)

    An array of relevant tracking information for the transaction involved in this dispute.
  • refund_ids

    array (contains the refund_id object)

    An array of refund IDs for the transaction involved in this dispute.

evidences

  • evidences

    array (contains the evidence object)

    An array of evidences for the dispute.

item_info

  • item_id

    string

    The ID of the item.
  • partner_transaction_id

    string

    The ID of the transaction in the partner system. The partner transaction ID is returned at an item level because the partner might show different transactions for different items in the cart.
  • reason

    enum

    The reason for the item-level dispute. Value is:
    • 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 was not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit wasn't 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.
    For information about the required information for each dispute reason and associated evidence type, see dispute reason codes.

    Possible values: MERCHANDISE_OR_SERVICE_NOT_RECEIVED, MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED, UNAUTHORISED, CREDIT_NOT_PROCESSED, DUPLICATE_TRANSACTION, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, CANCELED_RECURRING_BILLING, PROBLEM_WITH_REMITTANCE, OTHER.

  • dispute_amount

    object

    The amount of the item in the dispute.
  • notes

    string

    Any notes provided with the item.

message

  • posted_by

    enum

    The customer or merchant who posted the message.

    Possible values: BUYER, SELLER.

  • time_posted

    object

    The date and time when the message was posted, in Internet date and time format.

    Read only.

  • content

    string

    The customer- or merchant-posted content.

    Minimum length: 0.

    Maximum length: 2000.

money

  • currency_code

    string

    required

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

    Minimum length: 3.

    Maximum length: 3.

  • value

    string

    required

    The value, which might be:
    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    Maximum length: 32.

    Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

offer

  • buyer_requested_amount

    object

    The buyer-requested refund for this dispute.

refund_id

  • refund_id

    string

    The ID of the refunded transaction.

require_evidence_request

  • action

    enum

    The action to complete.

    Possible values: BUYER_EVIDENCE, SELLER_EVIDENCE.

seller

  • email

    object

    The email address that is associated with the merchant's PayPal account.
  • merchant_id

    string

    The PayPal account ID for the merchant.
  • name

    string

    The name of the merchant.

subsequent_actions

tracking_info

  • carrier_name

    enum

    The name of the carrier for the shipment of the transaction that is associated with this dispute.

    Possible values: UPS, USPS, FEDEX, AIRBORNE_EXPRESS, DHL, AIRSURE, ROYAL_MAIL, PARCELFORCE, SWIFTAIR, OTHER, UK_PARCELFORCE, UK_ROYALMAIL_SPECIAL, UK_ROYALMAIL_RECORDED, UK_ROYALMAIL_INT_SIGNED, UK_ROYALMAIL_AIRSURE, UK_UPS, UK_FEDEX, UK_AIRBORNE_EXPRESS, UK_DHL, UK_OTHER, UK_CANNOT_PROV_TRACK, CA_CANADA_POST, CA_PUROLATOR, CA_CANPAR, CA_LOOMIS, CA_TNT, CA_OTHER, CA_CANNOT_PROV_TRACK, DE_DP_DHL_WITHIN_EUROPE, DE_DP_DHL_T_AND_T_EXPRESS, DE_DHL_DP_INTL_SHIPMENTS, DE_GLS, DE_DPD_DELISTACK, DE_HERMES, DE_UPS, DE_FEDEX, DE_TNT, DE_OTHER, FR_CHRONOPOST, FR_COLIPOSTE, FR_DHL, FR_UPS, FR_FEDEX, FR_TNT, FR_GLS, FR_OTHER, IT_POSTE_ITALIA, IT_DHL, IT_UPS, IT_FEDEX, IT_TNT, IT_GLS, IT_OTHER, AU_AUSTRALIA_POST_EP_PLAT, AU_AUSTRALIA_POST_EPARCEL, AU_AUSTRALIA_POST_EMS, AU_DHL, AU_STAR_TRACK_EXPRESS, AU_UPS, AU_FEDEX, AU_TNT, AU_TOLL_IPEC, AU_OTHER, FR_SUIVI, IT_EBOOST_SDA, ES_CORREOS_DE_ESPANA, ES_DHL, ES_UPS, ES_FEDEX, ES_TNT, ES_OTHER, AT_AUSTRIAN_POST_EMS, AT_AUSTRIAN_POST_PPRIME, BE_CHRONOPOST, BE_TAXIPOST, CH_SWISS_POST_EXPRES, CH_SWISS_POST_PRIORITY, CN_CHINA_POST, HK_HONGKONG_POST, IE_AN_POST_SDS_EMS, IE_AN_POST_SDS_PRIORITY, IE_AN_POST_REGISTERED, IE_AN_POST_SWIFTPOST, IN_INDIAPOST, JP_JAPANPOST, KR_KOREA_POST, NL_TPG, SG_SINGPOST, TW_CHUNGHWA_POST, CN_CHINA_POST_EMS, CN_FEDEX, CN_TNT, CN_UPS, CN_OTHER, NL_TNT, NL_DHL, NL_UPS, NL_FEDEX, NL_KIALA, BE_KIALA, PL_POCZTA_POLSKA, PL_POCZTEX, PL_GLS, PL_MASTERLINK, PL_TNT, PL_DHL, PL_UPS, PL_FEDEX, JP_SAGAWA_KYUU_BIN, JP_NITTSU_PELICAN_BIN, JP_KURO_NEKO_YAMATO_UNYUU, JP_TNT, JP_DHL, JP_UPS, JP_FEDEX, NL_PICKUP, NL_INTANGIBLE, NL_ABC_MAIL, HK_FOUR_PX_EXPRESS, HK_FLYT_EXPRESS.

  • tracking_url

    string

    The URL to track the item shipment.
  • tracking_number

    string

    The tracking number for the shipment for the transaction associated with this dispute.

transaction_id

  • transaction_id

    string

    The encrypted transaction ID.

transaction_info

  • buyer_transaction_id

    string

    The ID, as seen by the customer, for this transaction.
  • seller_transaction_id

    string

    The ID, as seen by the merchant, for this transaction.
  • create_time

    object

    The date and time when the transaction was created, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • transaction_status

    enum

    The transaction status. Value is:
    • COMPLETED. The transaction processing is completed.
    • UNCLAIMED. The items in the transaction are unclaimed. If they are not claimed within 30 days, the funds are returned to the sender.
    • DENIED. The transaction was denied.
    • FAILED. The transaction failed.
    • HELD. The transaction is on hold.
    • PENDING. The transaction is waiting to be processed.
    • PARTIALLY_REFUNDED. Payment for the transaction was partially refunded.
    • REFUNDED. Payment for the transaction was successfully refunded.
    • REVERSED. Payment for the transaction was reversed due to a chargeback or other type of reversal.

    Possible values: COMPLETED, UNCLAIMED, DENIED, FAILED, HELD, PENDING, PARTIALLY_REFUNDED, REFUNDED, REVERSED.

  • gross_amount

    object

    The gross amount of the transaction.
  • invoice_number

    string

    The ID of the invoice that is associated with the payment.
  • custom

    string

    A free-text field that is entered by the merchant during checkout.
  • buyer

    object

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

    object

    The details for the merchant who receives the funds and fulfills the order. For example, merchant ID, contact email address, and so on.
  • items

    array (contains the item_info object)

    An array of items that were purchased as part of the transaction.

    Read only.

Additional API information

Error messages

In addition to common HTTP status codes that the REST APIs return, the Customer Disputes API can return the following 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.

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

  • 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 10 MB of files for a case. Individual files must be smaller than 5 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_FULFILMENT

    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 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_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, see document. A refund ID 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_TRACKING_INFO

    For PROOF_OF_FULFILLMENT, the tracking number and carrier name are required but they are missing. Retry the request. For information, see tracking_info. The tracking number and carrier name are missing.

  • PERMISSION_DENIED

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

  • RESOURCE_NOT_FOUND_ERROR

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

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