Transaction Search API Integration Guide

APICurrent

Last updated: Aug 15th, 6:59am

Use the Transaction Search API to get the history of transactions from your PayPal account.

Note: To use this API on behalf of third parties, you must be a PayPal partner. Reach out to your partner manager for the next steps. To become a PayPal partner, enroll in the partner program.

Set up your development environment

Before you can integrate Transaction Search, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Transaction Search.

Enable transaction search:
1. Log into Dashboard and type your PayPal business account email and password.
2. On the My Apps & Credentials page, toggle to Live or Sandbox, then click the link for your REST app in the REST API apps section.
3. Select the Transaction Search option in the app settings section and click Save.

Note: If the REST App was used for other API requests prior to adding this new permission, it may take up to 9 hours to be enabled for a new access token; until then the Transaction Search API will return permission denied.

Endpoints

To list transactions:

1GET <endpoint>/v1/reporting/transactions

Where endpoint is either:

Endpoint	Environment	Description
`https://api-m.sandbox.paypal.com`	Sandbox	Test. Use your test credentials to generate an access token to make calls to the sandbox URIs.
`https://api-m.paypal.com`	Live	Production. Use your live credentials to generate an access token to make calls to the live URIs.

In the request, you must include the HTTP Accept, Accept-Language, Auhorization, and Content-Type request headers.

To limit the size of and filter the transactions that appear in the response, specify one or more optional pagination and query parameters.

The API combines all pagination and query parameters with an and operator. The more parameters that you specify, the narrower the result set in the response. For pagination and query parameter details, see list transactions.

To get the next page of results in multiple-page result sets, you must make the same request with an incremented page pagination parameter. Continue to increment the page parameter value until you get the full result set.

The maximum page size is 500. The maximum supported date range is 31 days. The maximum number of records in a single request is 10,000. If the account has more than 10,000 records for a specified date range, shorten the date range.

Notes:

The Transaction Search API accepts multiple query parameters and the page and page_size pagination parameters. For general information about query and pagination parameters, see query parameters.

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. However, a full three years of data will not be available until July 2018 because data has only been stored since July 2016.

List transactions

This sample request lists transactions for a specified transaction ID.

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.

1curl -v -X GET https://api-m.sandbox.paypal.com/v1/reporting/transactions?transaction_id=5TY05013RG002845M&fields=all&page_size=100&page=1 \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>"

Because the request includes the fields=all query parameters, the sample response shows all fields for the listed transaction:

