Customer Disputes API

Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can create a dispute with PayPal. PayPal merchants, partners, and external developers can use the PayPal Customer Disputes API to manage customer disputes.
Note: In the live environment, merchants cannot create disputes but can only respond to customer-created disputes. However, merchants can create disputes in the sandbox environment.
A customer can also ask his or her bank or credit card company to dispute and reverse a charge, which is known as a chargeback. For more information, see Disputes, claims, chargebacks, and bank reversals.

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

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

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

For details, see Customer Disputes Overview documentation.

Disputes (resource group)

Use the /customer/disputes/ resource to list disputes and show dispute details, and accept or deny a proposed offer. Normally, an agent at PayPal creates disputes, updates the status of disputes, and settles disputes but now you can run test cases in the sandbox that create disputes, update the status of disputes, and settle disputes.

List disputes

GET /v1/customer/disputes
Lists disputes with a full or summary set of details. Default is a summary set of details, which shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields.

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

To list multiple disputes, set these query parameters in the request:
  • page_size=2
  • start_time instead of disputed_transaction_id

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

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.

    You can specify either but not both the start_time and disputed_transaction_id query parameter. If you omit the start time, default is the current date and time.
  • disputed_transaction_id

    string

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

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

    integer

    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. The list disputes call returns this token in the HATEOAS links in the response. If you omit this parameter, the API returns the first page of data.
  • dispute_state

    enum

    Filters the disputes in the response by a state. The allowed values are:
    • REQUIRED_ACTION. Filters the disputes in the response to those with the REQUIRED_ACTION dispute state.
    • REQUIRED_OTHER_PARTY_ACTION. Filters the disputes in the response to those with the REQUIRED_OTHER_PARTY_ACTION dispute state.
    • UNDER_PAYPAL_REVIEW. Filters the disputes in the response to those with the UNDER_PAYPAL_REVIEW dispute state.
    • RESOLVED. Filters the disputes in the response to those with the RESOLVED dispute state.
    • OPEN_INQUIRIES. Filters the disputes in the response to those with the OPEN_INQUIRIES dispute state.

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 a full or summary set of details. Default is a summary set of details, which shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields for each dispute.
  • items

    array (contains the dispute object)

    An array of disputes that match the filter criteria. Sorted in latest to earliest creation time order.
  • 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": {
            "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"
    }
  ]
}

Partially update dispute

PATCH /v1/customer/disputes/{dispute_id}
Partially updates a dispute, by ID. You can update the communication_detail value.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute to update.

Request body

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "op": "add",
    "path": "/communication_details",
    "value": {
      "email": "merchant@example.com",
      "note": "Please send a photo copy of the damaged items to the above email."
    }
  }
]'

Response

A successful request returns the HTTP 204 No Content status code.

Sample Response

204 No Content

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 disputes were created.
  • reason

    enum

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other.
  • status

    enum

    The status of the dispute. The possible values are:
    • OPEN. The dispute is open.
    • WAITING_FOR_BUYER_RESPONSE. The dispute is waiting for a response from the customer.
    • WAITING_FOR_SELLER_RESPONSE. The dispute is waiting for a response from the merchant.
    • UNDER_REVIEW. The dispute is under review with PayPal.
    • RESOLVED. The dispute is resolved.
    • OTHER. The default status if the dispute does not have one of the other statuses.

    Read only.

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

    string

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

    Read only.

  • dispute_outcome

    object

    The outcome of a dispute.

    Read only.

  • dispute_life_cycle_stage

    enum

    The stage in the dispute lifecycle. The possible values are:
    • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:
      • Has not received goods or a service.
      • Reports that the received goods or service are not as described.
      • Needs more details, such as a copy of the transaction or a receipt.
    • CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:
      • Accept the claim.
      • Submit evidence to challenge the claim.
    • PRE_ARBITRATION. The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.
    • ARBITRATION. The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.

    Read only.

  • dispute_channel

    enum

    The channel where the customer created the dispute. The possible values are:
    • INTERNAL. The customer contacts PayPal to file a dispute with the merchant.
    • EXTERNAL. The customer contacts their card issuer or bank to request a refund.

    Read only.

  • messages

    array (contains the message object)

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

    array (contains the evidence object)

    An array of evidence documents.
  • buyer_response_due_date

    string

    The date and time by when the customer must respond to the dispute, in Internet date and time format. If the customer does not respond by this date and time, the dispute is closed in the merchant'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})$.

  • 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 merchant-proposed offer for a dispute.

    Read only.

  • communication_details

    object

    The contact details that a merchant provides to the customer to use to share their evidence documents.
  • 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": {
        "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"
    }
  },
  "refund_details": {
    "allowed_refund_amount": {
      "currency_code": "USD",
      "value": "6.00"
    },
    "refunds": [
      {
        "gross_amount": {
          "currency_code": "USD",
          "value": "6.00"
        },
        "transaction_time": "2017-01-24T05:52:11.000Z",
        "transaction_id": "965038709E474252Y",
        "invoice_number": "Z35353547677"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-003-648-191",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Disputes actions (resource group)

Use the /customer/disputes/ resource with a dispute ID and an action to send a message to the other party, make an offer to resolve a dispute, escalate a dispute to a claim, provide evidence, accept a claim, appeal a dispute, and acknowledge returned item.

Accept claim

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

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 the claim. PayPal can, but the customer cannot, view these notes.

    Minimum length: 1.

    Maximum length: 2000.

  • accept_claim_reason

    enum

    The merchant's reason for acceptance of the customer's claim. The allowed values are:
    • DID_NOT_SHIP_ITEM. Merchant is accepting customer's claim as they could not ship the item back to the customer
    • TOO_TIME_CONSUMING. Merchant is accepting customer's claim as it is taking too long for merchant to fulfil the order
    • LOST_IN_MAIL. Merchant is accepting customer's claim as the item is lost in mail or transit
    • NOT_ABLE_TO_WIN. Merchant is accepting customer's claim as the merchant is not able to find sufficient evidence to win this dispute
    • COMPANY_POLICY. Merchant is accepting customer’s claims to follow their internal company policy
    • REASON_NOT_SET. This is the default value merchant can use if none of the above reasons apply
  • invoice_id

    string

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

    object

    The return address for the item.

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

    object

    To accept a customer's claim, the amount that the merchant agrees to refund the customer. The subsequent action depends on the amount:
    • If this amount is less than the customer-requested amount, the dispute updates to require customer acceptance.
    • If this amount is equal to or greater than the customer-requested amount, this amount is automatically refunded to the customer and the dispute closes.

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": "full refund with item return.",
  "return_shipping_address": {
    "address_line_1": "14,Kimberly st",
    "address_line_2": "Open Road North",
    "country_code": "US",
    "admin_area_1": "Gotham City",
    "admin_area_2": "Gotham",
    "postal_code": "124566"
  }
}'

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"
    }
  ]
}

