Skip to main content

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

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

This method is supported in Sandbox environment. To access the endpoint, just replace the apiz.ebay.com root URI with apiz.sandbox.ebay.com

URI parameters

ParameterTypeDescription
payment_dispute_idstringThis parameter is used to specify the unique identifier of the payment dispute being retrieved.

Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.

Occurrence: Required

HTTP request headers

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

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

OAuth scope

This request requires an access token created with the authorization code 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.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* PaymentDispute */
"note" : "string",
}

Response fields

Output container/fieldTypeDescription
amountSimpleAmount

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

Occurrence: Always

amount.currencyCurrencyCodeEnum

A 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 always returned with the amount container.

Occurrence: Conditional

amount.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

availableChoicesarray of SellerDecisionEnum

The 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

buyerProvidedInfoFromBuyer

This container is returned if the buyer is returning one or more line items in an order that is associated with the payment dispute, and that buyer has provided return shipping tracking information and/or a note about the return.

Occurrence: Conditional

buyerProvided.contentOnHoldboolean

When the value of this field is true it indicates that the buyer's note regarding the payment dispute (i.e., the buyerProvided.note field,) is on hold. When this is the case, the buyerProvided.note field will not be returned.

When the value of this field is false, it is not returned.

Occurrence: Conditional

buyerProvided.notestring

This field shows any note that was left by the buyer in regard to the dispute.

Occurrence: Conditional

buyerProvided.returnShipmentTrackingarray of TrackingInfo

This array shows shipment tracking information for one or more shipping packages being returned to the buyer after a payment dispute.

Occurrence: Conditional

buyerProvided.returnShipmentTracking.shipmentTrackingNumberstring

This string value represents the shipment tracking number of the package.

Occurrence: Conditional

buyerProvided.returnShipmentTracking.shippingCarrierCodestring

This string value represents the shipping carrier used to ship the package.

Occurrence: Conditional

buyerUsernamestring

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

Occurrence: Always

closedDatestring

The 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

evidencearray of DisputeEvidence

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

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

This enumeration value shows the type of evidential file provided.

Occurrence: Conditional

evidence.filesarray of FileInfo

This array shows the name, ID, file type, and upload date for each provided file.

Occurrence: Conditional

evidence.files.fileIdstring

The unique identifier of the evidence file.

Occurrence: Conditional

evidence.files.fileTypestring

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

Occurrence: Conditional

evidence.files.namestring

The seller-provided name of the evidence file.

Occurrence: Conditional

evidence.files.uploadedDatestring

The timestamp in this field shows the date/time when the seller uploaded the 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 OrderLineItems

This array shows one or more order line items associated with the evidential document that has been provided.

Occurrence: Conditional

evidence.lineItems.itemIdstring

The unique identifier of the eBay listing associated with the order.

Occurrence: Always

evidence.lineItems.lineItemIdstring

The unique identifier of the line item within the order.

Occurrence: Always

evidence.providedDatestring

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

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

The 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.shipmentTrackingarray of TrackingInfo

This array shows the shipping carrier and shipment tracking number associated with each shipment package of the order. This array is returned under the evidence container if the seller has provided shipment tracking information as evidence to support PROOF_OF_DELIVERY for an INR-related payment dispute.

Occurrence: Conditional

evidence.shipmentTracking.shipmentTrackingNumberstring

This string value represents the shipment tracking number of the package.

Occurrence: Conditional

evidence.shipmentTracking.shippingCarrierCodestring

This string value represents the shipping carrier used to ship the package.

Occurrence: Conditional

evidenceRequestsarray of EvidenceRequest

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

Occurrence: Conditional

evidenceRequests.evidenceIdstring

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

This enumeration value shows the type of evidential document provided.

Occurrence: Conditional

evidenceRequests.lineItemsarray of OrderLineItems

This array shows one or more order line items associated with the evidential document that has been provided.

Occurrence: Conditional

evidenceRequests.lineItems.itemIdstring

The unique identifier of the eBay listing associated with the order.

Occurrence: Always

evidenceRequests.lineItems.lineItemIdstring

The unique identifier of the line item within the order.

Occurrence: Always

evidenceRequests.requestDatestring

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

The 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

lineItemsarray of OrderLineItems

This array is used to identify one or more order line items associated with the payment dispute. There will always be at least one itemId/lineItemId pair returned in this array.

Occurrence: Always

lineItems.itemIdstring

The unique identifier of the eBay listing associated with the order.

Occurrence: Always

lineItems.lineItemIdstring

The unique identifier of the line item within the order.

Occurrence: Always

monetaryTransactionsarray of MonetaryTransaction

This array provide details about one or more monetary transactions that occur as part of a payment dispute. This array is only returned once one or more monetary transacations occur with a payment dispute.

Occurrence: Conditional

monetaryTransactions.datestring

This timestamp indicates when the monetary transaction occurred. A date is returned for all monetary transactions.

The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z.

Occurrence: Conditional

monetaryTransactions.typeMonetaryTransactionTypeEnum

This enumeration value indicates whether the monetary transaction is a charge or a credit to the seller.

Occurrence: Conditional

monetaryTransactions.reasonMonetaryTransactionReasonEnum

This enumeration value indicates the reason for the monetary transaction.

Occurrence: Conditional

monetaryTransactions.amountDisputeAmount

The amount involved in the monetary transaction. For active cross-border trade orders, the currency conversion and exchangeRate fields will be displayed as well.

Occurrence: Conditional

monetaryTransactions.amount.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.

This field is only returned if/when currency conversion was applied by eBay.

Occurrence: Conditional

monetaryTransactions.amount.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.

This field is only returned if/when currency conversion was applied by eBay.

Occurrence: Conditional

