Business Platforms and marketplacesPlatforms Enterprise

Business Platforms and marketplaces Enterprise

Sections

Business Platforms and marketplaces Enterprise

Help

FAQs Account help Technical support API Status

APIs & SDKs

JavaScript SDK React SDK REST API Server SDKs Codes Webhook events iOS Android

On this page

Resources

GitHub repo

Postman repo

PayPal.com

llms.txt

Where to find us

Developer blog

Community

Help Center

Sign up for updates

Where to hear from us

X

YouTube

LinkedIn

Discord

Legal

Privacy Policy

Terms of Service

Developer Agreement

© 2026 PayPal. All rights reserved.

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Billing Disputes Properties

The billing issue details.

duplicate_transactionobject<duplicate_transaction>Optional

The duplicate transaction details.

duplicate_transaction properties

2 properties

received_duplicatebooleanOptional

If `true`, indicates that a duplicate transaction was received.

original_transactionobject<transaction_info>Optional

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

transaction_info properties

13 properties

buyer_transaction_idstringOptional

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

Match^[A-Za-z0-9-]+$Length1 <= length <= 255

seller_transaction_idstringOptional

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

Match^[A-Za-z0-9-]+$Length1 <= length <= 255

reference_idstringOptional

The ID, as seen by the partner, for this transaction.

Match^.*$Length1 <= length <= 255

create_timestring<date_time>Optional

The date and time when the transaction was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *`yyyy`*-*`MM`*-*`dd`*`T`*`HH`*:*`mm`*:*`ss`*.*`SSS`*`Z`.

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

transaction_statusenumOptional

The transaction status.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"COMPLETED"
"UNCLAIMED"
"DENIED"
"FAILED"
"HELD"
"PENDING"
"PARTIALLY_REFUNDED"
"REFUNDED"
"REVERSED"
"CANCELLED"

gross_amountobject<money>Optional

The gross amount of the transaction.

money properties

2 properties

currency_codestring<currency_code>Required

The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Formatppaas_common_currency_code_v2Length3 <= length <= 3

valuestringRequired

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](/api/rest/reference/currency-codes/).

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length0 <= length <= 32

gross_assetobject<cryptocurrency>Optional

The gross asset of the transaction.

cryptocurrency properties

4 properties

asset_symbolenum<cryptocurrency_symbol>Required

The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

Match^[0-9A-Za-z]{1,10}$Length1 <= length <= 10

Allowed values

"BTC"
"ETH"
"BCH"
"LTC"
"PYUSD"
"LINK"
"SOL"
"MATIC"

quantitystring<cryptocurrency_quantity>Required

The quantity of a cryptocurrency asset. This is a decimal number with a scale defined for each cryptocurrency by its founders. For example, Bitcoin (BTC) has 8 as its scale, Ethereum (ETH) has 18 as its scale. The PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin. including its forks or offshoots, as well as Ethereum.

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length1 <= length <= 40

quantity_in_subunitsstring<cryptocurrency_subunits_quantity>Optional

The quantity of a cryptocurrency asset in the currency's sub units.
Amount is an integer in a string format.
Floating point should be avoided to avoid precision errors. For example:

Bitcoin(BTC) has 8 decimals,

so 1 BTC will be represented as 100000000 (1 followed by 8 zeroes).

Ethereum(ETH) has 18 decimals,

so 1 ETH will be represented as 1000000000000000000 (1 followed by 18 zeroes).

Match^-?[0-9]+$Length1 <= length <= 81

decimalsinteger<cryptocurrency_decimals>Optional

The number of decimal digits supported by this cryptocurrency. For example, for Bitcoin this value is 8 because there are 10^8 satoshis in one Bitcoin and for Ethereum it's 18 since there are 10^18 wei in one Ether.

Range0 <= value <= 40

invoice_numberstringOptional

The ID of the invoice for the payment.

Match^[A-Za-z0-9:\-|]+$Length1 <= length <= 127

customstringOptional

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

Match^(.|\r?\n)*$Length1 <= length <= 2000

buyerobject<buyer>Optional

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

buyer properties

1 property

namestringOptional

The customer's name.

