fulfillment API1.11.0

getPaymentDispute

GET
/payment_dispute/{payment_dispute_id}
This method retrieves detailed information on a specific payment dispute. The payment dispute identifier is passed in as path parameter at the end of the call URI.

Below is a summary of the information that is retrieved:
  • Current status of payment dispute
  • Amount of the payment dispute
  • Reason the payment dispute was opened
  • Order and line items associated with the payment dispute
  • Seller response options if an action is currently required on the payment dispute
  • Details on the results of the payment dispute if it has been closed
  • Details on any evidence that was provided by the seller to fight the payment dispute

Input

Resource URI (production)

GET https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/{payment_dispute_id}

URI parameters

ParameterTypeDescription
payment_dispute_idstringThis is the unique identifier of the payment dispute. This path parameter must be passed in at the end of the call URI to identify the payment dispute to retrieve. This identifier is automatically created by eBay once the payment dispute comes into the eBay managed payments system. The unique identifier for payment disputes is returned in the paymentDisputeId field in the getPaymentDisputeSummaries response.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.payment.dispute

See OAuth access tokens for more information.

Output

HTTP response headers

{ /* PaymentDispute */ }
Output container/fieldTypeDescription
paymentDisputeIdstringThis is the unique identifier of the payment dispute. This is the same identifier that is pass in to the call URI. This identifier is automatically created by eBay once the payment dispute comes into the eBay managed payments system.

Occurrence: Always

paymentDisputeStatusDisputeStateEnumThe enumeration value in this field gives the current status of the payment dispute. The status of a payment dispute partially determines other fields that are returned in the response.

Occurrence: Always

reasonDisputeReasonEnumThe enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute.

Occurrence: Always

orderIdstringThis is the unique identifier of the order involved in the payment dispute.

Note: eBay rolled out a new Order ID format in June 2019. The legacy APIs still support the old and new order ID format to identify orders, but only the new order ID format is returned in REST-based API responses.

Occurrence: Always

openDatestringThe timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Always

closedDatestringThe timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

respondByDatestringThe timestamp in this field shows the date/time when the seller must respond to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that currently require action by the seller, that same seller should look at the availableChoices array to see the available actions.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

lineItemsarray of OrderLineItemsThis array is used to identify one or more order line items associated with the payment dispute.

Occurrence: Always

lineItems.itemIdstringThe unique identifier of the eBay listing associated with the order.

Occurrence: Always

lineItems.lineItemIdstringThe unique identifier of the line item within the order. The lineItemId value is created once the buyer actually buys the item, or if there is a commitment to buy (either an auction that is won by the buyer or other listing that does not require immediate payment).

Occurrence: Always

amountSimpleAmountThis container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace.

Occurrence: Always

amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

amount.valuestringThe monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

resolutionPaymentDisputeOutcomeDetailThis container gives details about a payment dispute that has been resolved. This container is only returned for resolved/closed payment disputes.

Occurrence: Conditional

resolution.reasonForClosureOutcomeEnumThe enumeration value returned in this field indicates the outcome of the payment dispute for the seller. This field is always returned once the payment dispute is resolved.

Occurrence: Conditional

resolution.feesSimpleAmountThis container will show the dollar value of any fees associated with the payment dispute. This container is only returned if there are fees associated with the payment dispute.

Occurrence: Conditional

resolution.fees.currencyCurrencyCodeEnumA three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

resolution.fees.valuestringThe monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

resolution.recoupAmountSimpleAmountThis container shows the dollar amount being recouped from the seller. This container is empty if the seller wins the payment dispute or if the seller is fully protected by eBay's seller protection policy.

Occurrence: Conditional

resolution.recoupAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

resolution.recoupAmount.valuestringThe monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

resolution.protectionStatusProtectionStatusEnumThis enumeration value indicates if the seller is fully protected, partially protected, or not protected by eBay for the payment dispute. This field is always returned once the payment dispute is resolved.

Occurrence: Conditional

returnAddressAddressThis container gives the return address of the seller. An item under payment dispute could be returned to this address if the buyer returns it, but there is no guarantee that buyer would return the item.

