Transaction Search API

Use the Transaction Search API to get the history of transactions for a PayPal account. To use the API on behalf of third parties, you must be part of the PayPal partner network. Reach out to your partner manager for the next steps. To enroll in the partner program, see Partner with PayPal. For more information about the API, see the Transaction Search API Integration Guide.

Note: To use the API on behalf of third parties, you must be part of the PayPal partner network. Reach out to your partner manager for the next steps. To enroll in the partner program, see Partner with PayPal.

Transactions (resource group)

Use the /transactions resource to list transactions.

List transactions

GET/v1/reporting/transactions

Lists transactions. Specify one or more query parameters to filter the transaction that appear in the response.

Notes:
If you specify one or more optional query parameters, the ending_balance response field is empty.
It takes a maximum of three hours for executed transactions to appear in the list transactions call.
This call lists transaction for the previous three years.

Query parameters

payment_instrument_type
string
Filters the transactions in the response by a payment instrument type. Value is either:
- CREDITCARD. Returns a direct credit card transaction with a corresponding value.
- DEBITCARD. Returns a debit card transaction with a corresponding value.
If you omit this parameter, the API does not apply this filter.
end_date
string
required
Filters the transactions in the response by an end date and time, in Internet date and time format. Seconds are required. Fractional seconds are optional. The maximum supported range is 31 days.
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})$.
start_date
string
required
Filters the transactions in the response by a start date and time, in Internet date and time format. Seconds are required. Fractional seconds are optional.
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})$.
balance_affecting_records_only
string
Indicates whether the response includes only balance-impacting transactions or all transactions. Value is either:
- Y. The default. The response includes only balance transactions.
- N. The response includes all transactions.
fields
string
Indicates which fields appear in the response. Value is a single field or a comma-separated list of fields. The transaction_info value returns only the transaction details in the response. To include all fields in the response, specify fields=all. Valid fields are:
- transaction_info. The transaction information. Includes the ID of the PayPal account of the payee, the PayPal-generated transaction ID, the PayPal-generated base ID, the PayPal reference ID type, the transaction event code, the date and time when the transaction was initiated and was last updated, the transaction amounts including the PayPal fee, any discounts, insurance, the transaction status, and other information about the transaction.
- payer_info. The payer information. Includes the PayPal customer account ID and the payer's email address, primary phone number, name, country code, address, and whether the payer is verified or unverified.
- shipping_info. The shipping information. Includes the recipient's name, the shipping method for this order, the shipping address for this order, and the secondary address associated with this order.
- auction_info. The auction information. Includes the name of the auction site, the auction site URL, the ID of the customer who makes the purchase in the auction, and the date and time when the auction closes.
- cart_info. The cart information. Includes an array of item details, whether the item amount or the shipping amount already includes tax, and the ID of the invoice for PayPal-generated invoices.
- incentive_info. An array of incentive detail objects. Each object includes the incentive, such as a special offer or coupon, the incentive amount, and the incentive program code that identifies a merchant loyalty or incentive program.
- store_info. The store information. Includes the ID of the merchant store and the terminal ID for the checkout stand in the merchant store.
page
integer
The zero-relative start index of the entire list of items that are returned in the response. So, the combination of page=1 and page_size=20 returns the first 20 items.
Minimum value: 1.
Maximum value: 2147483647.
page_size
integer
The number of items to return in the response. So, the combination of page=1 and page_size=20 returns the first 20 items. The combination of page=2 and page_size=20 returns the next 20 items.
Minimum value: 1.
Maximum value: 500.
store_id
string
Filters the transactions in the response by a store ID.
terminal_id
string
Filters the transactions in the response by a terminal ID.
transaction_amount
string
Filters the transactions in the response by a gross transaction amount range. Specify the range as <start-range> TO <end-range>, where <start-range> is the lower limit of the gross PayPal transaction amount and <end-range> is the upper limit of the gross transaction amount. Specify the amounts in lower denominations. For example, to search for transactions from $5.00 to $10.05, specify [500 TO 1005].
Note:The values must be URL encoded.
transaction_currency
string
Filters the transactions in the response by a three-character ISO-4217 currency code for the PayPal transaction currency.
transaction_id
string
Filters the transactions in the response by a PayPal transaction ID. A valid transaction ID is 17 characters long, except for an order ID, which is 19 characters long.
Note: A transaction ID is not unique in the reporting system. The response can list two transactions with the same ID. One transaction can be balance affecting while the other is non-balance affecting.
Minimum length: 17.
Maximum length: 19.

