Skip to main content

Paypal

This page contains the setup guide and reference information for the Paypal source connector.

This connector uses PayPal APIs OAuth 2.0 access token to authenticate requests.

Prerequisites

You will need a Paypal account, which you can get following these steps

In the same page, you will also find how to setup a Sandbox so you can test the connector before using it in production.

Setup guide

Step 1: Get your Paypal secrets

After creating your account you will be able to get your Client ID and Secret. You can find them in your Apps & Credentials page.

Step 2: Set up the Paypal Transaction connector in Airbyte

  1. Log into your Airbyte account

  2. In the left navigation bar, click Sources.

    a. If this is your first time creating a source, use the search bar and enter Paypal Transaction and select it.

    b. If you already have sources configured, go to the top-right corner and click +new source. Then enter Paypal Transaction in the searech bar and select the connector.

  3. Set the name for your source

  4. Enter your Client ID

  5. Enter your Client secret

  6. Start Date: Use the provided datepicker or enter manually a UTC date and time in the format YYYY-MM-DDTHH:MM:SSZ.

  7. Switch ON/Off the Sandbox toggle. By defaukt the toggle is OFF, meaning it work only in a produciton environment.

  8. _(Optional) Dispute Start Date Range: Use the provided datepicker or enter manually a UTC date and time in the format YYYY-MM-DDTHH:MM:SS.sssZ.

    • If you don't add a date and you sync the lists_disputes stream, it will use the default value of 180 days in the past to retrieve data
    • It is mandatory to add the milliseconds is you enter a datetime.
    • This option only works for lists_disputes stream
  9. (Optional)Refresh Token: You can enter manually a refresh token. Right now the stream does this automatically.

  10. (Optional)Number of days per request: You can specify the days used by the connector when requesting data from the Paypal API. This helps in cases when you have a rate limit and you want to lower the window of retrieving data.

    • Paypal has a 10K record limit per request. This option is useful if your sync is every week and you have more than 10K per week
    • The default value is 7
    • This Max value you can enter is 31 days
  11. Click Set up source

info

By default, syncs are run with a slice period of 7 days. If you see errors with the message Result set size is greater than the maximum limit or an error code like RESULTSET_TOO_LARGE:

  • Try lower the the size of the slice period in your optional parameters in your connection configuration.
  • You can try to lower the scheduling sync window in case a day slice period is not enough. Lowering the sync period it may help avoid reaching the 10K limit.

Supported sync modes

The PayPal Transaction source connector supports the following sync modes:

FeatureSupported?
Full Refresh SyncYes
Incremental - Append SyncYes
NamespacesNo

Supported Streams

This Source is capable of syncing the following core Streams:

Transactions Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureTransactions
Start DateTimestamp with TZ (no ms)
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestMax 31 , 7(D)
Pagination StrategyPage Increment
Page size Max 500 (F)
Full Refresh
Incremental (D)

D: Default configured Value

F: Fixed Value. This means it is not configurable.


Balances Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureBalances
Start DateTimestamp with TZ (no ms)
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestNA
Pagination StrategyNA
Page size NA
Full Refresh
Incremental (D)

D: Default configured Value

F: Fixed Value. This means it is not configurable.


List Products Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureList Products
Start DateNA
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestNA
Pagination StrategyPage Increment
Page size Max 20 (F)
Full Refresh (D)
Incremental

D: Default configured Value

F: Fixed Value. This means it is not configurable.

caution

When configuring your stream take in consideration that the way the API works limits the speed on retreiving data. In some cases a +30K catalog retrieval could take between 10-15 minutes.


Show Products Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureShow Prod. Details
Start DateNA
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestNA
Pagination StrategyNA
Page size NA
Full Refresh (D)
Incremental

D: Default configured Value

F: Fixed Value. This means it is not configurable.

caution

When configuring this stream consider that the parent stream paginates with 20 number of items (Max alowed page size). The Paypal API calls are not concurrent, so the time it takes depends entirely on the server side. This stream could take a considerable time syncing, so you should consider running the sync of this and the parent stream (list_products) at the end of the day. Depending on the size of the catalog it could take several hours to sync.


