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.", "version": "1.9", "contact": {} }, "servers": [ { "url": "https://api-m.sandbox.paypal.com", "description": "PayPal Sandbox Environment" }, { "url": "https://api-m.paypal.com", "description": "PayPal Live Environment" } ], "tags": [ { "name": "transactions", "description": "Use the `/transactions` resource to list transactions." }, { "name": "partner-transactions", "description": "Use the `/partner-transactions` resource to list transactions." }, { "name": "balances", "description": "Use the `/balances` resource to list balances." } ], "externalDocs": { "url": "https://developer.paypal.com/docs/api/transaction-search/v1/" }, "paths": { "/v1/reporting/transactions": { "get": { "summary": "List transactions", "description": "Lists transactions. Specify one or more query parameters to filter the transaction that appear in the response.
Notes:", "operationId": "search.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists transactions .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_response" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/transaction_id" }, { "$ref": "#/components/parameters/transaction_type" }, { "$ref": "#/components/parameters/transaction_status" }, { "$ref": "#/components/parameters/transaction_amount" }, { "$ref": "#/components/parameters/transaction_currency" }, { "$ref": "#/components/parameters/start_date" }, { "$ref": "#/components/parameters/end_date" }, { "$ref": "#/components/parameters/payment_instrument_type" }, { "$ref": "#/components/parameters/store_id" }, { "$ref": "#/components/parameters/terminal_id" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/balance_affecting_records_only" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/reporting/search/read" ] } ], "tags": [ "transactions" ] } }, "/v1/reporting/balances": { "get": { "summary": "List all balances", "description": "List all balances. Specify date time to list balances for that time that appear in the response.
- If you specify one or more optional query parameters, the
ending_balanceresponse 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.
Notes:", "operationId": "balances.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists balances .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/balances_response" } } } }, "400": { "description": "The request is not well-formed, is syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/as_of_time" }, { "$ref": "#/components/parameters/currency_code" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/reporting/balances/read" ] } ], "tags": [ "balances" ] } } }, "components": { "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/v1/oauth2/token", "scopes": { "https://uri.paypal.com/services/reporting/search/read": "Transactions Search", "https://uri.paypal.com/services/reporting/balances/read": "List Balances" } } } } }, "responses": { "default": { "description": "The default response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_default" } } } } }, "schemas": { "account_id": { "type": "string", "description": "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.", "format": "ppaas_payer_id_v3", "minLength": 13, "maxLength": 13, "pattern": "^[2-9A-HJ-NP-Z]{13}$" }, "address": { "type": "object", "title": "Simple Postal Address (Coarse-Grained)", "description": "A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.", "properties": { "line1": { "type": "string", "description": "The first line of the address. For example, number or street." }, "line2": { "type": "string", "description": "The second line of the address. For example, suite or apartment number." }, "city": { "type": "string", "description": "The city name." }, "state": { "type": "string", "description": "The [code](/docs/api/reference/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/api/reference/state-codes/#argentina), [Brazil](/docs/api/reference/state-codes/#brazil), [Canada](/docs/api/reference/state-codes/#canada), [China](/docs/api/reference/state-codes/#china), [India](/docs/api/reference/state-codes/#india), [Italy](/docs/api/reference/state-codes/#italy), [Japan](/docs/api/reference/state-codes/#japan), [Mexico](/docs/api/reference/state-codes/#mexico), [Thailand](/docs/api/reference/state-codes/#thailand), or [United States](/docs/api/reference/state-codes/#usa). Maximum length is 40 single-byte characters." }, "country_code": { "$ref": "#/components/schemas/country_code" }, "postal_code": { "type": "string", "description": "The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code)." } }, "required": [ "line1", "city", "country_code" ] }, "auction_info": { "type": "object", "title": "Auction Information", "description": "The auction information.", "properties": { "auction_site": { "type": "string", "description": "The name of the auction site.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "auction_item_site": { "type": "string", "description": "The auction site URL.", "minLength": 1, "maxLength": 4000, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "auction_buyer_id": { "type": "string", "description": "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.", "minLength": 1, "maxLength": 500, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "auction_closing_date": { "description": "The date and time when the auction closes, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" } } }, "balance_detail": { "type": "object", "title": "Balance Information", "description": "The Balance information.", "properties": { "currency": { "description": "Currency Code of the balances listed.", "$ref": "#/components/schemas/currency_code" }, "primary": { "type": "boolean", "description": "Optional field representing if the currency is primary currency or not." }, "total_balance": { "description": "The total amount in PayPal account. It is the sum of all the other balances.", "$ref": "#/components/schemas/money" }, "available_balance": { "description": "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.", "$ref": "#/components/schemas/money" }, "withheld_balance": { "description": "Balance withheld in the account. The portion of funds that PayPal holds for the customer that is not currently at the customer's disposal.", "$ref": "#/components/schemas/money" } }, "required": [ "currency", "total_balance" ] }, "balance_detail_list": { "type": "array", "description": "An array of balance detail objects.", "maxItems": 200, "minItems": 0, "items": { "$ref": "#/components/schemas/balance_detail" } }, "balances_response": { "type": "object", "title": "Balances Response", "description": "The balances response information.", "properties": { "balances": { "$ref": "#/components/schemas/balance_detail_list" }, "account_id": { "$ref": "#/components/schemas/account_id" }, "as_of_time": { "description": "The requested date and time or the last date and time when the balances can be served, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" }, "last_refresh_time": { "description": "The date and time when the balances was last refreshed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" } } }, "cart_info": { "type": "object", "title": "Cart Information", "description": "The cart information.", "properties": { "item_details": { "$ref": "#/components/schemas/item_detail_list" }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether the item amount or the shipping amount already includes tax.", "default": false }, "paypal_invoice_id": { "type": "string", "description": "The ID of the invoice. Appears for only PayPal-generated invoices.", "minLength": 1, "maxLength": 127, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" } } }, "checkout_option": { "type": "object", "title": "Checkout Option", "description": "A checkout option as a name-and-value pair.", "properties": { "checkout_option_name": { "type": "string", "description": "The checkout option name, such as `color` or `texture`.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "checkout_option_value": { "type": "string", "description": "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`.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" } } }, "checkout_option_list": { "type": "array", "description": "An array of checkout options. Each option has a name and value.", "items": { "$ref": "#/components/schemas/checkout_option" }, "minItems": 1, "maxItems": 32767 }, "country_code": { "type": "string", "description": "The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region.
- 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.
Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.", "type": "string", "format": "ppaas_common_currency_code_v2", "minLength": 3, "maxLength": 3 }, "date_time": { "type": "string", "description": "The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.GBand notUKas 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.
Note: The regular expression provides guidance but does not reject all invalid dates.", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 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": { "type": "string", "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the", "format": "ppaas_common_email_address_v2", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" }, "error_400": { "type": "object", "title": "Bad Request Error", "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "properties": { "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_401": { "type": "object", "title": "Unauthorized Error", "description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "properties": { "name": { "type": "string", "enum": [ "AUTHENTICATION_FAILURE" ] }, "message": { "type": "string", "enum": [ "Authentication failed due to missing authorization header, or invalid authentication credentials." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_403": { "type": "object", "title": "Not Authorized Error", "description": "The client is not authorized to access this resource, although it may have valid credentials. ", "properties": { "name": { "type": "string", "enum": [ "NOT_AUTHORIZED" ] }, "message": { "type": "string", "enum": [ "Authorization failed due to insufficient permissions." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_404": { "type": "object", "title": "Not found Error", "description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "The specified resource does not exist." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_409": { "type": "object", "title": "Resource Conflict Error", "description": "The server has detected a conflict while processing this request.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_CONFLICT" ] }, "message": { "type": "string", "enum": [ "The server has detected a conflict while processing this request." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_415": { "type": "object", "title": "Unsupported Media Type Error", "description": "The server does not support the request payload's media type.", "properties": { "name": { "type": "string", "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] }, "message": { "type": "string", "enum": [ "The server does not support the request payload's media type." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_422": { "type": "object", "title": "Unprocessable Entity Error", "description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_429": { "type": "object", "title": "Too many requests", "description": "Too many requests. Blocked due to rate limiting.", "properties": { "name": { "type": "string", "enum": [ "RATE_LIMIT_REACHED" ] }, "message": { "type": "string", "enum": [ "Too many requests. Blocked due to rate limiting." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "error_default": { "description": "The default error response.", "oneOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/error_409" }, { "$ref": "#/components/schemas/error_415" }, { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/error_429" }, { "$ref": "#/components/schemas/error_500" }, { "$ref": "#/components/schemas/error_503" } ] }, "error_details": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "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." }, "value": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "$ref": "#/components/schemas/error_location" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "description": { "type": "string", "description": "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." } }, "required": [ "issue" ] }, "error_link_description": { "title": "Link Description", "description": "The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.", "type": "object", "required": [ "href", "rel" ], "properties": { "href": { "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.", "type": "string", "minLength": 0, "maxLength": 20000, "pattern": "^.*$" }, "rel": { "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^.*$" }, "method": { "description": "The HTTP method required to make the related call.", "type": "string", "minLength": 3, "maxLength": 6, "pattern": "^[A-Z]*$", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] } } }, "error_location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "enum": [ "body", "path", "query" ], "default": "body" }, "incentive_detail": { "type": "object", "title": "Incentive Details", "description": "The incentive details.", "properties": { "incentive_type": { "type": "string", "description": "The type of incentive, such as a special offer or coupon.", "minLength": 1, "maxLength": 500, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "incentive_code": { "type": "string", "description": "The code that identifies an incentive, such as a coupon.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "incentive_amount": { "$ref": "#/components/schemas/money", "description": "The incentive amount." }, "incentive_program_code": { "type": "string", "description": "The incentive program code that identifies a merchant loyalty or incentive program.", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" } } }, "incentive_detail_list": { "type": "array", "description": "An array of incentive details.", "items": { "$ref": "#/components/schemas/incentive_detail" }, "maxItems": 32767, "minItems": 1 }, "incentive_info": { "type": "object", "title": "Incentive Information", "description": "The incentive details.", "properties": { "incentive_details": { "$ref": "#/components/schemas/incentive_detail_list" } } }, "item_detail": { "type": "object", "title": "Item Details", "description": "The item details.", "properties": { "item_code": { "type": "string", "description": "An item code that identifies a merchant's goods or service.", "minLength": 1, "maxLength": 1000, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "item_name": { "type": "string", "description": "The item name.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "item_description": { "type": "string", "description": "The item description.", "minLength": 1, "maxLength": 2000, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "item_options": { "type": "string", "description": "The item options. Describes option choices on the purchase of the item in some detail.", "minLength": 1, "maxLength": 4000, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "item_quantity": { "type": "string", "description": "The number of purchased units of goods or a service.", "minLength": 1, "maxLength": 4000, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "item_unit_price": { "$ref": "#/components/schemas/money", "description": "The cost for each instance of goods or a service." }, "item_amount": { "$ref": "#/components/schemas/money", "description": "The amount of the payment for the item." }, "discount_amount": { "$ref": "#/components/schemas/money", "description": "The reduction in price associated with goods or a service." }, "adjustment_amount": { "$ref": "#/components/schemas/money", "description": "An increment or decrement to a purchase amount." }, "gift_wrap_amount": { "$ref": "#/components/schemas/money", "description": "The amount of money charged for gift wrapping an item." }, "tax_percentage": { "$ref": "#/components/schemas/percentage", "description": "A rate, expressed in hundreds, that is used to calculate a levy for the purchase of goods or services.", "maxLength": 10, "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" }, "tax_amounts": { "$ref": "#/components/schemas/item_detail_tax_amount_list" }, "basic_shipping_amount": { "$ref": "#/components/schemas/money", "description": "The delivery cost." }, "extra_shipping_amount": { "$ref": "#/components/schemas/money", "description": "The cost for expedited delivery of the goods." }, "handling_amount": { "$ref": "#/components/schemas/money", "description": "A charge for processing the purchase of goods or services." }, "insurance_amount": { "$ref": "#/components/schemas/money", "description": "A charge for guaranteeing the quality of a product or delivery of a product." }, "total_item_amount": { "$ref": "#/components/schemas/money", "description": "The sum of all factors, item cost, discounts, tax, shipping, and so on, that goes into the cost of an item." }, "invoice_number": { "type": "string", "description": "The invoice number. An alphanumeric string that identifies a billing for a merchant.", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "checkout_options": { "$ref": "#/components/schemas/checkout_option_list" } } }, "item_detail_list": { "type": "array", "description": "An array of item details.", "maxItems": 32767, "minItems": 1, "items": { "$ref": "#/components/schemas/item_detail" } }, "item_detail_tax_amount": { "type": "object", "title": "Tax Amount", "description": "The tax levied by a government on the purchase of goods or services.", "properties": { "tax_amount": { "$ref": "#/components/schemas/money", "description": "The tax levied by a government on the purchase of goods or services." } } }, "item_detail_tax_amount_list": { "type": "array", "description": "An array of tax amounts levied by a government on the purchase of goods or services.", "maxItems": 32767, "minItems": 1, "items": { "$ref": "#/components/schemas/item_detail_tax_amount" } }, "link_description": { "type": "object", "title": "Link Description", "description": "The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.", "required": [ "href", "rel" ], "properties": { "href": { "type": "string", "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) 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": { "type": "string", "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml)." }, "method": { "type": "string", "description": "The HTTP method required to make the related call.", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ] } } }, "link_description_list": { "type": "array", "description": "An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).", "readOnly": true, "items": { "$ref": "#/components/schemas/link_description" }, "maxItems": 32767, "minItems": 1 }, "money": { "type": "object", "title": "Money", "description": "The currency and amount for a financial transaction, such as a balance or payment due.", "properties": { "currency_code": { "$ref": "#/components/schemas/currency_code" }, "value": { "type": "string", "description": "The value, which might be:@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Y. Verified.N. Not verified.Note: The country code for Great Britain is", "$ref": "#/components/schemas/country_code" }, "address": { "description": "The payer address.", "$ref": "#/components/schemas/address" } } }, "percentage": { "type": "string", "description": "The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`.", "format": "ppaas_common_percentage_v2", "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" }, "phone": { "type": "object", "title": "Phone", "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).", "properties": { "country_code": { "type": "string", "description": "The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "national_number": { "type": "string", "description": "The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" }, "extension_number": { "type": "string", "description": "The extension number.", "minLength": 1, "maxLength": 15, "pattern": "^[0-9]{1,15}?$" } }, "required": [ "country_code", "national_number" ] }, "search_response": { "type": "object", "title": "Search Response", "description": "The search response information.", "properties": { "transaction_details": { "$ref": "#/components/schemas/transaction_detail_list" }, "account_number": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9]*$", "description": "The merchant account number." }, "start_date": { "description": "The start date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" }, "end_date": { "description": "The end date and time or the last date when the data can be served, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" }, "last_refreshed_datetime": { "description": "The date and time when the data was last refreshed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_time" }, "page": { "type": "integer", "description": "A zero-relative index of transactions.", "maximum": 2147483647, "minimum": 0 }, "total_items": { "type": "integer", "description": "The total number of transactions as an integer beginning with the specified `page` in the full result and not just in this response.", "maximum": 2147483647, "minimum": 0 }, "total_pages": { "type": "integer", "description": "The total number of pages, as an `integer`, when the `total_items` is divided into pages of the specified `page_size`.", "maximum": 2147483647, "minimum": 0 }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "shipping_info": { "type": "object", "title": "Shipping Information", "description": "The shipping information.", "properties": { "name": { "type": "string", "description": "The recipient's name.", "minLength": 1, "maxLength": 500, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "method": { "type": "string", "description": "The shipping method that is associated with this order.", "minLength": 1, "maxLength": 500, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "address": { "$ref": "#/components/schemas/address", "description": "The shipping address that is associated with this order." }, "secondary_shipping_address": { "$ref": "#/components/schemas/address", "description": "The secondary shipping address that is associated with this order." } } }, "store_info": { "type": "object", "title": "Store Information", "description": "The store information.", "properties": { "store_id": { "type": "string", "description": "The ID of a store for a merchant in the system of record.", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9]*$" }, "terminal_id": { "type": "string", "description": "The terminal ID for the checkout stand in a merchant store.", "minLength": 1, "maxLength": 60, "pattern": "^[a-zA-Z0-9]*$" } } }, "transaction_detail": { "type": "object", "title": "Transaction Details", "description": "The transaction details.", "properties": { "transaction_info": { "$ref": "#/components/schemas/transaction_info", "description": "The transaction information." }, "payer_info": { "$ref": "#/components/schemas/payer_info", "description": "The payer information." }, "shipping_info": { "$ref": "#/components/schemas/shipping_info", "description": "The shipping information." }, "cart_info": { "$ref": "#/components/schemas/cart_info", "description": "The cart information." }, "store_info": { "$ref": "#/components/schemas/store_info", "description": "The store information." }, "auction_info": { "$ref": "#/components/schemas/auction_info", "description": "The auction information." }, "incentive_info": { "$ref": "#/components/schemas/incentive_info", "description": "The incentive information." } } }, "transaction_detail_list": { "type": "array", "maxItems": 2147483647, "minItems": 1, "items": { "$ref": "#/components/schemas/transaction_detail" }, "description": "An array of transaction detail objects." }, "transaction_info": { "type": "object", "title": "Transaction Information", "description": "The transaction information.", "properties": { "paypal_account_id": { "type": "string", "description": "The ID of the PayPal account of the counterparty.", "minLength": 1, "maxLength": 24, "pattern": "^[a-zA-Z0-9]*$" }, "transaction_id": { "type": "string", "description": "The PayPal-generated transaction ID.", "readOnly": true, "minLength": 1, "maxLength": 24, "pattern": "^[a-zA-Z0-9]*$" }, "paypal_reference_id": { "type": "string", "description": "The PayPal-generated base ID. PayPal exclusive. Cannot be altered. Defined as a related, pre-existing transaction or event.", "minLength": 1, "maxLength": 24, "pattern": "^[a-zA-Z0-9]*$" }, "paypal_reference_id_type": { "type": "string", "description": "The PayPal reference ID type.", "minLength": 3, "maxLength": 3, "pattern": "^[a-zA-Z0-9]*$", "x-enumDescriptions": [ { "value": "ODR", "description": "An order ID." }, { "value": "TXN", "description": "A transaction ID." }, { "value": "SUB", "description": "A subscription ID." }, { "value": "PAP", "description": "A pre-approved payment ID." } ], "enum": [ "ODR", "TXN", "SUB", "PAP" ] }, "transaction_event_code": { "type": "string", "minLength": 1, "maxLength": 5, "pattern": "^[a-zA-Z0-9]*$", "description": "A five-digit transaction event code that classifies the transaction type based on money movement and debit or credit. For example,GBand notUKas 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.
T0001. See [Transaction event codes](/docs/integration/direct/transaction-search/transaction-event-codes/)."
},
"transaction_initiation_date": {
"description": "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](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_time"
},
"transaction_updated_date": {
"description": "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](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_time"
},
"transaction_amount": {
"$ref": "#/components/schemas/money",
"description": "The all-inclusive gross transaction amount that was transferred between the sender and receiver through PayPal."
},
"fee_amount": {
"$ref": "#/components/schemas/money",
"description": "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." }, "discount_amount": { "$ref": "#/components/schemas/money", "description": "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." }, "insurance_amount": { "$ref": "#/components/schemas/money", "description": "An insurance charge. Guarantees the quality or delivery of a product." }, "sales_tax_amount": { "$ref": "#/components/schemas/money", "description": "The PayPal- or merchant-reported sales tax amount for the transaction." }, "shipping_amount": { "$ref": "#/components/schemas/money", "description": "The PayPal- or merchant-reported shipping amount for the transaction." }, "shipping_discount_amount": { "$ref": "#/components/schemas/money", "description": "The discount on the shipping amount." }, "shipping_tax_amount": { "$ref": "#/components/schemas/money", "description": "The tax on the shipping service." }, "other_amount": { "$ref": "#/components/schemas/money", "description": "The special amount that is added to the transaction." }, "tip_amount": { "$ref": "#/components/schemas/money", "description": "The tip." }, "transaction_status": { "type": "string", "description": "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. |
Note: If you specify one or more optional query parameters, the ending_balance response field is empty."
},
"available_balance": {
"$ref": "#/components/schemas/money",
"description": "The available amount of transaction currency during the completion of this transaction."
},
"invoice_id": {
"type": "string",
"description": "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.", "minLength": 1, "maxLength": 127, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "custom_field": { "type": "string", "description": "The merchant-provided custom text.
Note: Usually, this field includes the unique ID for payments made with MassPay type transaction.", "minLength": 1, "maxLength": 127, "pattern": "^[a-zA-Z0-9_'\\-., \":;\\!?]*$" }, "protection_eligibility": { "type": "string", "description": "Indicates whether the transaction is eligible for protection. Value is:
01. Eligible.02. Not eligible03. Partially eligible.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." }, "instrument_type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "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)." }, "instrument_sub_type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "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." } } } }, "parameters": { "transaction_id": { "name": "transaction_id", "in": "query", "description": "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.", "schema": { "type": "string", "minLength": 17, "maxLength": 19 } }, "transaction_type": { "name": "transaction_type", "in": "query", "description": "Filters the transactions in the response by a PayPal transaction event code. See [Transaction event codes](/docs/integration/direct/transaction-search/transaction-event-codes/).", "schema": { "type": "string" } }, "transaction_status": { "name": "transaction_status", "in": "query", "description": "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. |
Note:The values must be URL encoded.", "schema": { "type": "string" } }, "transaction_currency": { "name": "transaction_currency", "in": "query", "description": "Filters the transactions in the response by a [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) for the PayPal transaction currency.", "schema": { "type": "string" } }, "start_date": { "name": "start_date", "in": "query", "description": "Filters the transactions in the response by a start date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required. Fractional seconds are optional.", "required": true, "schema": { "type": "string", "minLength": 20, "maxLength": 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})$" } }, "end_date": { "name": "end_date", "in": "query", "description": "Filters the transactions in the response by an end date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required. Fractional seconds are optional. The maximum supported range is 31 days.", "required": true, "schema": { "type": "string", "minLength": 20, "maxLength": 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": { "name": "payment_instrument_type", "in": "query", "description": "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.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.Y. The default. The response includes only balance transactions.N. The response includes all transactions.