Occurrence: Conditional

returnAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

returnAddress.addressLine2stringThe second line of the street address. This field can be used for additional address information, such as a suite or apartment number. This field will be returned if defined for the shipping address.

Occurrence: Conditional

returnAddress.citystringThe city of the shipping destination.

Occurrence: Conditional

returnAddress.countryCodeCountryCodeEnumThe country of the shipping destination, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany.

Occurrence: Always

returnAddress.countystringThe county of the shipping destination. Counties typically, but not always, contain multiple cities or towns. This field is returned if known/available.

Occurrence: Conditional

returnAddress.postalCodestringThe postal code of the shipping destination. Usually referred to as Zip codes in the US. Most countries have postal codes, but not all. The postal code will be returned if applicable.

Occurrence: Conditional

returnAddress.stateOrProvincestringThe state or province of the shipping destination. Most countries have states or provinces, but not all. The state or province will be returned if applicable.

Occurrence: Conditional

sellerResponseSellerResponseEnumThe enumeration value returned in this field indicates how the seller has responded to the payment dispute. The seller has the option of accepting the payment dispute and agreeing to issue a refund, accepting the payment dispute, agreeing to issue a refund, and requesting that the buyer return the item, or contesting the payment dispute. If the seller has yet to make a decision on the payment dispute, the enumeration value returned in this field will be SELLER_RESPONSE_OVERDUE.

Occurrence: Conditional

availableChoicesarray of SellerDecisionEnumThe value(s) returned in this array indicate the choices that the seller has when responding to the payment dispute. Once the seller has responded to the payment dispute, this field will no longer be shown, and instead, the sellerResponse field will show the decision that the seller made.

Occurrence: Conditional

revisionintegerThis integer value indicates the revision number of the payment dispute. Each time an action is taken against a payment dispute, this integer value increases by 1.

Occurrence: Conditional

evidencearray of DisputeEvidenceThis container shows any evidence that has been provided by the seller to contest the payment dispute. Evidence may include shipment tracking information, proof of authentication documentation, image(s) to proof that an item is as described, or financial documentation/invoice.

This container is only returned if the seller has provided at least one document used as evidence against the payment dispute.

Occurrence: Conditional

evidence.evidenceIdstringUnique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set.

Occurrence: Conditional

evidence.requestDatestringThe timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidence.respondByDatestringThe timestamp in this field shows the date/time when the seller was expected to provide a requested evidential document to eBay.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidence.providedDatestringThe timestamp in this field shows the date/time when the seller provided a requested evidential document to eBay.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidence.lineItemsarray of OrderLineItemsThis array shows one or more order line items associated with the evidential document has been provided.

Occurrence: Conditional

evidence.lineItems.itemIdstringThe unique identifier of the eBay listing associated with the order.

Occurrence: Always

evidence.lineItems.lineItemIdstringThe unique identifier of the line item within the order. The lineItemId value is created once the buyer actually buys the item, or if there is a commitment to buy (either an auction that is won by the buyer or other listing that does not require immediate payment).

Occurrence: Always

evidence.shipmentTrackingarray of TrackingInfoThis array shows the shipping carrier and shipment tracking number associated with each shipment package of the order. This array is returned if the seller has provided shipment tracking information as evidence to support PROOF_OF_DELIVERY.

Occurrence: Conditional

evidence.shipmentTracking.shippingCarrierCodestringThis string value represents the shipping carrier used to ship the package.

Occurrence: Conditional

evidence.shipmentTracking.shipmentTrackingNumberstringThis string value represents the shipment tracking number of the package.

Occurrence: Conditional

evidence.evidenceTypeEvidenceTypeEnumThe enumeration value returned in this field indicates the type of evidence provided. Two examples include an image file if the dispute reason is SIGNIFICANTLY_NOT_AS_DESCRIBED, or shipment tracking information if the dispute reason is ITEM_NOT_RECEIVED.

Occurrence: Conditional

evidence.filesarray of FileInfoThis array shows the name, ID, file type, and upload date for each provided file.

Occurrence: Conditional

