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)

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.

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

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.

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.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields. For details about response fields, see dispute.

Parameters

  • start_time

    query_string string

    Filters the disputes in the response to those created after this 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.
  • create_time_after

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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_state

    query_string enum

    Filters the disputes in the response by state.

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

  • response_due_date_before

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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})$.

  • page_size

    query_string integer

    Limits the number of disputes in the response to this value. Default is 10. Maximum number of disputes is 50. Minimum number of disputes is 1.

    Default: 10.

  • disputed_transaction_id

    query_string string

    Filters the disputes in the response to those related to the transaction with this ID.
  • total_required

    query_string boolean

    If set to true, includes the total number of items in the response.
  • create_time_before

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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_after

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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_before

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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})$.

  • email

    string

    A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs.
    Note: Due to RFC 5321, 254 is the generally accepted maximum length for an email address even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. The pattern here only verifies that an unquoted @ sign exists. Services should not rely on static validation of email addresses. The only sure way to validated an email address is to send email to it.

    Minimum length: 3.

    Maximum length: 254.

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

  • response_due_date_after

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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})$.

  • next_page_token

    query_string string

    The token to fetch the next page results. This value is returned in the previous request response. If no next page results exist, the next-page link is null.

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)

    The dispute details.
  • total_items

    see description

    The total number of items. Shown only if total_required=true.
    Possible types: integer

    Read only.

  • total_pages

    see description

    The total number of pages. Shown only if total_required=true.
    Possible types: integer

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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": "wprasad-buyer-14420721835929008@paypal.com",
            "name": "June Ellen"
          },
          "seller": {
            "email": "wprasad-seller-14420786421377856@paypal.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"
    }
  ]
}

Provide evidence

POST /v1/customer/disputes/dispute_id/provide-evidence

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.

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.

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

Parameters

  • dispute_id

    path string

    The ID of the dispute for which to submit evidence.

Request

The sample requests are:

  • Sample 1. Provides evidence of proof of fulfillment as a document.
  • Sample 2. Provides evidence as notes.

  • evidence_type

    enum

    The type of evidence.

    Allowed 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 uploaded document that supports a dispute. The API submits the document as a binary object.
  • notes

    string

    Any evidence-related notes.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customers/disputes/PP-D-27803/provide-evidence \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "evidence_type": "PROOF_OF_FULFILLMENT",
  "evidence_info": {
  "tracking_info": [
    {
    "carrier_name": "FEDEX",
    "tracking_number": "FED111112345"
    }
  ]
  },
  "documents": [
  {
    "name": "SHIPMENT_1",
    "url": "/content/dam/paypal/s10/006/01/001/96/57/11/s10-006-01-001-96571189-0702-49ce-a866-faad20e29730"
  }
  ]
}'

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customers/disputes/PP-D-27803/provide-evidence \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "notes": "Consider the following evidence.",
  "evidence_info": {
  "tracking_number": "ABX123",
  "carrier_name": "DHL"
  }
}'

Response

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

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

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

Sample Response

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

Accept claim

POST /v1/customer/disputes/dispute_id/accept-claim

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.

Accepts a claim for a dispute, by ID. Accepts liability for a claim, which closes the dispute in the customers’s favor. PayPal refunds money to the customer from the merchant's account.

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

Parameters

  • dispute_id

    path string

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

Request

  • note

    string

    The merchant's notes for 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 ship the item for refund processing.

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": "It was an honest mistake. Kindly refund the money 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.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

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

Show dispute details

GET /v1/customer/disputes/dispute_id

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.

Shows details for a dispute, by ID.

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

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 response does not show the customer's email ID.

Parameters

  • dispute_id

    path string

    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.

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

  • disputed_transactions

    array (contains the transaction_info object)

    Information about the disputed transaction.
  • reason

    string

    The reason for the 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 credit transaction 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 incorrectly charged because he or she canceled recurring billing.
    • OTHER. 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 the dispute.

    Read only.

  • messages

    array (contains the message object)

    A customer- or merchant-posted message for the dispute.
  • 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.

  • dispute_flow

    enum

    The flow ID associated with the dispute ID.

    Read only.

    Possible values: ACH_RETURNS, ACCOUNT_ISSUES, ADMIN_FRAUD_REVERSAL, BILLING, CHARGEBACKS, COMPLAINT_RESOLUTION, CORRECTION, DEBIT_CARD_CHARGEBACK, FAX_ROUTING, MIPS_COMPLAINT_ITEM, MIPS_COMPLAINT, OPS_VERIFICATION_FLOW, PAYPAL_DISPUTE_RESOLUTION, PINLESS_DEBIT_RETURN, PRICING_ADJUSTMENT, SPOOF_UNAUTH_CHILD, SPOOF_UNAUTH_PARENT, THIRD_PARTY_CLAIM, THIRD_PARTY_DISPUTE, TICKET_RETRIEVAL, UK_EXPRESS_RETURNS, UNKNOWN_FAXES, VETTING, OTHER.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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": "wprasad-buyer-14420721835929008@paypal.com",
        "name": "June Ellen"
      },
      "seller": {
        "email": "wprasad-seller-14420786421377856@paypal.com",
        "merchant_id": "MDLV8MPZEEXVJ",
        "name": "Total Attraction"
      }
    }
  ],
  "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
  "status": "WAITING_FOR_SELLER_RESPONSE",
  "dispute_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"
    }
  ]
}