Accept offer to resolve dispute

POST /v1/customer/disputes/{dispute_id}/accept-offer
The customer can accept an existing offer from merchant to resolve a dispute, by ID. If the customer accepts the offer, PayPal automatically refunds the amount proposed by merchant to the customer.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/accept-offer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "I am ok with the refund offered."
}'

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-000-000-651-454"
    }
  ]
}

Acknowledge returned item

POST /v1/customer/disputes/{dispute_id}/acknowledge-return-item
Acknowledges that the customer returned a disputed item for a dispute, by ID. A merchant can make this request for disputes with the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED reason.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/acknowledge-return-item \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "I have received the item back."
}'

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-000-000-651-454"
    }
  ]
}

Settle dispute

POST /v1/customer/disputes/{dispute_id}/adjudicate
Sandbox only. Settles a dispute in either the customer's or merchant's favor. Merchants can make this call in the sandbox to complete end-to-end dispute resolution testing, which mimics the dispute resolution that PayPal agents normally complete. To make this call, the dispute status must be UNDER_REVIEW.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute to settle.

Request body

  • adjudication_outcome

    enum

    The outcome of the adjudication. The allowed values are:
    • BUYER_FAVOR. Resolves the case in the customer's favor. Outcome is set to RESOLVED_BUYER_FAVOR.
    • SELLER_FAVOR. Resolves the case in the merchant's favor. Outcome is set to RESOLVED_SELLER_FAVOR.

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. For information about dispute reasons, see dispute reasons.

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

    object

    The return address for the item.

    Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason..

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" \
-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'

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"
    }
  ]
}

Deny proposed offer

POST /v1/customer/disputes/{dispute_id}/deny-offer
Denies an offer that the merchant proposes for a dispute, by ID.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/deny-offer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "refund offer is very low."
}'

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-000-000-651-454"
    }
  ]
}

Escalate dispute to claim

POST /v1/customer/disputes/{dispute_id}/escalate
Escalates the dispute, by ID, to a PayPal claim. To make this call, the stage in the dispute lifecycle must be INQUIRY.

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute to escalate to a claim.

Request body

  • note

    string

    required

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

    Minimum length: 1.

    Maximum length: 2000.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/escalate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Escalating to PayPal claim for resolution."
}'

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-000-000-651-454"
    }
  ]
}

Make offer to resolve dispute

POST /v1/customer/disputes/{dispute_id}/make-offer
Makes an offer to the other party to resolve a dispute, by ID. To make this call, the stage in the dispute lifecycle must be INQUIRY. If the customer accepts the offer, PayPal automatically makes a refund.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • note

    string

    required

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

    Minimum length: 1.

    Maximum length: 2000.

  • offer_amount

    object

    The amount proposed to resolve the dispute.
  • return_shipping_address

    object

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

    string

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

    enum

    required

    The merchant-proposed offer type for the dispute. The allowed values are:
    • REFUND. The merchant must refund the customer without any item replacement or return. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.
    • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
    • REFUND_WITH_REPLACEMENT. The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer to resolve dispute call.
    • REPLACEMENT_WITHOUT_REFUND. The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer to resolve dispute call.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/make-offer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Offer refund with replacement item.",
  "offer_amount": {
    "currency_code": "USD",
    "value": "23"
  },
  "offer_type": "REFUND_WITH_REPLACEMENT"
}'

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-000-000-651-454"
    }
  ]
}

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 merchant 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. For information about dispute reasons, see dispute reasons.

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.

Request body

  • evidences

    array (contains the evidence object)

    An array of evidences for the dispute.
  • return_shipping_address

    object

    The return address for the item.

    Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason..

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' \
-F 'return_shipping_address={
  "address_line_1": "14,Kimberly st",
  "address_line_2": "Open Road North",
  "country_code": "US",
  "admin_area_1": "Gotham City",
  "admin_area_2": "Gotham",
  "postal_code": "124566"
};type=application/json'

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 status

POST /v1/customer/disputes/{dispute_id}/require-evidence
Sandbox only. Updates the status of a dispute, by ID, from UNDER_REVIEW to either:
  • WAITING_FOR_BUYER_RESPONSE
  • WAITING_FOR_SELLER_RESPONSE
This status change enables either the customer or merchant to submit evidence for the dispute. To make this call, the dispute status must be UNDER_REVIEW. Specify an action value in the JSON request body to indicate whether the status change enables the customer or merchant to submit evidence:
If action isThe status updates to
BUYER_EVIDENCE WAITING_FOR_BUYER_RESPONSE
SELLER_EVIDENCE WAITING_FOR_SELLER_RESPONSE

Path parameters

  • dispute_id

    string

    required

    The ID of the dispute that requires evidence.

Request body

  • action

    enum

    The action. Indicates whether the state change enables the customer or merchant to submit evidence. The allowed values are:
    • BUYER_EVIDENCE. Changes the status of the dispute to WAITING_FOR_BUYER_RESPONSE.
    • SELLER_EVIDENCE. Changes the status of the dispute to WAITING_FOR_SELLER_RESPONSE.

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"
    }
  ]
}

