@kody/paypal
Read PayPal invoices and transactions, and send invoices or payouts with dry-run mutations.
README.md
102 lines · 4.8 KB · Markdown@kody/paypal
community-icon.svg is PayPal's official PP monogram (Simple Icons path of
PayPal's logo) on PayPal Blue #003087. PayPal® is a
trademark of PayPal, Inc. This package is not affiliated with or endorsed by
PayPal.
Intent
Reusable PayPal helpers so Kody agents can look up invoices, search transaction
reporting, match reimbursements, send invoices, and create payouts on the
caller's PayPal REST app — not a shared platform merchant. Auth is a saved
client ID plus client secret (OAuth client-credentials). Reads are free-form;
send-invoice and payout mutations support dryRun: true and require
confirm: true.
This listing is meant to be forked. After you fork, save your own
paypalClientId / paypalClientSecret and call the helpers in your account.
No invoice templates, default recipients, or personal emails are baked in.
Share this package as https://kody.codes/@kody/paypal
What it does
- List, get, search, find, summarize, create (draft), and send invoices
- Search transaction reporting over a date range
- Match invoices to incoming transactions (reimbursements)
- Create or read Payouts batches
- Optional weekly reimbursement-scan job (disabled by default after fork)
Prerequisites / setup
REST client ID + client secret (secret-backed client-credentials). There is
no built-in PayPal platform OAuth app and no user login flow. Do not open
/connect/oauth for this package — PayPal Invoicing, Transaction Search, and
Payouts use an app token from POST /v1/oauth2/token.
| Secret | Purpose |
|---|---|
paypalClientId | REST app client ID (Basic username for the token request) |
paypalClientSecret | REST app client secret (Basic password for the token request) |
- Create the app at developer.paypal.com/dashboard/applications. Enable Invoicing, Transaction Search, and Payouts for the features you need. Never paste the secret into chat.
- Save the client ID:
- Save the client secret:
- In the account secrets UI, approve hosts
api-m.paypal.comandapi-m.sandbox.paypal.comon both secrets. Saving a secret does not approve hosts by itself. - Agents: see
AGENTS.mdfor import paths and smoke checks.
Defaults to the live API (api-m.paypal.com). Pass environment: "sandbox"
per call to use api-m.sandbox.paypal.com.
Additional accounts
Pass account: "work" to use paypalClientId-work / paypalClientSecret-work,
or pass clientIdSecret / clientSecretSecret explicitly.
Done when
paypalClientIdandpaypalClientSecretare saved; PayPal hosts and package secret access are approved- Smoke test returns
ok: true(live invoice sample when credentials exist — no sends or payouts) - Mutations refuse unless
confirm: true;dryRun: truenever writes - The
reimbursement-scanjob stays disabled unless you explicitly enable it after fork
Jobs
reimbursement-scan calls ./scheduled-reimbursement-scan weekly (Monday
09:00 UTC). It is enabled: false. Enabling it is an operator choice after
you fork and confirm the date window is right for your account. Do not disable
jobs that are already live on a fork without an explicit request.
Errors
| PayPal response | What to do |
|---|---|
| 401 | Save paypalClientId and paypalClientSecret at the URLs above and approve api-m.paypal.com (and sandbox if used). |
| 403 | Enable Invoicing, Transaction Search, or Payouts on the REST app. |
| 404 | Confirm the invoice / payout id and that you are on live vs sandbox. |
| range > 31 days | listTransactions is one PayPal window; use searchTransactions to chunk. |