List Disputes Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureList Disputes
Start DateNA
Dispute Start Date RangeTimestamp with TZ (w/ms)
Refresh tokenAuto
Number of days per requestMax 180 , 7(D)
Pagination StrategyPage Token
Page size Max 50 (F)
Full Refresh
Incremental (D)

D: Default configured Value

F: Fixed Value. This means it is not configurable.


Search Invoices Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features

Param/FeatureSearch Invoices
Start DateTimestamp with TZ (no ms)
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestND
Pagination StrategyPage Number
Page size Max 100 (F)
Full Refresh (D)
Incremental

D: Default configured Value

F: Fixed Value. This means it is not configurable.

ND: Not Defined in the source.

info

The start_end from the configuration, is passed to the body of the request and uses the creation_date_range.start and creation_date_range.end. More information in the Paypal Developer API documentation.


List Payments Stream

The below table contains the configuraiton parameters available for this connector and the default values and available features.

Param/FeatureList Payments
Start DateTimestamp with TZ (no ms)
Dispute Start Date RangeNA
Refresh tokenAuto
Number of days per requestNA , 7(D)
Pagination StrategyPage Cursor
Page size Max 20 (F)
Full Refresh
Incremental (D)

D: Default configured Value

F: Fixed Value. This means it is not configurable.


Performance Considerations

  • Data Availability: It takes a maximum of 3 hours for executed transactions to appear in the list transactions call.
  • Number of days per request: The maximum supported date range is 31 days.
  • Historical Data: You can't retrieve more than 3yrs of data for the transactions stream. For dispute_start_date you can only retrieve 180 days of data (see specifications per stream)
  • records_per_request: The maximum number of records in a single request are 10K (API Server restriction)
  • page_size: The maximum page size is 500. This has been configured by default.
  • requests_per_minute = The maximum limit is 50 requests per minute from IP address to all endpoint (API Server restriction).

Data type map

Integration TypeAirbyte Type
stringstring
numbernumber
arrayarray
objectobject

Reference

Config fields reference

Field
Type
Property name
string
client_id
string
client_secret
string
start_date
boolean
is_sandbox
string
dispute_start_date
string
end_date
string
refresh_token
integer
time_window

Changelog

VersionDatePull RequestSubject
2.5.12024-03-1536165Unpin CDK Version
2.5.02024-03-1536173Extended Disputes stream schema with missing properties
2.4.02024-02-2035465Per-error reporting and continue sync on stream failures
2.3.02024-02-1434510Silver certified. New Streams Added
2.2.22024-02-0935075Manage dependencies with Poetry.
2.2.12024-01-1134155prepare for airbyte-lib
2.2.02023-10-2531852The size of the time_window can be configured
2.1.22023-10-2331759Keep transaction_id as a string and fetch data in 7-day batches
2.1.12023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
2.1.02023-08-1429223Migrate Python CDK to Low Code schema
2.0.02023-07-0527916Update Balances schema
1.0.02023-07-0327968mark Client ID and Client Secret as required fields
0.1.132023-02-2022916Specified date formatting in specification
0.1.122023-02-1823211Fix error handler
0.1.112023-01-2722019Set AvailabilityStrategy for streams explicitly to None
0.1.102022-09-0417554Made the spec and source config to be consistent
0.1.92022-08-1815741Removed OAuth2.0 option
0.1.82022-07-2515000Added support of OAuth2.0 authentication, fixed bug when normalization couldn't handle nested cursor field and primary key
0.1.72022-07-1814804Added RESULTSET_TOO_LARGE error validation
0.1.62022-06-1013682Updated paypal transaction schema
0.1.52022-04-2712335Added fixtures to mock time.sleep for connectors that explicitly sleep
0.1.42021-12-229034Updated connector fields title/description
0.1.32021-12-168580Added more logs during check connection stage
0.1.22021-11-087499Removed base-python dependencies
0.1.12021-08-035155Fixed start_date_min limit
0.1.02021-06-104240PayPal Transaction Search API