`transaction_status`

string

Filters the transactions in the response by a PayPal transaction status code. Value is:

Status code	Description
`D`	PayPal or merchant rules denied the transaction.
`P`	The transaction is pending. The transaction was created but waits for another payment process to complete, such as an ACH transaction, before the status changes to `S`.
`S`	The transaction successfully completed without a denial and after any pending statuses.
`V`	A successful transaction was reversed and funds were refunded to the original sender.

transaction_type
string
Filters the transactions in the response by a PayPal transaction event code. See Transaction event codes.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/reporting/transactions?start_date=2014-07-01T00:00:00-0700&end_date=2014-07-30T23:59:59-0700&transaction_id=5TY05013RG002845M&fields=all&page_size=100&page=1 \
-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 transactions .

account_number
string
The merchant account number.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[a-zA-Z0-9]*$.
end_date
string
The end date and time or the last date when the data can be served, in Internet date and time format.
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})$.
last_refreshed_datetime
string
The date and time when the data was last refreshed, in Internet date and time format.
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})$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
page
integer
A zero-relative index of transactions.
Maximum value: 2147483647.
start_date
string
The start date and time, in Internet date and time format.
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})$.
total_items
integer
The total number of transactions as an integer beginning with the specified page in the full result and not just in this response.
Maximum value: 2147483647.
total_pages
integer
The total number of pages, as an integer, when the total_items is divided into pages of the specified page_size.
Maximum value: 2147483647.
transaction_details
array (contains the transaction_detail object)
An array of transaction detail objects.

Sample Response

{
  "transaction_details": [
    {
      "transaction_info": {
        "paypal_account_id": "6STWC2LSUYYYE",
        "transaction_id": "5TY05013RG002845M",
        "transaction_event_code": "T0006",
        "transaction_initiation_date": "2014-07-11T04:03:52+0000",
        "transaction_updated_date": "2014-07-11T04:03:52+0000",
        "transaction_amount": {
          "currency_code": "USD",
          "value": "465.00"
        },
        "fee_amount": {
          "currency_code": "USD",
          "value": "-13.79"
        },
        "insurance_amount": {
          "currency_code": "USD",
          "value": "15.00"
        },
        "shipping_amount": {
          "currency_code": "USD",
          "value": "30.00"
        },
        "shipping_discount_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "transaction_status": "S",
        "transaction_subject": "Bill for your purchase",
        "transaction_note": "Check out the latest sales",
        "invoice_id": "Invoice-005",
        "custom_field": "Thank you for your business",
        "protection_eligibility": "01"
      },
      "payer_info": {
        "account_id": "6STWC2LSUYYYE",
        "email_address": "consumer@example.com",
        "address_status": "Y",
        "payer_status": "Y",
        "payer_name": {
          "given_name": "test",
          "surname": "consumer",
          "alternate_full_name": "test consumer"
        },
        "country_code": "US"
      },
      "shipping_info": {
        "name": "Sowmith",
        "address": {
          "line1": "Eco Space, bellandur",
          "line2": "OuterRingRoad",
          "city": "Bangalore",
          "country_code": "IN",
          "postal_code": "560103"
        }
      },
      "cart_info": {
        "item_details": [
          {
            "item_code": "ItemCode-1",
            "item_name": "Item1 - radio",
            "item_description": "Radio",
            "item_quantity": "2",
            "item_unit_price": {
              "currency_code": "USD",
              "value": "50.00"
            },
            "item_amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "tax_amounts": [
              {
                "tax_amount": {
                  "currency_code": "USD",
                  "value": "20.00"
                }
              }
            ],
            "total_item_amount": {
              "currency_code": "USD",
              "value": "120.00"
            },
            "invoice_number": "Invoice-005"
          },
          {
            "item_code": "ItemCode-2",
            "item_name": "Item2 - Headset",
            "item_description": "Headset",
            "item_quantity": "3",
            "item_unit_price": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "item_amount": {
              "currency_code": "USD",
              "value": "300.00"
            },
            "tax_amounts": [
              {
                "tax_amount": {
                  "currency_code": "USD",
                  "value": "60.00"
                }
              }
            ],
            "total_item_amount": {
              "currency_code": "USD",
              "value": "360.00"
            },
            "invoice_number": "Invoice-005"
          },
          {
            "item_name": "3",
            "item_quantity": "1",
            "item_unit_price": {
              "currency_code": "USD",
              "value": "-50.00"
            },
            "item_amount": {
              "currency_code": "USD",
              "value": "-50.00"
            },
            "total_item_amount": {
              "currency_code": "USD",
              "value": "-50.00"
            },
            "invoice_number": "Invoice-005"
          }
        ]
      },
      "store_info": {},
      "auction_info": {},
      "incentive_info": {}
    }
  ],
  "account_number": "XZXSPECPDZHZU",
  "last_refreshed_datetime": "2017-01-02T06:59:59+0000",
  "page": 1,
  "total_items": 1,
  "total_pages": 1,
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/reporting/transactions?start_date=2014-07-01T00:00:00-0700&end_date=2014-07-30T23:59:59-0700&transaction_id=5TY05013RG002845M&fields=all&page_size=100&page=1",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Balances (resource group)