Appeal dispute

POST /v1/customer/disputes/dispute_id/appeal

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.

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.

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

Parameters

  • dispute_id

    path string

    The PayPal dispute ID.

Request

  • evidence_type

    enum

    The type of evidence.

    Allowed 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 uploaded document that supports a dispute. The API submits the document as a binary object.
  • notes

    string

    Any evidence-related notes.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "notes": "Consider the following evidence.",
  "evidence_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.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

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 for 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 ship the item for refund processing.

activity_entity_information

  • last_known_valid_transaction_date

    string

    The date and time when the user last completed a valid transaction by using the instrument.

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 of the address. For example, Street, Lane, Boulevard, Court, and so on.

    Maximum length: 300.

  • delivery_service

    string

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

    Maximum length: 300.

  • building_name

    string

    The premise. A named location. 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 sub-premise. First-order entity below a named building or location. Usually a single building within a collection of buildings with a common name. Could be flat, storey, floor, room, or apartment.

    Maximum length: 300.

buyer

  • email

    string

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

    string

    The customer's name.

cancel_request

  • note

    string

    An optional note.

    Maximum length: 1048576.

  • transaction_ids

    array

    The transaction ID for a canceled unauthorized dispute. If you omit this value for unauthorized disputes, the issue is automatically chosen for cancellation. Not required for other dispute types.

cancellation_details

  • cancellation_date

    string

    The date and time of the cancellation, in Internet date and time format.
  • cancellation_number

    string

    The cancellation number.
  • cancelled

    boolean

    Indicates whether the dispute was canceled.

change_reason_request

  • reason

    string

    The reason to which to update a dispute's reason.
  • note

    string

    An optional note.

    Maximum length: 1048576.

  • extensions

    object

    The extended properties for the dispute. Contains the additional information for different dispute categories. For example, for billing disputes, includes the original transaction ID, the correct amount, and so on.
  • transaction_ids

    array

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

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.

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

  • disputed_transactions

    array (contains the transaction_info object)

    Information about the disputed transaction.
  • reason

    string

    The reason for the 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 credit transaction 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 incorrectly charged because he or she canceled recurring billing.
    • OTHER. 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 the dispute.

    Read only.

  • messages

    array (contains the message object)

    A customer- or merchant-posted message for the dispute.
  • 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.

  • dispute_flow

    enum

    The flow ID associated with the dispute ID.

    Read only.

    Possible values: ACH_RETURNS, ACCOUNT_ISSUES, ADMIN_FRAUD_REVERSAL, BILLING, CHARGEBACKS, COMPLAINT_RESOLUTION, CORRECTION, DEBIT_CARD_CHARGEBACK, FAX_ROUTING, MIPS_COMPLAINT_ITEM, MIPS_COMPLAINT, OPS_VERIFICATION_FLOW, PAYPAL_DISPUTE_RESOLUTION, PINLESS_DEBIT_RETURN, PRICING_ADJUSTMENT, SPOOF_UNAUTH_CHILD, SPOOF_UNAUTH_PARENT, THIRD_PARTY_CLAIM, THIRD_PARTY_DISPUTE, TICKET_RETRIEVAL, UK_EXPRESS_RETURNS, UNKNOWN_FAXES, VETTING, OTHER.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

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 to the customer.

dispute_reasons

  • response-dispute-reasons

    enum

    The dispute reason.

    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)

    The dispute details.
  • total_items

    see description

    The total number of items. Shown only if total_required=true.
    Possible types: integer

    Read only.

  • total_pages

    see description

    The total number of pages. Shown only if total_required=true.
    Possible types: integer

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

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. If you specify a transaction ID, determines whether that transaction is eligible for case creation.
  • dispute_id

    string

    The dispute ID. If you specify a dispute ID, lists the valid reasons for that dispute; the buyer can change the dispute's reason to any of these values.

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 uploaded document that supports a dispute. The API submits the document as a binary object.
  • 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

    string

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

    Read only.

evidence_info

  • tracking_info

    array (contains the tracking_info object)

    The tracking information.
  • refund_ids

    array

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

filter

  • email

    string

    Filters the disputes in the response by an email.
  • name

    string

    Filters the disputes in the response by a counter party's full name.
  • reasons

    string

    One or more reasons. Separate multiple reasons by a comma. When you specify multiple reasons, the response includes the disputes associated with any specified reason.
  • statuses

    string

    One or more statuses. Separate multiple statuses by a comma. When you specify multiple statuses, the response includes the disputes associated with any specified status.
  • create_time_before

    string

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

    string

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

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

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

    string

    The date and time when the dispute is due for response, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • response_due_date_after

    string

    The date and time when the dispute is due for response, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • dispute_amount_gte

    object

    Filters the disputes in the response by a dispute amount that is greater than or equal to this amount.
  • dispute_amount_lte

    object

    Filters the disputes in the response by a dispute amount that is less than or equal to this amount.

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

    string

    The reason of 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 credit transaction 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 incorrectly charged because he or she canceled recurring billing.
    • OTHER. Other.
  • dispute_amount

    object

    The amount of the item in the dispute.
  • notes

    string

    Any notes provided with the item.

