bench get-app https://github.com/kramssov/paypal_bank_sync

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=kramssov%2Fpaypal_bank_sync)](https://frappegems.com/gems/apps/kramssov/paypal_bank_sync)

PayPal Bank Sync for ERPNext

Pulls PayPal transactions into ERPNext Bank Transaction records via the PayPal Reporting API, ready for the Bank Reconciliation Tool. Built for New Delta Europe B.V. (ERPNext v16).

How it works

• Daily scheduled job, plus Sync Now / Test Connection buttons in the settings.
• Fetches transactions per ≤31-day window (PayPal API limit), all pages.
• Each settled PayPal transaction becomes a Bank Transaction at gross value (so it matches the invoice amount), plus a separate -FEE transaction for the PayPal fee — mirroring how your PayPal balance moves.
• Idempotent: the PayPal transaction id is stored in the unique transaction_id field; re-syncing never duplicates.
• Refunds and payouts become withdrawals. Pending transactions are skipped unless "Include pending" is checked. Denied/voided are never imported.
• Multi-currency routing: a PayPal account can hold balances in several currencies at once. Add rows to "Currency → Bank Account" in the settings to route each currency to its own ERPNext Bank Account (e.g. USD → a dedicated PayPal USD account). Any currency without a specific mapping falls back to the Default Bank Account.
• Resilient by design: each transaction is inserted independently — one failure (e.g. an unrouted currency mismatch) is logged and skipped rather than aborting the whole sync. Automatic retry with backoff on PayPal rate limits (429) and transient server errors (5xx), honoring PayPal's Retry-After header when present.
• The result of every run (created / already-known / failed counts, plus a tip if currency routing would help) is shown immediately and also saved to "Last Sync Summary" on the settings page, so you can check the outcome anytime without digging through the Error Log.

Setup

1. PayPal credentials — at developer.paypal.com → Apps & Credentials → Create App, with the Transaction Search feature enabled at creation time (see note below). Copy Client ID + Secret. Both Sandbox and Live tabs work; sandbox uses fake money and is perfect for testing.

   Known PayPal quirk: enabling Transaction Search on an existing app does not reliably apply to new OAuth tokens, even after saving and logging back in. If Test Connection / Sync Now fails with NOT_AUTHORIZED, create a new app with the feature enabled from the start rather than editing an old one. The app must also be tied to a Business (not Personal) sandbox/live account.

2. In ERPNext open PayPal Sync Settings (Integrations workspace, or search "PayPal Sync Settings"):

   • Environment: Sandbox (testing) or Live
   • Client ID / Client Secret
   • Default Bank Account: e.g. PayPal - NDEB
   • Currency → Bank Account: optional, add a row per extra currency your PayPal balance holds
   • Sync From Date: where the first run should start
3. Click Test Connection to verify credentials without pulling data, then Sync Now to run a real sync. Check the created Bank Transactions and the Last Sync Summary field.
4. Tick Enabled for the daily automatic sync.

Note: PayPal indexes new transactions for the Reporting API with a delay of up to ~3 hours; the daily job plus the built-in 2-day overlap re-scan means nothing is ever missed.

Access control

Only System Manager and Accounts Manager roles can view or edit PayPal Sync Settings, and only they can trigger Test Connection / Sync Now.

Known limitations / possible future work

• One PayPal account (one set of API credentials) per site. If you need multiple separate PayPal business accounts, run separate credential sets by rotating them, or open an issue to discuss multi-account support.
• No webhook receiver yet — sync is poll-based (daily + manual), not real-time. The Reporting API's own indexing delay (~3h) means real-time webhooks would only shave a few hours off freshness; poll-based sync was chosen for simplicity and a smaller attack surface.

Tests

Pure-python unit tests (no frappe needed):

python3 -m unittest discover -s paypal_bank_sync/tests

20 tests covering: transaction mapping (sales, refunds, pending/denied filtering), multi-currency routing, date-window chunking, OAuth against the correct sandbox/live hosts, pagination, and retry/backoff behavior (429/5xx, Retry-After header, exhausted retries, non-retryable errors).

License

GPL-3.0-or-later — © 2026 New Delta Europe B.V. Derivative works must remain open source under the same license and preserve this copyright notice.