Use the /balances resource to list balances.

List all balances

GET/v1/reporting/balances

List all balances. Specify date time to list balances for that time that appear in the response.

Notes:
It takes a maximum of three hours for balances to appear in the list balances call.
This call lists balances upto the previous three years.

Query parameters

as_of_time
string
List balances in the response at the date time provided, will return the last refreshed balance in the system when not provided.
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})$.
currency_code
string
Filters the transactions in the response by a three-character ISO-4217 currency code for the PayPal transaction currency.
Minimum length: 3.
Maximum length: 3.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/reporting/balances?currency_code=ALL&as_of_time=2021-02-22T00:00:00-0700&include_crypto_currencies=true \
-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 balances .

account_id
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.
Minimum length: 13.
Maximum length: 13.
Pattern: ^[2-9A-HJ-NP-Z]{13}$.
as_of_time
string
The requested date and time or the last date and time when the balances can be served, in Internet date and time format.
balances
array (contains the balance_detail object)
An array of balance detail objects.
last_refresh_time
string
The date and time when the balances was last refreshed, in Internet date and time format.

Sample Response

{
  "crypto_balances": [
    {
      "asset_symbol": "BTC",
      "quantity": "0.00512814"
    }
  ],
  "balances": [
    {
      "currency": "USD",
      "primary": true,
      "total_balance": {
        "currency_code": "USD",
        "value": "300.00"
      },
      "available_balance": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "withheld_balance": {
        "currency_code": "USD",
        "value": "200.00"
      }
    }
  ],
  "account_id": "DV77JV8VP82XE",
  "as_of_time": "2021-02-22T11:35:58Z",
  "last_refresh_time": "2021-03-03T16:23:30Z"
}

Common object definitions

account_id

account_id
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.
Minimum length: 13.
Maximum length: 13.
Pattern: ^[2-9A-HJ-NP-Z]{13}$.

address

city
string
required
The city name.
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.
line1
string
required
The first line of the address. For example, number or street.
line2
string
The second line of the address. For example, suite or apartment number.
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.
state
string
The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.

address_postal_code_validation

address_postal_code_validation

auction_info

auction_buyer_id
string
The ID of the buyer who makes the purchase in the auction. This ID might be different from the payer ID provided for the payment.
Minimum length: 1.
Maximum length: 500.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
auction_closing_date
string
The date and time when the auction closes, in Internet date and time format.
auction_item_site
string
The auction site URL.
Minimum length: 1.
Maximum length: 4000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
auction_site
string
The name of the auction site.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.

balance_detail

currency
string
required
Currency Code of the balances listed.
Minimum length: 3.
Maximum length: 3.
total_balance
object
required
The total amount in PayPal account. It is the sum of all the other balances.
available_balance
object
The amount of cash in an Account which is at the customer's disposal. This amount is captured at settlement cutoff time in the user's time zone as defined for the user.
primary
boolean
Optional field representing if the currency is primary currency or not.
withheld_balance
object
Balance withheld in the account. The portion of funds that PayPal holds for the customer that is not currently at the customer's disposal.

