Connect PayPal

1Create a REST app — with only Transaction Search

picoask only reads your transaction history, so give it an app that can only do that.

• Sign in at developer.paypal.com with your business account and open Apps & Credentials (make sure the Live toggle is selected, not Sandbox).
• Click Create App and name it something you'll recognise — e.g. picoask-readonly — so it can be deleted on its own later.
• In the app's Features, enable Transaction Search and disable everything else. picoask never charges, refunds or moves money — an app without those features can't, no matter what.
• Copy the app's Client ID and Secret.

One thing to know: after enabling Transaction Search on a new app, PayPal can take a few hours before data starts flowing. If your first sync shows nothing, that's usually all it is.

2Copy your Merchant ID

• In your PayPal business account, open Account Settings → Business information.
• Copy the PayPal Merchant ID — 13 characters.

App credentials don't reveal which account they belong to, so picoask asks for the id explicitly — it's what keeps your data scoped to your account in the warehouse.

3Connect in picoask

In your project's Integrations tab, choose PayPal → Connect and fill in:

• PayPal Merchant ID — the 13-character id from step 2.
• Client ID and Client Secret — from step 1.
• Environment — leave as live. Type sandbox only if you're trialling with a developer-sandbox account (sandbox rows are flagged and never mix into revenue).

picoask verifies the credentials and the Transaction Search grant immediately, so a mistyped secret or a missing feature is reported at connect time with the exact fix — not later as missing data. The secret is stored encrypted and used only by the sync worker.

4What gets synced

• Payments — everything received (PayPal and card), with PayPal's own fee and the net on every transaction. Payments you sent are kept separate by sign, so collected revenue stays honest.
• Refunds, reversals and chargebacks — dated by when they happened and kept distinguishable from each other, with each refund tied back to its original payment where PayPal records the link.
• Bank transfers — withdrawals to your bank and money loaded in, kept apart from revenue entirely, so "what reached the bank" is answerable without inflating sales.
• Payers — so revenue and repeat behaviour can be broken down per buyer.

Amounts land in each transaction's own currency, exactly as PayPal reports them, and are never silently converted. The first import pulls up to three years of history (PayPal's own retention limit); after that picoask checks every few hours. PayPal publishes transaction data with a delay of up to ~3 hours, and picoask deliberately waits it out — so the freshest numbers trail reality by a few hours rather than silently missing settling transactions forever.

5Troubleshooting

• Credentials rejected — the Client ID/Secret pair was copied incompletely, or the app lives in the other environment (a Live app's credentials fail against Sandbox and vice versa — check the toggle in the Developer Dashboard matches the Environment field).
• "Enable the Transaction Search feature" — the app exists but Transaction Search isn't enabled on it. Enable it under the app's Features, and allow a few hours before data flows.
• Connected, but no data yet — Transaction Search was enabled recently; PayPal takes a few hours to start serving history for a new grant. Nothing is wrong — retry later.
• Merchant ID refused — the value must be the 13-character id from Account Settings → Business information, not the app's Client ID (that's ~80 characters and goes in the credential field).
• Numbers trail today by a few hours — that's PayPal's own publication delay, waited out on purpose so nothing settling is skipped.