evidence.files.fileIdstringThe unique identifier of the evidence file.

Occurrence: Conditional

evidence.files.uploadedDatestringThe timestamp in this field shows the date/time when the seller uploaded the evidential file to eBay.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidence.files.namestringThe seller-provided name of the evidence file.

Occurrence: Conditional

evidence.files.fileTypestringThe type of file uploaded. Supported file extensions are .JPEG, .JPG, and .PNG., and maximum file size allowed is 1.5 MB.

Occurrence: Conditional

evidenceRequestsarray of EvidenceRequestThis container is returned if one or more evidence documents are being requested from the seller.

Occurrence: Conditional

evidenceRequests.evidenceIdstringUnique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set.

Occurrence: Conditional

evidenceRequests.requestDatestringThe timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidenceRequests.respondByDatestringThe timestamp in this field shows the date/time when the seller is expected to provide a requested evidential document to eBay.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

evidenceRequests.lineItemsarray of OrderLineItemsThis array shows one or more order line items associated with the evidential document has been provided.

Occurrence: Conditional

evidenceRequests.lineItems.itemIdstringThe unique identifier of the eBay listing associated with the order.

Occurrence: Always

evidenceRequests.lineItems.lineItemIdstringThe unique identifier of the line item within the order. The lineItemId value is created once the buyer actually buys the item, or if there is a commitment to buy (either an auction that is won by the buyer or other listing that does not require immediate payment).

Occurrence: Always

evidenceRequests.evidenceTypeEvidenceTypeEnumThis enumeration value shows the type of evidential document provided.

Occurrence: Conditional

buyerProvidedInfoFromBuyerThis container is returned if the buyer has provided a note about the payment dispute and/or has provided return shipment tracking information.

Occurrence: Conditional

buyerProvided.returnShipmentTrackingarray of TrackingInfoThis array shows shipment tracking information for one or more shipping packages being returned to the seller after a payment dispute.

Occurrence: Conditional

buyerProvided.returnShipmentTracking.shippingCarrierCodestringThis string value represents the shipping carrier used to ship the package.

Occurrence: Conditional

buyerProvided.returnShipmentTracking.shipmentTrackingNumberstringThis string value represents the shipment tracking number of the package.

Occurrence: Conditional

buyerProvided.notestringThis field shows any note that was left by the buyer for in regards to the dispute.

Occurrence: Conditional

buyerUsernamestringThis is the eBay user ID of the buyer that initiated the payment dispute.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
404Not found
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
33000API_FULFILLMENTAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
33001API_FULFILLMENTREQUESTInvalid Payment Dispute Id

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get fraud-related payment dispute

Get fraud-related payment dispute that seller accepts.

Input

Seller inputs a unique payment dispute identifier into the call URI.
GET
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5000250742

Output

The payment dispute was successfully retrieved. For this payment dispute, the buyer opened the payment dispute because they believed the transaction to be fraudulent, meaning they did not make this purchase. The seller has agreed to accept the payment dispute, and the seller will be refunded the full purchase total of $250.00.

Sample 2: Get SNAD-related payment dispute

Get SNAD-related payment dispute that seller contests with evidence file.

Input

Seller inputs a unique payment dispute identifier into the call URI.
GET
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5000250744

Output

The payment dispute was successfully retrieved. For this payment dispute, the buyer opened the payment dispute because they believed the item to be not as described in the listing. The seller has decided to contest the payment dispute, and the seller has provided an image file to prove that the item is as described. Next, eBay will review the provided file and investigate further before making a decision on this dispute.

Sample 3: Get INR-related payment dispute

Get INR-related payment dispute that seller contests with a shipment tracking.

Input

Seller inputs a unique payment dispute identifier into the call URI.
GET
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5000250743

Output

The payment dispute was successfully retrieved. For this payment dispute, the buyer opened the payment dispute because they claim to have not received the item that they paid for. The seller has decided to contest the payment dispute, and the seller has provided shipment tracking information to help prove that the item was shipped/delivered to the buyer. Next, eBay will review the shipment tracking history and investigate further before making a decision on this dispute.