balances_response

account_id
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.
Minimum length: 13.
Maximum length: 13.
Pattern: ^[2-9A-HJ-NP-Z]{13}$.
as_of_time
string
The requested date and time or the last date and time when the balances can be served, in Internet date and time format.
balances
array (contains the balance_detail object)
An array of balance detail objects.
last_refresh_time
string
The date and time when the balances was last refreshed, in Internet date and time format.

cart_info

item_details
array (contains the item_detail object)
An array of item details.
paypal_invoice_id
string
The ID of the invoice. Appears for only PayPal-generated invoices.
Minimum length: 1.
Maximum length: 127.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
tax_inclusive
boolean
Indicates whether the item amount or the shipping amount already includes tax.

checkout_option

checkout_option_name
string
The checkout option name, such as color or texture.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
checkout_option_value
string
The checkout option value. For example, the checkout option color might be blue or red while the checkout option texture might be smooth or rippled.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.

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

cryptocurrency_quantity

cryptocurrency_quantity
string
Quantity of a cryptocurrency asset.
This is a decimal number with scale defined for each Cryptocurrency by the founders. For example,
Bitcoin(BTC) has 8 as scale,
Ethereum (ETH) has 18 as scale.

Minimum length: 1.

Maximum length: 40.

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

cryptocurrency_symbol

cryptocurrency_symbol
enum
The Cryptocurrency ticker symbol / code as assigned by liquidity providers (exchanges).
The possible values are:
- BTC. The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin
- ETH. The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum
- BCH. The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash
- LTC. The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin
Minimum length: 1.
Maximum length: 10.
Pattern: ^[0-9A-Za-z]{1,10}$.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

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

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

debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error

debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error_details

issue
string
required
The unique, fine-grained application-level error code.
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
location
string
The location of the field that caused the error. Value is body, path, or query.
value
string
The value of the field that caused the error.

error_details

issue
string
required
The unique, fine-grained application-level error code.
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
location
string
The location of the field that caused the error. Value is body, path, or query.
value
string
The value of the field that caused the error.

incentive_detail

incentive_amount
object
The incentive amount.
incentive_code
string
The code that identifies an incentive, such as a coupon.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
incentive_program_code
string
The incentive program code that identifies a merchant loyalty or incentive program.
Minimum length: 1.
Maximum length: 100.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
incentive_type
string
The type of incentive, such as a special offer or coupon.
Minimum length: 1.
Maximum length: 500.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.

incentive_info

incentive_details
array (contains the incentive_detail object)
An array of incentive details.

item_detail

adjustment_amount
object
An increment or decrement to a purchase amount.
basic_shipping_amount
object
The delivery cost.
checkout_options
array (contains the checkout_option object)
An array of checkout options. Each option has a name and value.
discount_amount
object
The reduction in price associated with goods or a service.
extra_shipping_amount
object
The cost for expedited delivery of the goods.
gift_wrap_amount
object
The amount of money charged for gift wrapping an item.
handling_amount
object
A charge for processing the purchase of goods or services.
insurance_amount
object
A charge for guaranteeing the quality of a product or delivery of a product.
invoice_number
string
The invoice number. An alphanumeric string that identifies a billing for a merchant.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_amount
object
The amount of the payment for the item.
item_code
string
An item code that identifies a merchant's goods or service.
Minimum length: 1.
Maximum length: 1000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_description
string
The item description.
Minimum length: 1.
Maximum length: 2000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_name
string
The item name.
Minimum length: 1.
Maximum length: 200.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_options
string
The item options. Describes option choices on the purchase of the item in some detail.
Minimum length: 1.
Maximum length: 4000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_quantity
string
The number of purchased units of goods or a service.
Minimum length: 1.
Maximum length: 4000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
item_unit_price
object
The cost for each instance of goods or a service.
tax_amounts
array (contains the item_detail_tax_amount object)
An array of tax amounts levied by a government on the purchase of goods or services.
tax_percentage
string
A rate, expressed in hundreds, that is used to calculate a levy for the purchase of goods or services.
Maximum length: 10.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.
total_item_amount
object
The sum of all factors, item cost, discounts, tax, shipping, and so on, that goes into the cost of an item.