Send message to other party

POST /v1/customer/disputes/{dispute_id}/send-message
Sends a message to the other party in the dispute, by ID. Merchants and customers can only send messages if the dispute_life_cycle_stage value is INQUIRY.

Path parameters

  • dispute_id

    string

    required

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

Request body

  • message

    string

    required

    The message sent by the merchant to the other party.

Sample Request

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

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-000-000-651-454"
    }
  ]
}

Common object definitions

accept_claim

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

  • accept_claim_reason

    enum

    The merchant's reason for acceptance of the customer's claim. The possible values are:
    • DID_NOT_SHIP_ITEM. Merchant is accepting customer's claim as they could not ship the item back to the customer
    • TOO_TIME_CONSUMING. Merchant is accepting customer's claim as it is taking too long for merchant to fulfil the order
    • LOST_IN_MAIL. Merchant is accepting customer's claim as the item is lost in mail or transit
    • NOT_ABLE_TO_WIN. Merchant is accepting customer's claim as the merchant is not able to find sufficient evidence to win this dispute
    • COMPANY_POLICY. Merchant is accepting customer’s claims to follow their internal company policy
    • REASON_NOT_SET. This is the default value merchant can use if none of the above reasons apply
  • invoice_id

    string

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

    object

    The return address for the item.

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

    object

    To accept a customer's claim, the amount that the merchant agrees to refund the customer. The subsequent action depends on the amount:
    • If this amount is less than the customer-requested amount, the dispute updates to require customer acceptance.
    • If this amount is equal to or greater than the customer-requested amount, this amount is automatically refunded to the customer and the dispute closes.

accept_offer

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

acknowledge_return_item

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

address_details

  • street_number

    string

    The street number.

    Maximum length: 100.

  • street_name

    string

    The street name. Just Drury in Drury Lane.

    Maximum length: 100.

  • street_type

    string

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

    Maximum length: 100.

  • delivery_service

    string

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

    Maximum length: 100.

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

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

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

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

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

  • admin_area_2

    string

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

    Maximum length: 120.

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

address_portable_postal_code_validation

  • address_portable_postal_code_validation

adjudicate

  • adjudication_outcome

    enum

    The outcome of the adjudication. The possible values are:
    • BUYER_FAVOR. Resolves the case in the customer's favor. Outcome is set to RESOLVED_BUYER_FAVOR.
    • SELLER_FAVOR. Resolves the case in the merchant's favor. Outcome is set to RESOLVED_SELLER_FAVOR.

adjudication_info

  • dispute_amount

    object

    The actual amount that was disputed on the third-party site.
  • items

    array (contains the referred_item_info object)

    An array of items in the transaction that is in dispute.
  • outcome

    object

    The outcome of the case.
  • extensions

    object

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

    enum

    The reason for the dispute, if the reason has changed during the dispute lifecycle. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • FRAUD_REVERSAL. An agent-created fraud reversal case.
    • ACH_RETURN. An ACH return from a bank.
    • CHARGEBACK. A chargeback from a credit card-issuing bank.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other
    • THIRD_PARTY. A case created for logging and record purposes in the PayPal system that corresponds to a case created on third-party platforms.
  • closure_reason

    string

    The reason that the dispute was closed.
  • messages

    array (contains the referred_message object)

    An array of customer- or merchant-posted messages.

buyer

  • name

    string

    The customer's name.

cancel

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

    enum

    The reason the merchant cancelled the item. The possible values are:
    • ITEM_RECEIVED. The customer already received the item.
    • REFUND_RECEIVED. The customer already received a refund for the item.
    • OTHER. The customer cancelled the dispute for another reason. If OTHER is specified, customer needs to specify more information in the notes field.
    • SHIPMENT_INFO_RECEIVED. The customer received the provided shipping tracking information and agrees to cancel.
    • REPLACEMENT_RECEIVED. The customer received the item replacement and agrees to cancel.

canceled_recurring_billing

  • expected_refund

    object

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

    object

    The cancellation details.

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.

category

  • category

    enum

    The category of the item in dispute. The possible values are:
    • COMPUTERS. Computer or related accessories.
    • HOME. Home appliances.
    • JEWELRY. Decorative items, ornaments, and so on.
    • ANTIQUES. Antiques and collectible items.
    • ENTERTAINMENT. Entertainment goods, such as video games, DVDs, and so on.
    • OTHER_TANGIBLES. Other material goods.
    • TRAVEL. Travel items and travel needs.
    • SERVICE. Services, such as installation, repair, and so on.
    • VIRTUAL_GOODS. Non-physical objects, such as online games.
    • OTHER_INTANGIBLES. Other intangible goods.
    • TICKETS. Tickets for events, such as sports, concerts, and so on.

communication_details

  • email

    string

    The email address that is provided by the merchant where the customer can share the evidences.

    Minimum length: 3.

    Maximum length: 254.

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

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

  • time_posted

    string

    The date and time when the contact details were posted, in Internet date and time format.

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

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

credit_not_processed

  • issue_type

    enum

    The issue type. The possible values are:
    • PRODUCT. The product has an issue.
    • SERVICE. The service has an issue.
  • expected_refund

    object

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

    object

    The cancellation details.
  • product_details

    object

    The product information.
  • service_details

    object

    The service details.

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