monetaryTransactions.amount.currencyCurrencyCodeEnum

A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

monetaryTransactions.amount.exchangeRatestring

The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field.

This field is only returned if/when currency conversion was applied by eBay.

Occurrence: Conditional

monetaryTransactions.amount.valuestring

The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.

Occurrence: Conditional

notestring

This field shows information that the seller provides about the dispute, such as the basis for the dispute, any relevant evidence, tracking numbers, and so forth.

This field is limited to 1000 characters.

Occurrence: Conditional

openDatestring

The 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

orderIdstring

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

Occurrence: Always

paymentDisputeIdstring

This is the unique identifier of the payment dispute. This is the same identifier that is passed in to the call URI. This identifier is automatically created by eBay once the payment dispute comes into the eBay system.

Occurrence: Always

paymentDisputeStatusDisputeStateEnum

The 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

reasonDisputeReasonEnum

The 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

resolutionPaymentDisputeOutcomeDetail

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

Occurrence: Conditional

resolution.feesSimpleAmount

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

A 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 always returned with the amount container.

Occurrence: Conditional

resolution.fees.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

resolution.protectedAmountSimpleAmount

This container shows the amount of money that the seller is protected against in a payment dispute under eBay's seller protection policy.

Occurrence: Conditional

resolution.protectedAmount.currencyCurrencyCodeEnum

A 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 always returned with the amount container.

Occurrence: Conditional

resolution.protectedAmount.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

resolution.protectionStatusProtectionStatusEnum

This 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

resolution.reasonForClosureOutcomeEnum

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

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

A 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 always returned with the amount container.

Occurrence: Conditional

resolution.recoupAmount.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

resolution.totalFeeCreditSimpleAmount

This container shows the amount of money in selling fee credits due back to the seller after a payment dispute is settled.

Occurrence: Conditional

resolution.totalFeeCredit.currencyCurrencyCodeEnum

A 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 always returned with the amount container.

Occurrence: Conditional

resolution.totalFeeCredit.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

respondByDatestring

The timestamp in this field shows the date/time when the seller must response 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

returnAddressReturnAddress

This container gives the address where the order will be returned to. This container is returned if the seller is accepting the payment dispute and will issue a refund to the buyer once the item is returned to this address.

Occurrence: Conditional

returnAddress.addressLine1string

The first line of the street address.

Occurrence: Conditional

returnAddress.addressLine2string

The second line of the street address. This line is not always necessarily, but is often used for apartment number or suite number, or other relevant information that can not fit on the first line.

Occurrence: Conditional

returnAddress.citystring

The city of the return address.

Occurrence: Conditional

returnAddress.countryCountryCodeEnum

The country's two-letter, ISO 3166-1 country code. See the enumeration type for a country's value.

Occurrence: Conditional

returnAddress.countystring

The county of the return address. Counties are not applicable to all countries.

Occurrence: Conditional

returnAddress.fullNamestring

The full name of return address owner.

Occurrence: Conditional

returnAddress.postalCodestring

The postal code of the return address.

Occurrence: Conditional

returnAddress.primaryPhonePhone

This container shows the seller's primary phone number associated with the return address.

Occurrence: Conditional

returnAddress.primaryPhone.countryCodestring

The two-letter, ISO 3166 code associated with the seller's phone number. This field is needed if the buyer is located in a different country than the seller. It is also OK to provide if the buyer and seller are both located in the same country

See CountryCodeEnum for a list of supported values.

Occurrence: Conditional

returnAddress.primaryPhone.numberstring

The seller's primary phone number associated with the return address. When this number is provided in a contestPaymentDispute or contestPaymentDispute method, it is provided as one continuous numeric string, including the area code. So, if the phone number's area code was '408', a number in this field may look something like this:

"number" : "4088084356"

If the buyer is located in a different country than the seller, the seller's country code will need to be specified in the countryCode field.

Occurrence: Conditional

returnAddress.stateOrProvincestring

The state or province of the return address.

Occurrence: Conditional

revisioninteger

This 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: Always

sellerResponseSellerResponseEnum

The 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 and agreeing to issue a refund as long as the buyer returns the item, or contesting the payment dispute. This field is returned as soon as the seller makes an initial decision on the payment dispute.

Occurrence: Conditional

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
404Invalid Payment Dispute Id
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

Warnings

This call has no warnings.

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.

GEThttps://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5********2

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.

GEThttps://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5********4

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.

GEThttps://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5********3

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.

Sample 4: Get resolved payment dispute

Get a resolved INR-related payment dispute that was accepted by the seller.

Input

Seller inputs a unique payment dispute identifier into the call URI.

GEThttps://apiz.ebay.com/sell/fulfillment/v1/payment_dispute/5********0

Output

As indicated by the paymentDisputeStatus field, the 'Item not received' payment dispute between buyer and seller is closed. As indicated in the resolution.reasonForClosure field, the seller accepted the dispute. The buyer is automatically refunded by eBay, and eBay recoups that money by charging the seller for the buyer refund amount. The seller is eligible to receive a credit for the final value fees. The amount of money that eBay is recouping is shown in the resolution.recoupAmount container and the amount of fee credits due back to the seller is shown in the resolution.totalFeeCredit container.

The monetaryTransactions container in the response summarizes the single monetary transaction that occurred with this payment dispute, and this is the charge from eBay to the seller to recoup the refund amount issued to the buyer. This order was an active cross-border trade order where a Canadian seller created a listing on the eBay US marketplace. Due to this scenario, the monetaryTransactions.amount container shows the amount of the order in US currency (paid by the buyer), and what that value converts to in Canadian dollars. The exchange rate used for the conversion is also shown.

Got thoughts? Click the feedback button – your insights help us improve!