json_openapi_2_0_country_code

  • json-openapi-2.0-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 CUP, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

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

json_openapi_2_0_currency_code

  • json-openapi-2.0-currency_code

    string

    The three-letter ISO 4217 alphabetic currency code.

    Minimum length: 3.

    Maximum length: 3.

json_openapi_2_0_date_time

  • json-openapi-2.0-date_time

    string

    A valid date and time representation, as defined by RFC 3339, section 5.6, which is a profile of the ISO 8601 date and time standard. Unlike RFC 3339, we do define a practical if impractically precise length limit on the number of fractional seconds. This means, for instance, that seconds are required while fractional seconds are optional.
    Note: The regular expression cannot reject all invalid dates but only provide guidance.

    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})$.

json_openapi_2_0_email_address

  • json-openapi-2.0-email_address

    string

    A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs.
    Note: Due to RFC 5321, 254 is the generally accepted maximum length for an email address even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. The pattern here only verifies that an unquoted @ sign exists. Services should not rely on static validation of email addresses. The only sure way to validated an email address is to send email to it.

    Minimum length: 3.

    Maximum length: 254.

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

merchant

  • email

    string

    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.

message

  • posted_by

    enum

    The user who posted the message.

    Possible values: BUYER, SELLER.

  • time_posted

    string

    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.

metrics_request

  • dimension

    enum

    The dispute attribute.

    Possible values: STATUS, REASON, DISPUTE_OUTCOME, DISPUTE_STATE.

  • measure

    enum

    The measure for the dimension.

    Possible values: COUNT, DISPUTE_AMOUNT_SUM, TRANSACTION_AMOUNT_SUM, REFUND_AMOUNT_SUM.

  • filter

    object

metrics_response

  • metrics

    array

    An array of metrics for disputes of a dimension and measure.

money_type_with_currency_code_qualified_value

  • currency_code

    string

    The three-letter ISO 4217 alphabetic currency code.
  • value

    string

    The currency value. For currencies like JPY that are not typically fractional, might be an integer. For currencies like TND that are subdivided into thousandths, might be a decimal fraction. For the required number of decimal places for a currency code, see ISO 4217.

    Maximum length: 32.

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

portable_postal_address_(medium_grained)

  • address_line_1

    string

    The first line of the address. For example, number, street, and so on. 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

    Optional. The second line of the address. For example, suite, apartment number, and so on.

    Maximum length: 300.

  • address_line_3

    string

    Optional. The third line of the address, if needed. Examples include street complement for Brazil, direction text such as next to Walmart, or landmark in Indian address.

    Maximum length: 300.

  • admin_area_4

    string

    Neighborhood, ward, or district. Smaller than admin_area_level_3. Smaller than sub_locality. Value is:
    • Postal Sorting Code used in Guernsey, and many French territories such as French Guiana
    • Fine-grained administrative levels in China

    Maximum length: 300.

  • admin_area_3

    string

    Usually sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Could be:
    • Suburb or Bairro/Neighborhood in Brazil
    • In India, street name information is often not available, but a sublocality or district can be a very small area

    Maximum length: 300.

  • admin_area_2

    string

    Usually city, town or village. Smaller than admin_area_level_1.

    Maximum length: 300.

  • admin_area_1

    string

    Usually corresponds to province, state, or ISO-3166-2 subdivision. Highest level sub-division of a country. Expected to be the form that would appears in address as it is formatted for postal delivery. For example, CA and not California. Value is:
    • A county in UK
    • State in USA
    • Province in Canada
    • Prefecture in Japan
    • Kanton in Switzerland

    Maximum length: 300.

  • postal_code

    string

    Postal code.

    Maximum length: 60.

  • 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 CUP, bank card, and cross-border transactions.
  • address_details

    object

    Non-portable additional address details sometimes needed for compliance, risk, and 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 plus street_name plus street_type.

response_dispute_create_response

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

subsequent_actions

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

tracking_info

  • carrier_name

    enum

    The name of the carrier for the shipment for the transaction in 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 involved in this dispute.

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

    string

    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. The charge for the transaction was reversed.

    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 customer details. For example, the customer's first name, last name, email address, and so on.
  • seller

    object

    The merchant details. For example, merchant ID, contact email address, and so on.
  • items

    array (contains the item_info object)

    The information for the purchased item in a disputed transaction.

    Read only.

Additional API information

Error messages

In addition to common REST API errors, the Customer Disputes API can return the following errors. Corrective action is provided where possible.

  • AUTHORIZATION_ERROR

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

  • INTERNAL_SERVICE_ERROR

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

  • PERMISSION_DENIED

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