PayPal Payout Reconciliation Skill

What it catches

Proven on a labeled example

examples/northwind-october/ is a fictional coffee roaster's October in PayPal's own export format: 6 payouts, 18 lines, a bank statement and an orders export, with 12 planted situations (a missing deposit, a short deposit, a chargeback, a reserve hold, a double charge, an under-charged order, a paid order never charged, an unexplained deposit, a payout still in transit and a refund from September). expected.json labels the outcome a careful bookkeeper would reach; the tests assert the tool reaches exactly that in any row order, that every proposed entry balances, and that a fixed month exits 0.

What you get

Outputs in out/: payouts.csv (each payout, its status and bank line), exceptions.csv (review queue, highest priority first), journal.csv (proposed entries, balanced), report.md, summary.json. Exit 0 = every payout is accounted for; 1 = something blocks the reconciliation; 2 = an input problem (the message says which flag fixes it).

Quick start

./run_tests.sh
python3 -m paypalrec --payouts examples/northwind-october/paypal_activity.csv --bank examples/northwind-october/bank.csv \
  --orders examples/northwind-october/orders.csv --name "Northwind Coffee" --out out/

Inputs

• PayPal > Activity > Statements > Activity download, Balance affecting transactions, CSV. Pending and Memo rows are skipped; each General Withdrawal is treated as a payout to the bank.
• Any bank CSV with a date and either an amount column or debit/credit columns. Map unusual headers with --map-bank date="Posted" amount="Amt". Slash dates that could be US or EU are refused until you pass --date-format.
• Optional orders/invoices CSV with an order number and total (Shopify orders export, WooCommerce, an invoice list).

Use it from your agent

• Claude Code plugin: this folder is a plugin (.claude-plugin/plugin.json). Try it with claude --plugin-dir ./paypal-reconciliation-skill, or add the folder to your own plugin marketplace.
• Skill only: copy skills/paypal-rec/ into ~/.claude/skills/ (or your agent's skills folder) and keep this folder where the agent can run python3 -m paypalrec.
• No agent: the CLI works on its own; --help lists every flag.

Honest limits

• CSV exports only: no API connection, no login, no PDF statements.
• One currency per run (--currency); no FX conversion.
• Matching is exact on amount within a date window (default 5 days). A deposit that combines two payouts comes out as exceptions for a person to pair, not a forced match.
• PayPal is a balance, not a sweep: the entry is one period activity entry plus one transfer per withdrawal.
• possible_ codes are leads: check the order and the processor dashboard before refunding anyone.
• It proposes entries; it never posts them. It is not accounting or tax advice.

Requirements

Python 3.9+ (tested on 3.10 and 3.13), no dependencies. Not affiliated with PayPal.

Format and license

Zip, 22 KB, v1.0, 17 files. Use and modify it for yourself and for clients you serve; no resale or redistribution of the kit itself. Full terms in LICENSE.txt.

FAQ

Business or personal PayPal?

Any account that can download activity as CSV.

Multi-currency balances?

One currency per run.

Does it post entries?

Never.

How do I get the files?

Right after payment, Stripe’s confirmation page shows your download link.

Refunds?

Email hello@youraitools.co within 14 days if it doesn’t work and we can’t fix it.

Can I pay with crypto?

Yes. Pay the same price in USDC or USDT on Base, Ethereum, Arbitrum, Optimism, Polygon or Solana from the "Pay with crypto" button, with no account or KYC. We check the payment on-chain and show your download links as soon as it confirms.

Pairs well with

Related

• Stripe Payout Reconciliation Skill
• Shopify Payments Payout Reconciliation Skill
• All agent skills