deny_offer

  • note

    string

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

    Minimum length: 1.

    Maximum length: 2000.

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 disputes were created.
  • reason

    enum

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other.
  • status

    enum

    The status of the dispute. The possible values are:
    • OPEN. The dispute is open.
    • WAITING_FOR_BUYER_RESPONSE. The dispute is waiting for a response from the customer.
    • WAITING_FOR_SELLER_RESPONSE. The dispute is waiting for a response from the merchant.
    • UNDER_REVIEW. The dispute is under review with PayPal.
    • RESOLVED. The dispute is resolved.
    • OTHER. The default status if the dispute does not have one of the other statuses.

    Read only.

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

    string

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

    Read only.

  • dispute_outcome

    object

    The outcome of a dispute.

    Read only.

  • dispute_life_cycle_stage

    enum

    The stage in the dispute lifecycle. The possible values are:
    • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:
      • Has not received goods or a service.
      • Reports that the received goods or service are not as described.
      • Needs more details, such as a copy of the transaction or a receipt.
    • CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:
      • Accept the claim.
      • Submit evidence to challenge the claim.
    • PRE_ARBITRATION. The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.
    • ARBITRATION. The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.

    Read only.

  • dispute_channel

    enum

    The channel where the customer created the dispute. The possible values are:
    • INTERNAL. The customer contacts PayPal to file a dispute with the merchant.
    • EXTERNAL. The customer contacts their card issuer or bank to request a refund.

    Read only.

  • messages

    array (contains the message object)

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

    array (contains the evidence object)

    An array of evidence documents.
  • buyer_response_due_date

    string

    The date and time by when the customer must respond to the dispute, in Internet date and time format. If the customer does not respond by this date and time, the dispute is closed in the merchant'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})$.

  • 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 merchant-proposed offer for a dispute.

    Read only.

  • communication_details

    object

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

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

dispute_create

dispute_create_request

  • dispute_flow

    enum

    The flow ID for the dispute being created. The possible values are:
    • THIRD_PARTY_CLAIM. Third-party claim information that the dispute requires custom handling.
    • THIRD_PARTY_DISPUTE. Third-party claim information that the dispute does not require any special handling. Defaults to default procedures.
  • extensions

    object

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

    object

    required

    The details about the transactions that are part of the referred dispute.
  • reference_dispute

    object

    required

    Details about the partner dispute.
  • reason

    enum

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • FRAUD_REVERSAL. An agent-created fraud reversal case.
    • ACH_RETURN. An ACH return from a bank.
    • CHARGEBACK. A chargeback from a credit card-issuing bank.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other
    • THIRD_PARTY. A case created for logging and record purposes in the PayPal system that corresponds to a case created on third-party platforms.
  • messages

    array (contains the referred_message object)

    An array of customer- or merchant-posted messages.

dispute_create_response

dispute_flow

  • dispute_flow

    enum

    The flow ID for the dispute being created. The possible values are:
    • THIRD_PARTY_CLAIM. Third-party claim information that the dispute requires custom handling.
    • THIRD_PARTY_DISPUTE. Third-party claim information that the dispute does not require any special handling. Defaults to default procedures.

dispute_outcome

  • outcome_code

    enum

    The outcome of a resolved dispute. The possible values are:
    • 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. PayPal accepted the dispute.
    • DENIED. PayPal denied the dispute.
    • NONE. A dispute was created for the same transaction ID, and the previous dispute was closed without any decision.
  • 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. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • FRAUD_REVERSAL. An agent-created fraud reversal case.
    • ACH_RETURN. An ACH return from a bank.
    • CHARGEBACK. A chargeback from a credit card-issuing bank.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other
    • THIRD_PARTY. A case created for logging and record purposes in the PayPal system that corresponds to a case created on third-party platforms.

document

  • name

    string

    The document name.
  • size

    string

    The document size.

duplication_transaction

  • received_duplicate

    boolean

    If true, indicates that a duplicate transaction was received.
  • original_transaction

    object

    The transaction details for the original transaction, when the dispute reason is DUPLICATE_TRANSACTION. Currently, contains only the date and amount.

eligibility

  • 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 customer can use the eligible reasons to update the dispute.

eligibility_request

  • transaction_id

    string

    required

    The encrypted transaction ID.
  • disputed_items

    array (contains the eligibility_request_item object)

    An array of the items in the disputed transaction.

eligibility_request_item

  • id

    string

    The ID of the item.
  • category

    enum

    The category of the item in dispute. The possible values are:
    • COMPUTERS. Computer or related accessories.
    • HOME. Home appliances.
    • JEWELRY. Decorative items, ornaments, and so on.
    • ANTIQUES. Antiques and collectible items.
    • ENTERTAINMENT. Entertainment goods, such as video games, DVDs, and so on.
    • OTHER_TANGIBLES. Other material goods.
    • TRAVEL. Travel items and travel needs.
    • SERVICE. Services, such as installation, repair, and so on.
    • VIRTUAL_GOODS. Non-physical objects, such as online games.
    • OTHER_INTANGIBLES. Other intangible goods.
    • TICKETS. Tickets for events, such as sports, concerts, and so on.

eligibility_response

  • eligible

    boolean

    Indicates whether the transaction can be disputed.
  • allowable_life_cycle

    enum

    The details about the allowable life cycle stage and the reason why it is allowed. The possible values are:
    • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when a customer has not received goods or a service, the goods or service are not as described, or the customer needs additional details on a transaction, such as a copy of the transaction or a receipt
    • CHARGEBACK. This stage occurs when a customer or merchant escalates an inquiry to a claim. Claims give PayPal the authority to investigate the case and determine an outcome if the dispute channel is `INTERNAL`. This state is a PayPal dispute lifecycle stage and is not to be interpreted as a credit card or debit card charge back
  • ineligibility_reason

    string

    The reason that the dispute could not be created.
  • existing_disputes

    array (contains the referred_dispute object)

    An array of details about the disputes on the transaction.
  • existing_refunds

    array (contains the transaction object)

    An array of details about the refunds on the disputed transaction, if applicable.

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. Value is body, path, or query.

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

escalate

  • note

    string

    required

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

    Minimum length: 1.

    Maximum length: 2000.

