# @kody/paypal

`community-icon.svg` is PayPal's official PP monogram (Simple Icons path of
[PayPal's logo](https://www.paypal.com)) 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) |

1. Create the app at [developer.paypal.com/dashboard/applications](https://developer.paypal.com/dashboard/applications).
   Enable **Invoicing**, **Transaction Search**, and **Payouts** for the features
   you need. Never paste the secret into chat.
2. Save the client ID:

https://kody.codes/account/secrets/new?name=paypalClientId&description=PayPal%20REST%20API%20client%20ID%20for%20invoices%2C%20transactions%2C%20and%20payouts&allowedHosts=api-m.paypal.com,api-m.sandbox.paypal.com&scope=user

3. Save the client secret:

https://kody.codes/account/secrets/new?name=paypalClientSecret&description=PayPal%20REST%20API%20client%20secret%20for%20invoices%2C%20transactions%2C%20and%20payouts&allowedHosts=api-m.paypal.com,api-m.sandbox.paypal.com&scope=user

4. In the account secrets UI, approve hosts **`api-m.paypal.com`** and
   **`api-m.sandbox.paypal.com`** on both secrets. Saving a secret does not
   approve hosts by itself.
5. Agents: see [`AGENTS.md`](./AGENTS.md) for 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.

https://kody.codes/account/secrets/new?name=paypalClientId-work&description=PayPal%20REST%20API%20client%20ID%20for%20the%20work%20account&allowedHosts=api-m.paypal.com,api-m.sandbox.paypal.com&scope=user

https://kody.codes/account/secrets/new?name=paypalClientSecret-work&description=PayPal%20REST%20API%20client%20secret%20for%20the%20work%20account&allowedHosts=api-m.paypal.com,api-m.sandbox.paypal.com&scope=user

## Done when

- `paypalClientId` and `paypalClientSecret` are 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: true` never writes
- The `reimbursement-scan` job 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. |

## Docs

- [PayPal REST APIs](https://developer.paypal.com/api/rest/)
- [Invoicing](https://developer.paypal.com/docs/invoicing/)
- [Transaction Search](https://developer.paypal.com/docs/api/transaction-search/v1/)
- [Payouts](https://developer.paypal.com/docs/payouts/standard/integrate-api/)