Match^[^~!@#$%^*()_{}:|\t\n/]+$Length1 <= length <= 2000

sellerobject<seller>Optional

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

seller properties

3 properties

emailstring<email_address>Optional

The email address for the merchant's PayPal account.

Match^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$Formatppaas_common_email_address_v2Length3 <= length <= 254

merchant_idstringOptional

The PayPal account ID for the merchant.

Match^[0-9A-Za-z]+$Length1 <= length <= 255

namestringOptional

The name of the merchant.

Match^[^~!@#$%^*()_{}:|\t\n/]+$Length1 <= length <= 2000

itemsobject<item_info>[]Optional

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

Items1 <= length <= 100

item_info properties

15 properties

item_idstringOptional

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.

Match^.*$Length1 <= length <= 255

item_namestringOptional

The item name.

Match^.*$Length1 <= length <= 2000

item_descriptionstringOptional

The item description.

Match^(.|\r?\n)*$Length1 <= length <= 2000

item_quantitystringOptional

The count of the item in the dispute. Must be a whole number.

Match^[1-9][0-9]{0,9}$Length1 <= length <= 10

partner_transaction_idstringOptional

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.

Match^[A-Za-z0-9]+$Length1 <= length <= 255

reasonenum<dispute_reason>Optional

The reason for the item-level dispute. For information about the required information for each dispute reason and associated evidence type, see dispute reasons.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"MERCHANDISE_OR_SERVICE_NOT_RECEIVED"
"MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED"
"UNAUTHORISED"
"CREDIT_NOT_PROCESSED"
"DUPLICATE_TRANSACTION"
"INCORRECT_AMOUNT"
"PAYMENT_BY_OTHER_MEANS"
"CANCELED_RECURRING_BILLING"
"PROBLEM_WITH_REMITTANCE"
"OTHER"

dispute_amountobject<money>Optional

The amount of the item in the dispute.

money properties

2 properties

currency_codestring<currency_code>Required

The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Formatppaas_common_currency_code_v2Length3 <= length <= 3

valuestringRequired

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](/api/rest/reference/currency-codes/).

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length0 <= length <= 32

notesstringOptional

Any notes provided with the item.

Match^(.|\r?\n)*$Length1 <= length <= 2000

item_typeenum<item_type>Optional

The type of the item which has the issue.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"PRODUCT"
"SERVICE"
"BOOKING"
"DIGITAL_DOWNLOAD"

product_detailsitem_product_detailsOptional

service_detailsitem_service_detailsOptional

booking_detailsitem_booking_detailsOptional

digital_download_detailsitem_digital_download_detailsOptional

cancellation_detailsitem_cancellation_detailsOptional

agreed_refund_detailsitem_agreed_refund_detailsOptional

payment_processorpayment_processorOptional

incorrect_transaction_amountobject<incorrect_transaction_amount>Optional

The incorrect transaction amount details.

incorrect_transaction_amount properties

3 properties

correct_transaction_amountobject<money>Optional

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

money properties

2 properties

currency_codestring<currency_code>Required

The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Formatppaas_common_currency_code_v2Length3 <= length <= 3

valuestringRequired

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](/api/rest/reference/currency-codes/).

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length0 <= length <= 32

correct_transaction_assetobject<cryptocurrency>Optional

The correct asset quantity of the transaction.

cryptocurrency properties

4 properties

asset_symbolenum<cryptocurrency_symbol>Required

The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

Match^[0-9A-Za-z]{1,10}$Length1 <= length <= 10

Allowed values

"BTC"
"ETH"
"BCH"
"LTC"
"PYUSD"
"LINK"
"SOL"
"MATIC"

quantitystring<cryptocurrency_quantity>Required

The quantity of a cryptocurrency asset. This is a decimal number with a scale defined for each cryptocurrency by its founders. For example, Bitcoin (BTC) has 8 as its scale, Ethereum (ETH) has 18 as its scale. The PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin. including its forks or offshoots, as well as Ethereum.

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length1 <= length <= 40

quantity_in_subunitsstring<cryptocurrency_subunits_quantity>Optional

The quantity of a cryptocurrency asset in the currency's sub units.
Amount is an integer in a string format.
Floating point should be avoided to avoid precision errors. For example:

Bitcoin(BTC) has 8 decimals,

so 1 BTC will be represented as 100000000 (1 followed by 8 zeroes).

Ethereum(ETH) has 18 decimals,

so 1 ETH will be represented as 1000000000000000000 (1 followed by 18 zeroes).

Match^-?[0-9]+$Length1 <= length <= 81

decimalsinteger<cryptocurrency_decimals>Optional

The number of decimal digits supported by this cryptocurrency. For example, for Bitcoin this value is 8 because there are 10^8 satoshis in one Bitcoin and for Ethereum it's 18 since there are 10^18 wei in one Ether.

Range0 <= value <= 40

correct_transaction_timestring<date_time>Optional

The date and time when the customer created the transaction, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

payment_by_other_meansobject<payment_by_other_means>Optional

The payment by other means details.

payment_by_other_means properties

4 properties

charge_different_from_originalbooleanOptional

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

received_duplicatebooleanOptional

If `true`, indicates that a duplicate transaction was received.

payment_methodenumOptional

The payment method.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"CASH"
"CREDIT_CARD"
"CHECK"
"PAYPAL"
"DEBIT_CARD"
"GIFT_CARD"
"BANK_TRANSFER"

payment_instrument_suffixstringOptional

Last 2-4 characters of the payment instrument. For payment_method CHECK, payment_instrument_suffix entered must be of minimum length 2-4 characters. For payment_method CREDIT_CARD, DEBIT_CARD, GIFT_CARD, BANK_TRANSFER, payment_instrument_suffix entered must be of length 4.