1{
2  "transaction_details": [
3  {
4    "transaction_info":
5    {
6      "paypal_account_id": "6STWC2LSUYYYE",
7      "transaction_id": "5TY05013RG002845M",
8      "transaction_event_code": "T0006",
9      "transaction_initiation_date": "2014-07-11T04:03:52+0000",
10      "transaction_updated_date": "2014-07-11T04:03:52+0000",
11      "transaction_amount":
12      {
13        "currency_code": "USD",
14        "value": "465.00"
15      },
16      "fee_amount":
17      {
18        "currency_code": "USD",
19        "value": "-13.79"
20      },
21      "insurance_amount":
22      {
23        "currency_code": "USD",
24        "value": "15.00"
25      },
26      "shipping_amount":
27      {
28        "currency_code": "USD",
29        "value": "30.00"
30      },
31      "shipping_discount_amount":
32      {
33        "currency_code": "USD",
34        "value": "10.00"
35      },
36      "transaction_status": "S",
37      "transaction_subject": "Bill for your purchase",
38      "transaction_note": "Check out the latest sales",
39      "invoice_id": "Invoice-005",
40      "custom_field": "Thank you for your business",
41      "protection_eligibility": "01"
42    },
43    "payer_info":
44    {
45      "account_id": "6STWC2LSUYYYE",
46      "email_address": "consumer@example.com",
47      "address_status": "Y",
48      "payer_status": "Y",
49      "payer_name":
50      {
51        "given_name": "test",
52        "surname": "consumer",
53        "alternate_full_name": "test consumer"
54      },
55      "country_code": "US"
56    },
57    "shipping_info":
58    {
59      "name": "Sowmith",
60      "address":
61      {
62        "line1": "Eco Space, bellandur",
63        "line2": "OuterRingRoad",
64        "city": "Bangalore",
65        "country_code": "IN",
66        "postal_code": "560103"
67      }
68    },
69    "cart_info":
70    {
71      "item_details": [
72      {
73        "item_code": "ItemCode-1",
74        "item_name": "Item1 - radio",
75        "item_description": "Radio",
76        "item_quantity": "2",
77        "item_unit_price":
78        {
79          "currency_code": "USD",
80          "value": "50.00"
81        },
82        "item_amount":
83        {
84          "currency_code": "USD",
85          "value": "100.00"
86        },
87        "tax_amounts": [
88        {
89          "tax_amount":
90          {
91            "currency_code": "USD",
92            "value": "20.00"
93          }
94        }],
95        "total_item_amount":
96        {
97          "currency_code": "USD",
98          "value": "120.00"
99        },
100        "invoice_number": "Invoice-005"
101      },
102      {
103        "item_code": "ItemCode-2",
104        "item_name": "Item2 - Headset",
105        "item_description": "Headset",
106        "item_quantity": "3",
107        "item_unit_price":
108        {
109          "currency_code": "USD",
110          "value": "100.00"
111        },
112        "item_amount":
113        {
114          "currency_code": "USD",
115          "value": "300.00"
116        },
117        "tax_amounts": [
118        {
119          "tax_amount":
120          {
121            "currency_code": "USD",
122            "value": "60.00"
123          }
124        }],
125        "total_item_amount":
126        {
127          "currency_code": "USD",
128          "value": "360.00"
129        },
130        "invoice_number": "Invoice-005"
131      },
132      {
133        "item_name": "3",
134        "item_quantity": "1",
135        "item_unit_price":
136        {
137          "currency_code": "USD",
138          "value": "-50.00"
139        },
140        "item_amount":
141        {
142          "currency_code": "USD",
143          "value": "-50.00"
144        },
145        "total_item_amount":
146        {
147          "currency_code": "USD",
148          "value": "-50.00"
149        },
150        "invoice_number": "Invoice-005"
151      }]
152    },
153    "store_info":
154    {},
155    "auction_info":
156    {},
157    "incentive_info":
158    {}
159  }],
160  "account_number": "XZXSPECPDZHZU",
161  "last_refreshed_datetime": "2017-01-02T06:59:59+0000",
162  "page": 1,
163  "total_items": 1,
164  "total_pages": 1,
165  "links": [
166  {
167    "href": "https://api-m.sandbox.paypal.com/v1/reporting/transactions?transaction_id=5TY05013RG002845M&fields=all&page_size=100&page=1",
168    "rel": "self",
169    "method": "GET"
170  }]
171}

Check balances

To check the total, available, or withheld balances of a PayPal account, specify a date and time to filter your response. You can also filter your response by currency to get a balance for each holding currency.

Note:

It takes a maximum of three hours for balances to appear in the list balances call.

This call lists balances for up to the previous three years.

1curl -v -X GET https://api-m.sandbox.paypal.com/v1/reporting/balances?currency_code=USD&as_of_time=2016-10-15T06:07:00-0700 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 200 OK status code and a JSON response body that lists balances.

1{
2  "balance": {
3    "currency": "USD",
4    "primary": true,
5    "total_balance": {
6      "currency_code": "USD",
7      "value": "300.00"
8    },
9    "available_balance": {
10      "currency_code": "USD",
11      "value": "100.00"
12    },
13    "withheld_balance": {
14      "currency_code": "USD",
15      "value": "200.00"
16    }
17  },
18  "account_id": "QCXKLSS8GWT22",
19  "as_of_time": "2016-10-15T13:07:00Z",
20  "last_refresh_time": "2017-02-17T05:59:59Z"
21}

Additional information

Transaction Event Codes

Transaction Search API Reference