evidence

  • evidence_type

    enum

    The evidence type. The possible values are:
    • PROOF_OF_FULFILLMENT. Proof of fulfillment.
    • PROOF_OF_REFUND. Proof of refund.
    • PROOF_OF_DELIVERY_SIGNATURE. Proof of delivery signature.
    • PROOF_OF_RECEIPT_COPY. Proof of receipt copy.
    • RETURN_POLICY. The return policy.
    • BILLING_AGREEMENT. The billing agreement.
    • PROOF_OF_RESHIPMENT. Proof of re-shipment.
    • ITEM_DESCRIPTION. The item description.
    • POLICE_REPORT. A police report.
    • AFFIDAVIT. An affidavit.
    • PAID_WITH_OTHER_METHOD. Paid with another method.
    • COPY_OF_CONTRACT. Copy of the contract.
    • TERMINAL_ATM_RECEIPT. The ATM receipt.
    • PRICE_DIFFERENCE_REASON. The reason for the price difference.
    • SOURCE_CONVERSION_RATE. The source conversion rate.
    • BANK_STATEMENT. The bank statement.
    • CREDIT_DUE_REASON. The credit due reason.
    • REQUEST_CREDIT_RECEIPT. The request credit receipt.
    • PROOF_OF_RETURN. Proof of return.
    • CREATE. Create.
    • CHANGE_REASON. The change reason.
    • OTHER. Other.
  • evidence_info

    object

    The evidence-related information.
  • documents

    array (contains the document object)

    An array of evidence documents.
  • notes

    string

    Any evidence-related notes.

    Maximum length: 2000.

  • item_id

    string

    The item ID. If the merchant provides multiple pieces of evidence and the transaction has multiple item IDs, the merchant can use this value to associate a piece of evidence with an item ID.