Match^.*$Length2 <= length <= 4

credit_not_processedobject<credit_not_processed>Optional

The credit not processed details.

credit_not_processed properties

6 properties

issue_typeenumOptional

The issue type.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"PRODUCT"
"SERVICE"

expected_refundobject<money>Optional

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

money properties

2 properties

currency_codestring<currency_code>Required

The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Formatppaas_common_currency_code_v2Length3 <= length <= 3

valuestringRequired

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](/api/rest/reference/currency-codes/).

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length0 <= length <= 32

cancellation_detailsobject<cancellation_details>Optional

The cancellation details.

cancellation_details properties

4 properties

cancellation_datestring<date_time>Optional

The date and time of the cancellation, in [Internet date and time format](http://tools.ietf.org/html/rfc3339#section-5.6).

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

cancellation_numberstringOptional

The cancellation number.

Match^.*$Length1 <= length <= 127

cancelledbooleanOptional

Indicates whether the dispute was canceled.

cancellation_modeenumOptional

Indicates the mode used for order cancellation.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"CANCELLED_PAYPAL_BILLING_AGREEMENT"
"WEBSITE"
"PHONE"
"EMAIL"
"WRITTEN"
"IN_PERSON"

product_detailsobject<product_details>Optional

The product information.

product_details properties

7 properties

descriptionstringOptional

The product description.

Match^(.|\r?\n)*$Length1 <= length <= 2000

product_receivedenumOptional

Indicates whether the product was, or was not, received or returned.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"YES"
"NO"
"RETURNED"

product_received_timestring<date_time>Optional

The date and time when product was delivered.

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

expected_delivery_datestring<date_time>Optional

The expected delivery date and time of the product.

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

sub_reasonsarray<sub_reasons>Optional

An array of sub-reasons for the product issue.

Items1 <= length <= 10

purchase_urlstringOptional

The URL where the customer purchased the product.

Formaturi

return_detailsobject<return_details>Optional

The return details for the product.

return_details properties

5 properties

return_timestring<date_time>Optional

The date and time when the product was returned, [Internet date and time format](http://tools.ietf.org/html/rfc3339#section-5.6).

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

modeenumOptional

The method that the customer used to return the product.

Match^[A-Z_]+$Length1 <= length <= 255

Allowed values

"SHIPPED"
"IN_PERSON"

receiptbooleanOptional

Indicates whether customer has the return receipt.

return_confirmation_numberstringOptional

The confirmation number for the item return.

Match^[A-Za-z0-9:\-]+$Length1 <= length <= 255

returnedbooleanOptional

If `true`, indicates that the item was returned but the seller refused to accept the return and if `false`, indicates the item was not attempted to return.

service_detailsobject<service_details>Optional

The service details.

service_details properties

5 properties

descriptionstringOptional

The service description.

Match^(.|\r?\n)*$Length1 <= length <= 2000

service_startedenumOptional

Indicates whether the service was started or cancelled.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"YES"
"NO"
"CANCELLED"

notestringOptional

The customer specified note about the service usage.

Match^(.|\r?\n)*$Length1 <= length <= 2000

sub_reasonsarray<definitions-sub_reasons>Optional

An array of sub-reasons for the service issue.

Items1 <= length <= 10

purchase_urlstringOptional

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

Formaturi

agreed_refund_detailsobject<agreed_refund_details>Optional

Details of Agreed Refund between customer and merchant.

agreed_refund_details properties

2 properties

merchant_agreed_refundbooleanOptional

Indicates whether merchant has agreed to refund the buyer or not.

merchant_agreed_refund_timestring<date_time>Optional

The date and time proposed by merchant to provide the refund, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

canceled_recurring_billingobject<canceled_recurring_billing>Optional

The recurring billing canceled details.

canceled_recurring_billing properties

2 properties

expected_refundobject<money>Optional

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

money properties

2 properties

currency_codestring<currency_code>Required

The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Formatppaas_common_currency_code_v2Length3 <= length <= 3

valuestringRequired

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](/api/rest/reference/currency-codes/).

Match^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$Length0 <= length <= 32

cancellation_detailsobject<cancellation_details>Optional

The cancellation details.

cancellation_details properties

4 properties

cancellation_datestring<date_time>Optional

The date and time of the cancellation, in [Internet date and time format](http://tools.ietf.org/html/rfc3339#section-5.6).

Match^[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})$Formatppaas_date_time_v3Length20 <= length <= 64

cancellation_numberstringOptional

The cancellation number.

Match^.*$Length1 <= length <= 127

cancelledbooleanOptional

Indicates whether the dispute was canceled.

cancellation_modeenumOptional

Indicates the mode used for order cancellation.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"CANCELLED_PAYPAL_BILLING_AGREEMENT"
"WEBSITE"
"PHONE"
"EMAIL"
"WRITTEN"
"IN_PERSON"

Back to top

On this page

No Headings