How to connect PayPal for reconciliation

Give Ledfra a PayPal app of its own, with Transaction search enabled and nothing else. PayPal has no read-only credential type. An app's credentials can do whatever the app's features allow, so the way to hand Ledfra a credential that can only read is to build an app that can only read. This page walks through creating that app and using it for PayPal reconciliation: comparing what your ledger recorded with what PayPal reports.

Why an app of its own

The app your checkout runs on has features that move money, such as accepting payments, and possibly sending payouts or refunds. Its credentials carry all of them. Ledfra only ever reads, but a credential is safer when it cannot do what it is not used for, wherever it ends up.

A separate app also keeps the two independent. You can rotate or delete Ledfra's credentials without touching the app your customers pay through.

1. Create the app

1. Sign in to the PayPal Developer Dashboard and set the Sandbox / Live switch at the top. A Sandbox app reads PayPal's test accounts, and a Live app reads real money. Pick the one that matches what this ledger records, and remember which it was.
2. Open Apps & Credentials and choose Create App.
3. Name it after what it is for, such as Ledfra reconciliation, and create it as a merchant app.

2. Enable Transaction search, and nothing else

Open the new app and scroll to Features. Tick Transaction search, under Add-on services. Then untick every other feature, including any PayPal ticked for you when it created the app, such as Log in with PayPal or the mobile SDKs. Save.

Transaction search is the only feature Ledfra uses. It lets the app read the account's transactions and balances, which is everything reconciliation needs.

3. Connect it in Ledfra

1. Open the ledger and choose Payment processors in the sidebar, then select PayPal.
2. Choose the environment, Sandbox or Live, to match the switch you used in step 1. Ledfra never guesses it: a client id does not say which environment issued it, and trying both would send your secret to the one that did not.
3. Copy the client id and secret from the app's page in PayPal, paste them, and choose Connect PayPal.

Ledfra checks the credentials with PayPal before storing them, and asks PayPal which account they belong to rather than taking it on trust. Once connected, the PayPal card shows that account, the last four characters of the secret, and whether it is Sandbox or Live. The secret itself cannot be read back by anything.

4. Link the accounts that mirror PayPal's balances

PayPal reports two balances per currency. Available is money you can spend or pay out, and every account links it to an asset account in your ledger. The form starts with a new one, already named and keyed. Withheld is money PayPal is holding back, for a dispute or a reserve on the account.

Withheld is optional, because for most accounts it is always zero. Unlike Stripe's pending balance, it is not a stage every payment passes through, so leaving it out does not split ordinary payments across two places. Tick Also track funds PayPal withholds if your account carries a reserve or sees disputes, and Ledfra compares that money too. Left out, the card shows it as not tracked.

You then choose where reconciliation starts. The beginning compares the whole PayPal history, and Now takes what PayPal holds today as the opening balance, for an account with history this ledger does not record.

Starting from now posts PayPal's available balance in your ledger as an opening entry, against the same Opening balances equity account a Stripe connection uses, so the account holds what PayPal does from the first moment and payouts can draw on it. The Stripe guide explains the entry in full. An existing account that already carries postings can only start from the beginning, because the opening would count its money twice.

PayPal reports about two hours behind

PayPal publishes its transaction history in blocks, typically about two hours after the fact. Ledfra can only compare what PayPal has published, so its figures trail the PayPal dashboard by roughly that much.

If a payment from the last couple of hours appears in PayPal and not yet in the Reconciliation report, that is the delay, not missing money. Ledfra allows for it before it reports a PayPal reading as stale.

Limits

• Ledfra cannot see which features an app has. Unticking them in PayPal is what makes the credential read-only. If you are unsure whether an app can move money, check its Features page, not Ledfra.
• One PayPal account per ledger. Once accounts are linked, credentials for a different PayPal account are refused. A second account needs a ledger of its own.
• Starting from now needs nothing withheld. If PayPal is holding funds at the moment you link, Ledfra cannot split them into a reliable opening balance and refuses the link until they are released.
• Nothing converts between currencies. Each currency is linked and compared on its own.

Where to go next

1. How to connect Stripe - the same setup for a Stripe account.
2. Accounts - asset accounts, and why money in transit is not cash.
3. What is Ledfra? - where reconciliation fits in the whole model.