evidence_info

  • tracking_info

    array (contains the response_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.
  • return_shipping_address

    object

    The return address for the item.

    Required when the customer must return an item to the merchant for the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED dispute reason..

incorrect_transaction_amount

  • correct_transaction_amount

    object

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

    string

    The date and time when the customer created the transaction, in Internet date and time format.

item_info

  • item_id

    string

    The item ID. If the merchant provides multiple pieces of evidence and the transaction has multiple item IDs, the merchant can use this value to associate a piece of evidence with an item ID.
  • item_description

    string

    The item description.
  • 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. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other.
  • dispute_amount

    object

    The amount of the item in the dispute.
  • notes

    string

    Any notes provided with the item.

make_offer

  • note

    string

    required

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

    Minimum length: 1.

    Maximum length: 2000.

  • offer_amount

    object

    The amount proposed to resolve the dispute.
  • return_shipping_address

    object

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

    string

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

    enum

    required

    The merchant-proposed offer type for the dispute. The possible values are:
    • REFUND. The merchant must refund the customer without any item replacement or return. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.
    • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
    • REFUND_WITH_REPLACEMENT. The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer to resolve dispute call.
    • REPLACEMENT_WITHOUT_REFUND. The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer to resolve dispute call.

message

  • posted_by

    enum

    Indicates whether the customer, merchant, or dispute arbiter posted the message. The possible values are:
    • BUYER. The customer posted the message.
    • SELLER. The merchant posted the message.
    • ARBITER. The arbiter of the dispute posted the message.

    Read only.

  • time_posted

    string

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

    Read only.

  • content

    string

    The message text.

    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.

    Maximum length: 32.

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

offer

  • buyer_requested_amount

    object

    The customer-requested refund for this dispute.
  • seller_offered_amount

    object

    The merchant-offered refund for this dispute.
  • offer_type

    enum

    The merchant-proposed offer type for the dispute. The possible values are:
    • REFUND. The merchant must refund the customer without any item replacement or return. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.
    • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
    • REFUND_WITH_REPLACEMENT. The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer to resolve dispute call.
    • REPLACEMENT_WITHOUT_REFUND. The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer to resolve dispute call.

offer_type

  • offer_type

    enum

    The merchant-proposed offer type for the dispute. The possible values are:
    • REFUND. The merchant must refund the customer without any item replacement or return. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.
    • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the chargeback phase and occurs when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
    • REFUND_WITH_REPLACEMENT. The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer to resolve dispute call.
    • REPLACEMENT_WITHOUT_REFUND. The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer to resolve dispute call.

outcome

  • faulty_party

    enum

    required

    This is the party that was at fault. The possible values are:
    • BUYER. The customer is at fault.
    • SELLER. The merchant is at fault.
    • PARTNER. The partner is at fault.
    • NONE. No specific party is at fault.
  • adjudication_reason

    string

    required

    The reason for the decision.
  • resolution_date

    string

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

patch

  • op

    enum

    required

    The operation to complete.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    The JSON pointer to the target document location at which to complete the operation.
  • value

    number,integer,string,boolean,null,array,object

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

    string

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

patch_request

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

payment_by_other_means

  • charge_different_from_original

    boolean

    If true, indicates that a charge was made that is different from the original charge.
  • received_duplicate

    boolean

    If true, indicates that a duplicate transaction was received.
  • payment_method

    enum

    The payment method. The possible values are:
    • CASH. The payment method was cash.
    • CREDIT_CARD. The payment method was a credit card.
    • CHECK. The payment method was a check.
    • PAYPAL. The payment method was PayPal.

product_details

  • description

    string

    The product description.
  • product_received

    enum

    Indicates whether the product was, or was not, received or returned. The possible values are:
    • YES. The product was received.
    • NO. The product was not received.
    • RETURNED. The product was returned.
  • sub_reasons

    array (contains the sub_reason object)

    An array of sub-reasons for the product issue.
  • purchase_url

    string

    The URL where the customer purchased the product.
  • return_details

    object

    The return details for the product.

reason

  • reason

    enum

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other.

reference_dispute

  • id

    string

    The dispute ID of the partner dispute for which a PayPal dispute is created.
  • create_time

    string

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

referred_dispute

  • id

    string

    The ID of the PayPal-side 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.

  • dispute_flow

    enum

    The flow ID for the dispute being created. The possible values are:
    • THIRD_PARTY_CLAIM. Third-party claim information that the dispute requires custom handling.
    • THIRD_PARTY_DISPUTE. Third-party claim information that the dispute does not require any special handling. Defaults to default procedures.
  • reference_dispute

    object

    The details about the partner dispute.
  • transaction

    object

    The details about the transactions in the referred dispute.
  • extensions

    object

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

    enum

    The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • FRAUD_REVERSAL. An agent-created fraud reversal case.
    • ACH_RETURN. An ACH return from a bank.
    • CHARGEBACK. A chargeback from a credit card-issuing bank.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other
    • THIRD_PARTY. A case created for logging and record purposes in the PayPal system that corresponds to a case created on third-party platforms.
  • status

    enum

    The status of the dispute. The possible values are:
    • OPEN. The dispute is open.
    • CLOSED. The dispute is resolved.

    Read only.

  • refund_info

    object

    The payout details for the referred dispute.
  • outcome

    object

    The outcome of the case.
  • messages

    array (contains the referred_message object)

    An array of customer- or merchant-posted messages.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

referred_extensions

  • transaction_hold_info

    object

    The transaction hold information.
  • transaction_risk_info

    object

    The transaction risk information.

referred_item_info

  • id

    string

    The ID of the item.
  • category

    enum

    The category of the item in dispute. The possible values are:
    • COMPUTERS. Computer or related accessories.
    • HOME. Home appliances.
    • JEWELRY. Decorative items, ornaments, and so on.
    • ANTIQUES. Antiques and collectible items.
    • ENTERTAINMENT. Entertainment goods, such as video games, DVDs, and so on.
    • OTHER_TANGIBLES. Other material goods.
    • TRAVEL. Travel items and travel needs.
    • SERVICE. Services, such as installation, repair, and so on.
    • VIRTUAL_GOODS. Non-physical objects, such as online games.
    • OTHER_INTANGIBLES. Other intangible goods.
    • TICKETS. Tickets for events, such as sports, concerts, and so on.
  • description

    string

    The description 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. For information about the required information for each dispute reason and associated evidence type, see dispute reasons. The possible values are:
    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize purchase of the merchandise or service.
    • FRAUD_REVERSAL. An agent-created fraud reversal case.
    • ACH_RETURN. An ACH return from a bank.
    • CHARGEBACK. A chargeback from a credit card-issuing bank.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other
    • THIRD_PARTY. A case created for logging and record purposes in the PayPal system that corresponds to a case created on third-party platforms.
  • amount

    object

    The amount of the item in the dispute.
  • note

    string

    Any notes provided with the item.

referred_message

  • posted_by

    enum

    required

    The customer or merchant who posted the message. The possible values are:
    • BUYER. The customer posted the message.
    • SELLER. The merchant posted the message.

    Read only.

  • posted_time

    string

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

    Read only.

  • content

    string

    required

    The customer- or merchant-posted content.

    Minimum length: 0.

    Maximum length: 2000.

referred_subsequent_actions

refund_id

  • refund_id

    string

    The ID of the refunded transaction.

refund_info

  • recipient

    enum

    required

    The payout recipient information. The possible values are:
    • BUYER. The customer received the refund.
    • SELLER. The merchant received the refund.
  • amount

    object

    required

    The amount of the payout for the dispute.
  • create_time

    string

    required

    The date and time when the payout is made, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • transaction_id

    string

    The encrypted transaction ID, if available.
  • payout_type

    enum

    required

    The type of payout. The possible values are:
    • REVERSAL. The payout was made with the reversal of the original transaction, from the merchant to the customer.
    • COURTESY_CREDIT. The payout was made through a courtesy credit.
    • SELLER_PROTECTION_COVERAGE. The payout was made through Seller Protection coverage.
  • seller_protection_eligible

    boolean

    required

    Indicates whether the merchant is eligible for protection on the disputed transaction.
  • transaction_source

    enum

    required

    The site where the transaction occurred. The possible values are:
    • PAYPAL. The transaction occurred on PayPal.
    • OTHER. The transaction occurred on a third-party site other than PayPal.

require_evidence_request

  • action

    enum

    The action. Indicates whether the state change enables the customer or merchant to submit evidence. The possible values are:
    • BUYER_EVIDENCE. Changes the status of the dispute to WAITING_FOR_BUYER_RESPONSE.
    • SELLER_EVIDENCE. Changes the status of the dispute to WAITING_FOR_SELLER_RESPONSE.

response_tracking_info

  • carrier_name

    enum

    required

    The name of the shipment carrier for the transaction for this dispute. The possible values are:
    • UPS. United Parcel Service.
    • USPS. United States Postal Service.
    • FEDEX. Federal Express.
    • AIRBORNE_EXPRESS. Airborne Express.
    • DHL. DHL.
    • AIRSURE. AirSure.
    • ROYAL_MAIL. Royal Mail.
    • PARCELFORCE. Parcelforce Worldwide.
    • SWIFTAIR. Swiftair.
    • OTHER. Other.
    • UK_PARCELFORCE. Parcelforce UK.
    • UK_ROYALMAIL_SPECIAL. Royal Mail Special Delivery UK.
    • UK_ROYALMAIL_RECORDED. Royal Mail Recorded UK.
    • UK_ROYALMAIL_INT_SIGNED. Royal Mail International Signed.
    • UK_ROYALMAIL_AIRSURE. Royal Mail AirSure UK.
    • UK_UPS. United Parcel Service UK.
    • UK_FEDEX. Federal Express UK.
    • UK_AIRBORNE_EXPRESS. Airborne Express UK.
    • UK_DHL. DHL UK.
    • UK_OTHER. Other UK.
    • UK_CANNOT_PROV_TRACK. Cannot provide tracking UK.
    • CA_CANADA_POST. Canada Post.
    • CA_PUROLATOR. Purolator Canada.
    • CA_CANPAR. Canpar Courier Canada.
    • CA_LOOMIS. Loomis Express Canada.
    • CA_TNT. TNT Express Canada.
    • CA_OTHER. Other Canada.
    • CA_CANNOT_PROV_TRACK. Cannot provide tracking Canada.
    • DE_DP_DHL_WITHIN_EUROPE. DHL Parcel Europe.
    • DE_DP_DHL_T_AND_T_EXPRESS. DHL T and T Express.
    • DE_DHL_DP_INTL_SHIPMENTS. DHL DP International shipments.
    • DE_GLS. General Logistics Systems Germany.
    • DE_DPD_DELISTACK. DPD Tracking Germany.
    • DE_HERMES. Hermes Germany.
    • DE_UPS. United Parcel Service Germany.
    • DE_FEDEX. Federal Express Germany.
    • DE_TNT. TNT Express Germany.
    • DE_OTHER. Other Germany.
    • FR_CHRONOPOST. Chronopost France.
    • FR_COLIPOSTE. Coliposte France.
    • FR_DHL. DHL France.
    • FR_UPS. United Parcel Service France.
    • FR_FEDEX. Federal Express France.
    • FR_TNT. TNT Express France.
    • FR_GLS. General Logistics Systems France.
    • FR_OTHER. Other France.
    • IT_POSTE_ITALIA. Poste Italia.
    • IT_DHL. DHL Italy.
    • IT_UPS. United Parcel Service Italy.
    • IT_FEDEX. Federal Express Italy.
    • IT_TNT. TNT Express Italy
    • IT_GLS. General Logistics Systems Italy.
    • IT_OTHER. Other Italy.
    • AU_AUSTRALIA_POST_EP_PLAT. Australia Post EP Plat.
    • AU_AUSTRALIA_POST_EPARCEL. Australia Post Eparcel.
    • AU_AUSTRALIA_POST_EMS. Australia Post EMS.
    • AU_DHL. DHL Australia.
    • AU_STAR_TRACK_EXPRESS. StarTrack Express Australia.
    • AU_UPS. United Parcel Service Australia.
    • AU_FEDEX. Federal Express Australia.
    • AU_TNT. TNT Express Australia.
    • AU_TOLL_IPEC. Toll IPEC Australia.
    • AU_OTHER. Other Australia.
    • FR_SUIVI. Suivi FedEx France.
    • IT_EBOOST_SDA. Poste Italiane SDA.
    • ES_CORREOS_DE_ESPANA. Correos de Espana.
    • ES_DHL. DHL Spain.
    • ES_UPS. United Parcel Service Spain.
    • ES_FEDEX. Federal Express Spain.
    • ES_TNT. TNT Express Spain.
    • ES_OTHER. Other Spain.
    • AT_AUSTRIAN_POST_EMS. EMS Express Mail Service Austria.
    • AT_AUSTRIAN_POST_PPRIME. Austrian Post Prime.
    • BE_CHRONOPOST. Chronopost.
    • BE_TAXIPOST. Taxi Post.
    • CH_SWISS_POST_EXPRES. Swiss Post Express.
    • CH_SWISS_POST_PRIORITY. Swiss Post Priority.
    • CN_CHINA_POST. China Post.
    • HK_HONGKONG_POST. Hong Kong Post.
    • IE_AN_POST_SDS_EMS. Post SDS EMS Express Mail Service Ireland.
    • IE_AN_POST_SDS_PRIORITY. Post SDS Priority Ireland.
    • IE_AN_POST_REGISTERED. Post Registered Ireland.
    • IE_AN_POST_SWIFTPOST. Swift Post Ireland.
    • IN_INDIAPOST. India Post.
    • JP_JAPANPOST. Japan Post.
    • KR_KOREA_POST. Korea Post.
    • NL_TPG. TPG Post Netherlands.
    • SG_SINGPOST. SingPost Singapore.
    • TW_CHUNGHWA_POST. Chunghwa POST Taiwan.
    • CN_CHINA_POST_EMS. China Post EMS Express Mail Service.
    • CN_FEDEX. Federal Express China.
    • CN_TNT. TNT Express China.
    • CN_UPS. United Parcel Service China.
    • CN_OTHER. Other China.
    • NL_TNT. TNT Express Netherlands.
    • NL_DHL. DHL Netherlands.
    • NL_UPS. United Parcel Service Netherlands.
    • NL_FEDEX. Federal Express Netherlands.
    • NL_KIALA. KIALA Netherlands.
    • BE_KIALA. Kiala Point Belgium.
    • PL_POCZTA_POLSKA. Poczta Polska.
    • PL_POCZTEX. Pocztex.
    • PL_GLS. General Logistics Systems Poland.
    • PL_MASTERLINK. Masterlink Poland.
    • PL_TNT. TNT Express Poland.
    • PL_DHL. DHL Poland.
    • PL_UPS. United Parcel Service Poland.
    • PL_FEDEX. Federal Express Poland.
    • JP_SAGAWA_KYUU_BIN. Sagawa Kyuu Bin Japan.
    • JP_NITTSU_PELICAN_BIN. Nittsu Pelican Bin Japan.
    • JP_KURO_NEKO_YAMATO_UNYUU. Kuro Neko Yamato Unyuu Japan.
    • JP_TNT. TNT Express Japan.
    • JP_DHL. DHL Japan.
    • JP_UPS. United Parcel Service Japan.
    • JP_FEDEX. Federal Express Japan.
    • NL_PICKUP. Pickup Netherlands.
    • NL_INTANGIBLE. Intangible Netherlands.
    • NL_ABC_MAIL. ABC Mail Netherlands.
    • HK_FOUR_PX_EXPRESS. 4PX Express Hong Kong.
    • HK_FLYT_EXPRESS. Flyt Express Hong Kong.
  • carrier_name_other

    string

    The name of carrier in free-form text for unavailable carriers.
  • tracking_url

    string

    The URL to track the dispute-related transaction shipment.
  • tracking_number

    string

    required

    The number to track the dispute-related transaction shipment.

return_details

  • return_time

    string

    The date and time when the product was returned, Internet date and time format.
  • mode

    enum

    The method that the customer used to return the product. The possible values are:
    • SHIPPED. The customer shipped the product back to the merchant.
    • IN_PERSON. The customer returned the item to the merchant in person.
  • receipt

    boolean

    Indicates whether customer has the return receipt.
  • return_confirmation_number

    string

    The confirmation number for the item return.

seller

  • email

    string

    The email address for the merchant's PayPal account.
  • merchant_id

    string

    The PayPal account ID for the merchant.
  • name

    string

    The name of the merchant.

send_message

  • message

    string

    required

    The message sent by the merchant to the other party.

service_details

  • description

    string

    The service description.
  • service_started

    enum

    Indicates whether the service was started or cancelled. The possible values are:
    • YES. The service was started.
    • NO. The service was not started.
    • CANCELLED. The service was cancelled.
  • note

    string

    The customer specified note about the service usage.
  • sub_reasons

    array (contains the sub_reason object)

    An array of sub-reasons for the service issue.
  • purchase_url

    string

    The URL of the merchant or marketplace site where the customer purchased the service.

sub_reason

  • sub_reason

    enum

    The sub-reason for the service issue. The possible values are:
    • DAMAGED. The service was damaged.
    • DIFFERENT. The service was different from what was expected.
    • INCOMPLETE. The service was incomplete.
    • OTHER. Other.

subsequent_action

tracking_info_item

  • carrier_name

    string

    The name of the carrier for the shipment of the transaction for this dispute.
  • tracking_url

    string

    The URL to track the item shipment.
  • tracking_number

    string

    The tracking number for the dispute-related transaction shipment.
  • tracking_status

    enum

    Each Tracking info sent to PP should be mapped to tracking status. The possible values are:
    • INVALID. The tracking information is invalid.
    • NO_TRACKING. The tracking information is not available.
    • IN_TRANSIT. The disputed item is in transit.
    • LOST. The disputed item is lost.
    • DELIVERED. The disputed item was delivered to the customer.
  • note

    string

    Any notes about the tracking information.
  • posted_time

    string

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

    Read only.

transaction

  • id

    string

    The ID of the PayPal transaction.
  • items

    array (contains the referred_item_info object)

    An array of items in the transaction in the dispute.
  • status

    enum

    The transaction status. The possible values are:
    • COMPLETED. The transaction processing is complete.
    • 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. The payment for the transaction was partially refunded.
    • REFUNDED. The payment for the transaction was successfully refunded.
    • REVERSED. The payment for the transaction was reversed due to a chargeback or another type of reversal.
    • CANCELED. The payment for the transaction was canceled.
  • gross_amount

    object

    The gross amount of the 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_hold_info

  • hold_required

    boolean

    Indicates whether a temporary hold must be placed on the transaction.
  • id

    string

    The temporary hold ID.
  • reason

    string

    The reason for placing the temporary hold for the dispute.

transaction_id

  • transaction_id

    string

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

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. The possible values are:
    • COMPLETED. The transaction processing 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. The payment for the transaction was partially refunded.
    • REFUNDED. The payment for the transaction was successfully refunded.
    • REVERSED. The payment for the transaction was reversed due to a chargeback or other reversal type.
    • CANCELLED. The transaction is cancelled.
  • gross_amount

    object

    The gross amount of the transaction.
  • invoice_number

    string

    The ID of the invoice for 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, and email address.
  • seller

    object

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

    array (contains the item_info object)

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

    Read only.

transaction_risk_info

  • high_risk

    boolean

    Indicates whether the transaction is high risk and money must be recovered.
  • id

    string

    The recoup ID.
  • reason

    string

    The reason for recoup for the dispute,

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.

  • AMOUNT_SHOULD_NOT_BE_PASSED

    For MERCHANDISE_OR_SERVICE_NOT_RECEIVED dsiputes, refund amount cannot be specified in accept claim as this feature is not yet supported in PayPal Dispute system. You cannot specify the refund amount in an accept claim call.

  • AUTHORIZATION_ERROR

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

  • DATE_CAN_NOT_BE_IN_FUTURE

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

  • DISPUTE_REASON_NOT_ELIGIBLE

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

  • INSUFFICIENT_FUNDS

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

  • INTANGIBLE_ITEM_CANNOT_BE_RETURNED

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

  • INTERNAL_SERVICE_ERROR

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

  • INVALID_EVIDENCE_FILE

    The evidence file is not valid. The user can upload up to 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_FULFILLMENT

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

  • INVALID_PAGE_SIZE

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

  • INVALID_RETURN_SHIPPING_ADDRESS_FORMAT

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

  • INVALID_START_TIME_FORMAT

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

  • INVALID_START_TIME_RANGE

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

  • ITEM_ID_IS_MANDATORY_FOR_MULTIPLE_EVIDENCES

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

  • MANDATORY_PARAMETER_MISSING

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

  • MISSING_EVIDENCE_INFO

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

  • MISSING_EVIDENCE_TYPE

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

  • MISSING_REFUND_ID

    For PROOF_OF_REFUND, at least one refund ID is required but it is missing. Retry the request with a valid refund ID. For information, For details, see provide evidence. A refund ID is missing. You specify PROOF_OF_REFUND in the evidence_type parameter of a provide evidence call.

  • MISSING_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_RETURN_SHIPPING_ADDRESS

    For MERCHANDISE_OR_SERVICE_NOT_RECEIVED cases, return shipping address cannot be specified in accept claim as this applies only for MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes. You cannot specify the return shipping address in an accept claim call because the shipping address applies to only MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED disputes.

  • MISSING_TRACKING_INFO

    For PROOF_OF_FULFILLMENT, the tracking number and carrier name are required but they are missing. Retry the request. For information, see response_tracking_info. The tracking number and carrier name are missing. You specify PROOF_OF_FULFILLMENT in the evidence_type parameter of a provide evidence call.

  • PERMISSION_DENIED

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

  • RESOURCE_NOT_FOUND_ERROR

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

  • SHIPPING_ADDRESS_SHOULD_NOT_BE_PASSED

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

  • UNKNOWN_ERROR

    Unknown exception occurred. An unknown error occurred.

  • VALIDATION_ERROR

    Invalid request - see details. One or more validation errors occurred. See the details for specific validation errors.

Feedback
Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community