item_detail_tax_amount

tax_amount
object
The tax levied by a government on the purchase of goods or services.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

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

money

currency_code
string
required
The three-character ISO-4217 currency code that identifies the currency.
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]+))$.

name

Hide deprecated

alternate_full_name
string
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
Maximum length: 300.
full_name
string
When the party is a person, the party's full name.
Maximum length: 300.
given_name
string
When the party is a person, the party's given, or first, name.
Maximum length: 140.
middle_name
string
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
Maximum length: 140.
prefix
string
The prefix, or title, to the party's name.
Maximum length: 140.
suffix
string
The suffix for the party's name.
Maximum length: 140.
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
Maximum length: 140.

name_validation

name_validation

payer_info

account_id
string
The PayPal` customer account ID.
Minimum length: 1.
Maximum length: 13.
Pattern: ^[a-zA-Z0-9]*$.
address
object
The payer address.
address_status
string
The address status of the payer. Value is either:
- Y. Verified.
- N. Not verified.
Minimum length: 1.
Maximum length: 1.
Pattern: ^[N|Y]$.
country_code
string
The two-character ISO 3166-1 code that identifies the country or region of the payer.
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)$.
email_address
string
The email address of the payer.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.
payer_name
object
The payer name.
payer_status
string
The status of the payer. Value is Y or N.
Minimum length: 1.
Maximum length: 1.
Pattern: ^[N|Y]$.
phone_number
object
The primary phone number of the payer.

percentage

percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

phone

country_code
string
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
Minimum length: 1.
Maximum length: 3.
Pattern: ^[0-9]{1,3}?$.
national_number
string
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
Minimum length: 1.
Maximum length: 14.
Pattern: ^[0-9]{1,14}?$.
extension_number
string
The extension number.
Minimum length: 1.
Maximum length: 15.
Pattern: ^[0-9]{1,15}?$.

search_error

debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

maximum_items
integer
The maximum number of transactions. Valid only for RESULTSET_TOO_LARGE.
total_items
integer
The total number of transactions. Valid only for RESULTSET_TOO_LARGE.

search_response

account_number
string
The merchant account number.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[a-zA-Z0-9]*$.
end_date
string
The end date and time or the last date when the data can be served, in Internet date and time format.
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})$.
last_refreshed_datetime
string
The date and time when the data was last refreshed, in Internet date and time format.
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})$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
page
integer
A zero-relative index of transactions.
Maximum value: 2147483647.
start_date
string
The start date and time, in Internet date and time format.
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})$.
total_items
integer
The total number of transactions as an integer beginning with the specified page in the full result and not just in this response.
Maximum value: 2147483647.
total_pages
integer
The total number of pages, as an integer, when the total_items is divided into pages of the specified page_size.
Maximum value: 2147483647.
transaction_details
array (contains the transaction_detail object)
An array of transaction detail objects.

shipping_info

address
object
The shipping address that is associated with this order.
method
string
The shipping method that is associated with this order.
Minimum length: 1.
Maximum length: 500.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
name
string
The recipient's name.
Minimum length: 1.
Maximum length: 500.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
secondary_shipping_address
object
The secondary shipping address that is associated with this order.

store_info

store_id
string
The ID of a store for a merchant in the system of record.
Minimum length: 1.
Maximum length: 100.
Pattern: ^[a-zA-Z0-9]*$.
terminal_id
string
The terminal ID for the checkout stand in a merchant store.
Minimum length: 1.
Maximum length: 60.
Pattern: ^[a-zA-Z0-9]*$.

transaction_detail

auction_info
object
The auction information.
cart_info
object
The cart information.
incentive_info
object
The incentive information.
payer_info
object
The payer information.
shipping_info
object
The shipping information.
store_info
object
The store information.
transaction_info
object
The transaction information.

transaction_info

annual_percentage_rate
string
The annual percentage rate (APR). Determines the amount of interest a consumer pays to finance a purchase at a merchant.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.
available_balance
object
The available amount of transaction currency during the completion of this transaction.
bank_reference_id
string
The bank reference ID. The bank provides this value for an ACH transaction.
Minimum length: 1.
Maximum length: 127.
Pattern: ^[a-zA-Z0-9]*$.
credit_promotional_fee
object
The overall amount of the credit promotional fee.
credit_term
string
The credit term. The time span covered by the installment payments as expressed in the term length plus the length time unit code.
Minimum length: 1.
Maximum length: 25.
Pattern: ^[a-zA-Z0-9.]*$.
credit_transactional_fee
object
The overall amount of the credit transaction fee.
custom_field
string
The merchant-provided custom text.
Note: Usually, this field includes the unique ID for payments made with MassPay type transaction.
Minimum length: 1.
Maximum length: 127.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
discount_amount
object
The reduction in price offered for goods or services purchased.
Note: This discount is for a price reduction that is offered for other than that at a individual item level.
ending_balance
object
The ending balance.
Note: If you specify one or more optional query parameters, the ending_balance response field is empty.
fee_amount
object
The PayPal fee amount. All transaction fees are included in this amount, which is the record of fee associated with the transaction.
Note: This field contains a value only when a transaction fee is applied and processed for this transaction.
instrument_sub_type
string
A finer-grained classification of the financial instrument that was used to fund a payment. For example, Visa card or a Mastercard for a credit card, BANKCARD ,DISCOVER etc. The pattern is not provided because the value is defined by an external party.
Minimum length: 1.
Maximum length: 64.
instrument_type
string
A high-level classification of the type of financial instrument that was used to fund a payment. The pattern is not provided because the value is defined by an external party. E.g. PAYPAL, CREDIT_CARD, DEBIT_CARD, APPLE_PAY, BANK , VENMO ,Pay Upon Invoice, Pay Later or Alternative Payment Methods (APM).
Minimum length: 1.
Maximum length: 64.
insurance_amount
object
An insurance charge. Guarantees the quality or delivery of a product.
invoice_id
string
The invoice ID that is sent by the merchant with the transaction.
Note: If an invoice ID was sent with the capture request, the value is reported. Otherwise, the invoice ID of the authorizing transaction is reported.
Minimum length: 1.
Maximum length: 127.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
other_amount
object
The special amount that is added to the transaction.
payment_method_type
string
The payment method that was used for a transaction. Value is PUI, installment, or mEFT.
Note: Appears only for pay upon invoice (PUI), installment, and mEFT transactions. Merchants and partners in the EMEA region can use this attribute to note transactions that attract turn-over tax.
Minimum length: 1.
Maximum length: 20.
Pattern: ^[a-zA-Z0-9-]*$.
payment_tracking_id
string
The payment tracking ID, which is a unique ID that partners specify to either get information about a payment or request a refund.
Minimum length: 1.
Maximum length: 127.
Pattern: ^[a-zA-Z0-9]*$.
paypal_account_id
string
The ID of the PayPal account of the counterparty.
Minimum length: 1.
Maximum length: 24.
Pattern: ^[a-zA-Z0-9]*$.
paypal_reference_id
string
The PayPal-generated base ID. PayPal exclusive. Cannot be altered. Defined as a related, pre-existing transaction or event.
Minimum length: 1.
Maximum length: 24.
Pattern: ^[a-zA-Z0-9]*$.
paypal_reference_id_type
enum
The PayPal reference ID type.
The possible values are:
- ODR. An order ID.
- TXN. A transaction ID.
- SUB. A subscription ID.
- PAP. A pre-approved payment ID.
Minimum length: 3.
Maximum length: 3.
Pattern: ^[a-zA-Z0-9]*$.
protection_eligibility
string
Indicates whether the transaction is eligible for protection. Value is:
- 01. Eligible.
- 02. Not eligible
- 03. Partially eligible.
Minimum length: 1.
Maximum length: 2.
Pattern: ^[a-zA-Z0-9]*$.
sales_tax_amount
object
The PayPal- or merchant-reported sales tax amount for the transaction.
shipping_amount
object
The PayPal- or merchant-reported shipping amount for the transaction.
shipping_discount_amount
object
The discount on the shipping amount.
shipping_tax_amount
object
The tax on the shipping service.
tip_amount
object
The tip.
transaction_amount
object
The all-inclusive gross transaction amount that was transferred between the sender and receiver through PayPal.
transaction_event_code
string
A five-digit transaction event code that classifies the transaction type based on money movement and debit or credit. For example, T0001. See Transaction event codes.
Minimum length: 1.
Maximum length: 5.
Pattern: ^[a-zA-Z0-9]*$.
transaction_id
string
The PayPal-generated transaction ID.
Read only.
Minimum length: 1.
Maximum length: 24.
Pattern: ^[a-zA-Z0-9]*$.
transaction_initiation_date
string
The date and time when work on a transaction began in the PayPal system, as expressed in the time zone of the account on this side of the payment. Specify the value in Internet date and time format.
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})$.
transaction_note
string
A special note that the payer passes to the payee. Might contain special customer requests, such as shipping instructions.
Minimum length: 1.
Maximum length: 4000.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.

`transaction_status`

string

A code that indicates the transaction status. Value is:

Status code	Description
`D`	PayPal or merchant rules denied the transaction.
`P`	The transaction is pending. The transaction was created but waits for another payment process to complete, such as an ACH transaction, before the status changes to `S`.
`S`	The transaction successfully completed without a denial and after any pending statuses.
`V`	A successful transaction was fully reversed and funds were refunded to the original sender.

Minimum length: 1.

Maximum length: 1.

Pattern: ^[a-zA-Z0-9]*$.

transaction_subject
string
The subject of payment. The payer passes this value to the payee. The payer controls this data through the interface through which he or she sends the data.
Minimum length: 1.
Maximum length: 256.
Pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$.
transaction_updated_date
string
The date and time when the transaction was last changed, as expressed in the time zone of the account on this side of the payment. Specify the value in Internet date and time format.
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})$.

payment_instrument_type

end_date

start_date

balance_affecting_records_only

fields

page

page_size

store_id

terminal_id

transaction_amount

transaction_currency

transaction_id

transaction_status

transaction_type

Sample Request

account_number

end_date

last_refreshed_datetime

links

page

start_date

total_items

total_pages

transaction_details

Sample Response

as_of_time

currency_code

Sample Request

account_id

as_of_time

balances

last_refresh_time

Sample Response

account_id

city

country_code

line1

line2

postal_code

state

address_postal_code_validation

auction_buyer_id

auction_closing_date

auction_item_site

auction_site

currency

total_balance

available_balance

primary

withheld_balance

account_id

as_of_time

balances

last_refresh_time

item_details

paypal_invoice_id

tax_inclusive

checkout_option_name

checkout_option_value

country_code

cryptocurrency_quantity

cryptocurrency_symbol

currency_code

currency_code

date_time

email_address

debug_id

message

name

details

information_link

links

debug_id

message

name

details

information_link

links

issue

description

`payment_instrument_type`

`end_date`

`start_date`

`balance_affecting_records_only`

`fields`

`page`

`page_size`

`store_id`

`terminal_id`

`transaction_amount`

`transaction_currency`

`transaction_id`

`transaction_status`

`transaction_type`

`account_number`

`end_date`

`last_refreshed_datetime`

`links`

`page`

`start_date`

`total_items`

`total_pages`

`transaction_details`

`as_of_time`

`currency_code`

`account_id`

`as_of_time`

`balances`

`last_refresh_time`

`account_id`

`city`

`country_code`

`line1`

`line2`

`postal_code`

`state`

`address_postal_code_validation`

`auction_buyer_id`

`auction_closing_date`

`auction_item_site`

`auction_site`

`currency`

`total_balance`

`available_balance`

`primary`

`withheld_balance`

`account_id`

`as_of_time`

`balances`

`last_refresh_time`

`item_details`

`paypal_invoice_id`

`tax_inclusive`

`checkout_option_name`

`checkout_option_value`

`country_code`

`cryptocurrency_quantity`

`cryptocurrency_symbol`

`currency_code`

`currency_code`

`date_time`

`email_address`

`debug_id`

`message`

`name`

`details`

`information_link`

`links`

`debug_id`

`message`

`name`

`details`

`information_link`

`links`

`issue`

`description`

`field`

`location`

`value`

`issue`