Skip to content

Self-improving AI Employees for everyone

docs: document the Dodo Payments plugin

trohitg3a5533470168
diff --git a/CLAUDE.md b/CLAUDE.md
index 9aba10d7..c1e88562 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,6 +36,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[MCP Connectors](./docs-internal/mcp_connectors.md)** | Custom connectors: the owner adds an outside MCP server from Connectors → Add, or the MCP server card in the Custom category (`mcp`, kind `mcpAdd`, never connected; its page `panels/McpAddPanel.tsx` is the same form) (URL, name, sign-in: none, bearer, one header, or OAuth), and OpenCompany is its MCP *client* (`server/nodes/mcp/`, official `mcp` SDK; unrelated to the CLI agents' `/mcp/ide` server). The server reads the tools before keeping anything: streamable HTTP, then SSE; our own httpx client with redirects off; host and resolved addresses of every request (an OAuth sign-in's to its authorization server too) checked against `services/netpolicy.py` (shared with the Browser node: never cloud metadata or OpenCompany's own ports, plain http only on the owner's network), within `DISCOVER_S` (45 s, under the app's 60 s probe wait). Kept as `mcp:<slug>` (sign-in, encrypted; plain `model_params._mcp`: tools as accepted, per-tool `{enabled, ask}`, a waiting refresh) and `mcp:<slug>_proxy` (URL). A tool no model could call is kept with the reason, never renamed. Each connector is its own card through the generic `Credential.catalogue_entries` hook and the `_mcp_connector` template. Commands `mcp_connector_add` / `_sign_in` / `_test` / `_refresh` / `_review` / `_set_tool` / `_remove`; Refresh holds every change for Accept. Client: `AddConnectorForm.tsx` and `panels/McpConnectorPanel.tsx`. The `mcpConnector` node on an agent's Tools gives one tool per tool that is on (`ToolNode.tool_bindings`, named `<slug>__<tool>`, run with its binding's locked `mcp_tool` / `mcp_ask` / labels; arguments checked with jsonschema, a `$ref` followed only inside its schema: a tool whose inputs refer to another document is unusable, and a call goes as a plain `tools/call`, so the SDK never checks a result against an output schema the server sends; Ask first per tool through the node's `approval` spec); CLI agents leave it out and RLM refuses it. OAuth (`_oauth.py`) is the SDK's `OAuthClientProvider`: Add or Sign in again answers `sign_in_url`, the sign-in finishes in the background through `/api/mcp/oauth/callback`, tokens go to the OAuth token store under `mcp:<slug>` with their expiry (`store_oauth_tokens(..., expiry=)`), and each connection restores the expiry (read uncached with `get_stored_oauth_tokens`) and the endpoints before first use, so the SDK refreshes instead of opening a sign-in; a token issued without an expiry is renewed once the server refuses it (`_oauth.connect`); a refused refresh says Sign in again. Each connector is also an app a hire can use: `connector_apps`, registered with `services/employees/apps.register_app_source`, is read by `Connections.apps` with `employee_apps.json`'s apps (a saved one counts as connected), `mcpConnector` is on the hire allowlist, and the employee's card reads the connector from the node's `app_field` (`mcp_connector`). |
| **[WhatsApp Business Service](./docs-internal/whatsapp_business_service.md)** | Official Meta Cloud API plugin in [`server/nodes/whatsapp_business/`](./server/nodes/whatsapp_business/) — **distinct from `nodes/whatsapp/`**, which is a personal account over an unofficial Go bridge; they share no node type, credential or palette group. Four nodes: `whatsappBusinessSend` (10 ops — Meta models message type as a *field* on one `/messages` endpoint, so text / media / template / interactive are operations, not nodes), `whatsappBusinessMedia` (the one genuinely separate endpoint family), and the `Receive` / `Status` triggers (kept separate because a canary trigger registers exactly one CloudEvents type). `phone_number_id` is deliberately **absent from Params** and comes from the credential only, because it selects the sending identity — `server_controlled_fields` would keep a model-set value out on every tool path, but an ActionNode's tool schema is its whole `Params` (`ToolInput` is ToolNode-only), so a declared field would still appear in the schema the model sees. Webhook via `register_webhook_source` on the shared catch-all, `X-Hub-Signature-256` HMAC failing closed, composite `wamid:status` dedup ids so `sent→delivered→read` don't collapse. |
| **[Stripe Service](./docs-internal/stripe_service.md)** | Stripe CLI integration — `stripeAction` (CLI pass-through) + `stripeReceive` (signed-webhook trigger, on a canvas Run and deployed: every Stripe event travels under one CloudEvents type, `com.opencompany.stripe.event.received`, with the Stripe type in `subject` and `data.event_type`, where the node's own `build_filter` reads it; the source shapes the payload once, wakes the in-process waiter through `WebhookSource.handle` and reaches deployed listeners through `dispatch.emit`; deploying starts `stripe listen` through the generic `TriggerNode.prepare_deployment` hook, at Start and at the boot re-arm). Reference plugin for the Wave 12 event framework AND the **CLI-managed-auth pattern**: browser OAuth via `stripe login --non-interactive` + `--complete <url>` (URL extracted from `next_step` shell command via `shlex.split`) + auto-installed binary (`ensure_stripe_cli` from GitHub releases) + marker-token reuse of `auth_service.store_oauth_tokens` + CloudEvents-shaped `broadcast_credential_event("credential.oauth.connected" \| ".disconnected", provider=...)` — zero per-provider hardcoding in the frontend. Daemon stdout/stderr ingested via `ProcessService`'s `line_handler` callback (no log-file tailing); credential gate routed through `await self.has_credential()` so non-api-key auth (`is_logged_in()`) plugs in via subclass override. |
+| **[Dodo Payments Service](./docs-internal/dodo_payments_service.md)** | Dodo Payments integration over the official SDK (`dodopayments`, Stainless-generated, capped `<2`) — `dodoPaymentsAction` (list / get payments, subscriptions, customers, products; list refunds and disputes; `create_checkout_session` (returns `checkout_url`), `create_customer`, `create_customer_portal_link` (`send_email` off), `create_refund` (whole payment, one item, or part of it), `cancel_subscription` (`subscriptions.update`: the SDK has no cancel method), `change_subscription_plan`; `call` for any SDK method by its dotted name and `list_operations`; AI tool `dodo_payments_action`; `dodoPaymentsEndpoints` loader) + `dodoPaymentsReceive` (Standard Webhooks trigger at `/webhook/dodo-payments`). **A Dodo key works only in its own mode and carries no marker**: `DodoPaymentsCredential` (`ApiKeyCredential`, id `dodo_payments`) validates with `GET /brands` in test mode, then live mode, and its `validate` override saves the mode that accepted the key (`dodo_payments_mode`); every call goes to that mode's base URL from the SDK's `ENVIRONMENTS`, key and URL passed explicitly so no `DODO_PAYMENTS_*` variable authenticates or redirects a node. **Writes run with the SDK's retries off** (it retries POSTs and the API takes no idempotency key, so a retried refund could be paid twice); a write that times out or meets a 5xx says its outcome is unknown. **Nothing vendored**: `_sdk.endpoint_index()` reflects the installed SDK (`cached_property` resources, routes from the generated `self._get(path_template(...` source, parameters from signatures minus the SDK's per-call keywords, which `call` refuses since `extra_headers` could replace auth); the `webhooks` resource is left out (signing secrets have no use in an agent's hands); a test fails if any other method's route is missed. Lists are one page each (the SDK's auto-pagination asks for page 2 after page 0). Approval per operation: refunds, cancellations, plan changes and a `call` on a non-GET endpoint are held under Ask first (`ApprovalSpec` `operations` + a `when` on the endpoint's verb); reads and checkout links run. The trigger follows Stripe's fixed pattern (one CloudEvents type `com.opencompany.dodo_payments.event.received` with Dodo's type in `subject` / `data.event_type`, `event_type` and `build_filter` on the node, envelope id = `webhook-id` so a retried delivery is a duplicate, `emit` from the source's `handle`, both trigger sets in `constants.py`) but emits with `broadcast=False` (customer details, no client reads them); `StandardWebhooksVerifier` refuses timestamps outside the spec's five-minute window. SDK imported only inside `_sdk.py` (clean-interpreter test); tests run the real SDK under respx. Palette group `payments`; hire app with `side_effects: "money"`. |
| **[Vercel Service](./docs-internal/vercel_service.md)** | Vercel CLI integration — `vercelAction` (deploy / inspect / list + `custom` CLI passthrough; AI tool `vercel`). Second reference for the CLI-managed-auth pattern: the **device-flow variant** (`vercel login` is one blocking process — no two-step `--complete`; direct `create_subprocess_exec` + chunk-based banner read for the code-embedding URL, pumps drain pipes for the process lifetime, success gate = auth.json mtime advance + sniff). Dual auth: optional `vercel_token` field (injected as `VERCEL_TOKEN` env, never argv) OR CLI login with marker tokens. All invocations pin `--global-config <DATA_DIR>/vercel/` (the `CLAUDE_CONFIG_DIR` isolation idiom). `bun add` into the shared packages tree (pinned version, via `core/js_runtime.add_package`; the CLI runs on bun). First-deploy project guard raises `NodeUserError` instead of letting Vercel derive an invalid name from the workspace dir. Shipped with the generic OAuthConnect change: Login gates on **required** fields only, so optional fields never block CLI login. |
| **[GitHub Service](./docs-internal/github_service.md)** | GitHub CLI integration — `githubAction` (repo_clone / pr_create / pr_list / pr_merge / issue_create / issue_list + `custom` passthrough; AI tool `github`). **Strict Stripe pattern: the gh CLI owns its own auth** — no token stored/injected by OpenCompany, no auth pre-flight (gh's own error surfaces), marker OAuth row for the modal badge, fieldless catalogue entry. Login = spawned `gh auth login --hostname github.com --git-protocol https --web` — source-verified: headless takes the `isInteractive=false` branch (no Press-Enter), prints one-time code + `github.com/login/device` URL on stderr; the modal shows the code via the generic `verificationCode` plumbing (`useCredentialPanel` → `OAuthConnect`). `login_env()` strips `GH_TOKEN`/`GITHUB_TOKEN` (login aborts otherwise). Success gate = `gh auth status` exit 0, then best-effort **`gh auth setup-git`** (official bridge — the future git node needs zero auth code). gh binary: **project-local, pooch-driven** (temporal `_install.py` idiom) — pinned release under `package_dir("gh")`, system gh never consulted (auth state still shared: gh config paths are user-level). Palette group `vcs`. |
| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / `search_commands` (`cf cli search`) / zones_list / DNS records list-create-edit-delete / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, open beta — "the next version of Wrangler"). **Pin enforced, not just installed once**: `ensure_cf_cli` compares `core.js_runtime.installed_version("cf")` with the pin and re-runs `bun add` on a mismatch (clearing the login marker, since a new version may not see the old login). **Login = gh's device-flow shape**: `cf auth login --force --device --no-browser` prints a URL + one-time code on stderr that the handler relays to the modal (works from any machine; the old fixed-port-8877 loopback flow is `--no-device` only) — single flight (a repeat click returns the same code), install before any login (no invisible codes), never-kill-the-shim (killing bun's `cf.exe` launcher orphans the child), success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). **cf contract traps**: destructive commands without `--force` print "Aborted." and **exit 0** (delete always passes it; `custom` turns it into an error); no `--account-id` flag on most commands (account = `CLOUDFLARE_ACCOUNT_ID`, from the `account_id` param — several accounts fail non-interactively without it); cf resolves a domain `--zone` only in the first page of the selected account, so the node resolves domains itself via `zones list --name`; no output-format flag (unknown flags rejected); cf reads `.env` files from its working directory and fails under bun on a `cloudflare.config.ts` found above it, so typed ops run from a neutral `<DATA_DIR>/cloudflare` (`custom` from the workspace) with `CF_DELEGATION=1` (otherwise bun lets cf hand off to another cached cf copy) and telemetry off. The optional `apiKey` field (an API token) rides `CLOUDFLARE_API_TOKEN` and beats the login; cf does NOT accept a Global API Key, so a `cfk_` key (with `cloudflare_email`) serves only `graphql_query`, which POSTs the official `client/v4/graphql` endpoint directly (no cf GraphQL command; the cf login's token never leaves the CLI) — needs `Account > Account Analytics > Read`. System cf never consulted. Palette group `deployment`. |
@@ -541,7 +542,7 @@ class CacheEntry(SQLModel, table=True):
## Codebase Summary
- **Hybrid architecture**: Python (FastAPI + Pydantic plugins) + React/TypeScript frontend + a bun-hosted Express sidecar for JS/TS code execution (bun is the only JavaScript runtime and package manager anything shipped needs; Node is dev/CI-only).
-- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<plugin>/__init__.py`](./server/nodes/) (or a single `.py` inside a domain folder) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is `len(services.node_registry.NODE_METADATA)` after `import nodes`; never a file glob (`**/__init__.py` also matches group packages, and excluding `__init__.py` drops most plugins). Folders cover agent / model / android / google / microsoft / whatsapp / whatsapp_business / twitter / telegram / discord / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / context / vision / browser / speech / translate / stripe / vercel / github / cloudflare / gcloud / aws.
+- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<plugin>/__init__.py`](./server/nodes/) (or a single `.py` inside a domain folder) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is `len(services.node_registry.NODE_METADATA)` after `import nodes`; never a file glob (`**/__init__.py` also matches group packages, and excluding `__init__.py` drops most plugins). Folders cover agent / model / android / google / microsoft / whatsapp / whatsapp_business / twitter / telegram / discord / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / context / vision / browser / speech / translate / stripe / dodo_payments / vercel / github / cloudflare / gcloud / aws.
- **WebSocket-first frontend-backend communication.** Authoritative handler count is the size of the `MESSAGE_HANDLERS` dict in [`server/routers/websocket.py`](./server/routers/websocket.py) plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain the count in this doc — it drifts on every plugin add.
- **Plugin-first architecture (Wave 11).** One plugin = one authoring location (a folder rooted at `__init__.py`, or a single `.py` inside a domain folder). `services/handlers/` shrank from 12.8K → 1.1K LOC across 16 → 4 files. Live invariant total via `pytest --collect-only`.
@@ -671,7 +672,7 @@ The project uses WebSocket as the primary communication method between frontend
> The authoritative, per-node reference is the backend plugin registry plus the per-node "logic-flow" cards under [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) (one card per node, grouped by category, with handles / params / outputs / side-effects / edge-cases). Live node list = the plugin registry (one folder per node under `server/nodes/<group>/`; read the total from `len(services.node_registry.NODE_METADATA)` rather than hardcoding it here — a bare `__init__.py` glob overcounts by also matching the group packages). Do NOT maintain a per-node catalogue here — it drifts on every plugin add.
-Node groups (palette categories) are registered in [`server/nodes/groups.py`](./server/nodes/groups.py), 34 keys at time of writing: agent, ai, android, api, browser, chat, code, deployment, discord, document, email, filesystem, google, language, location, memory, microsoft, model, payments, proxy, scheduler, scraper, search, service, skill, social, text, tool, trigger, utility, vcs, whatsapp, whatsapp_business, workflow. Folder names are not palette keys: telegram and twitter nodes declare `social`, stripe declares `payments`, vercel / cloudflare / gcloud / aws declare `deployment`, github declares `vcs`, the `context` node declares `memory`, `vision` declares `tool`, and speech and translate declare `language` (provider-abstracted `textToSpeech` / `speechToText` and `translateText` / `transliterateText` / `detectLanguage`; `nodes/sarvam/` was retired into them, and only `sarvamChatModel` under `nodes/model/` remains vendor-named). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
+Node groups (palette categories) are registered in [`server/nodes/groups.py`](./server/nodes/groups.py), 34 keys at time of writing: agent, ai, android, api, browser, chat, code, deployment, discord, document, email, filesystem, google, language, location, memory, microsoft, model, payments, proxy, scheduler, scraper, search, service, skill, social, text, tool, trigger, utility, vcs, whatsapp, whatsapp_business, workflow. Folder names are not palette keys: telegram and twitter nodes declare `social`, stripe and dodo_payments declare `payments`, vercel / cloudflare / gcloud / aws declare `deployment`, github declares `vcs`, the `context` node declares `memory`, `vision` declares `tool`, and speech and translate declare `language` (provider-abstracted `textToSpeech` / `speechToText` and `translateText` / `transliterateText` / `detectLanguage`; `nodes/sarvam/` was retired into them, and only `sarvamChatModel` under `nodes/model/` remains vendor-named). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
## Backend Services
diff --git a/docs-internal/dodo_payments_service.md b/docs-internal/dodo_payments_service.md
new file mode 100644
index 00000000..750cceb5
--- /dev/null
+++ b/docs-internal/dodo_payments_service.md
@@ -0,0 +1,175 @@
+# Dodo Payments Service
+
+Self-contained plugin at [`server/nodes/dodo_payments/`](../server/nodes/dodo_payments/)
+over the official **Dodo Payments Python SDK** (`dodopayments`, a server
+dependency, generated by Stainless from Dodo's OpenAPI spec). Two nodes in the
+`payments` palette group, beside Stripe:
+
+- `dodoPaymentsAction` (workflow node + AI tool `dodo_payments_action`): typed
+ operations for the everyday flows (payments, subscriptions, customers,
+ products, refunds, disputes, checkout and customer-portal links), `call` for
+ any other SDK method, and `list_operations` to discover them.
+- `dodoPaymentsReceive`: a trigger that fires on each verified webhook
+ delivery to `/webhook/dodo-payments`, on a canvas Run and deployed.
+
+**Auth model: an API key in OpenCompany's encrypted store, plus the mode it
+belongs to.** A Dodo key works only in the mode it was created in
+(test.dodopayments.com or live.dodopayments.com) and carries no marker saying
+which. `DodoPaymentsCredential` (`ApiKeyCredential`, id `dodo_payments`) keeps
+three rows: the key under the provider id (the field the modal validates),
+`dodo_payments_mode`, and the optional `dodo_payments_webhook_key`
+(`extra_fields`). Validation asks `GET /brands` in test mode, then live mode
+(`_sdk.key_mode`; every business has a brand, and the route requires the key),
+and the credential's `validate` override saves the mode that accepted it. The
+owner never types the mode; a key stored without one makes the node answer
+with the `PermissionDeniedError` envelope asking to validate it again.
+
+**No ambient configuration.** Every client is created with the key and the
+mode's base URL (`dodopayments.ENVIRONMENTS`) passed explicitly, so
+`DODO_PAYMENTS_API_KEY` or `DODO_PAYMENTS_BASE_URL` in the server environment
+never authenticates a node or points it elsewhere.
+
+## File map
+
+| File | Role |
+|---|---|
+| `__init__.py` | Registers the webhook source, the canary trigger type, both output schemas and the `dodoPaymentsEndpoints` dropdown loader; both nodes auto-register on import |
+| `dodo_payments_action.py` | `DodoPaymentsActionNode(ActionNode)`, `usable_as_tool=True`, `tool_name="dodo_payments_action"`, both canvas handles kept visible, eighteen `@Operation`s, the `ApprovalSpec`; `_run` resolves the credential before any work |
+| `dodo_payments_receive.py` | `DodoPaymentsReceiveNode(WebhookTriggerNode)`: `event_type` set to the envelope type, `build_filter` on `data["event_type"]`, `_check_precondition`, `shape_output` returning `event.data` |
+| `_sdk.py` | Every SDK touch, imported lazily: `open_client`, `key_mode`, the endpoint index (`endpoint_index`, `resolve_endpoint`, `endpoint_writes`, `check_request`), `invoke`, `to_plain`, `raise_user_error`, the dropdown loader |
+| `_source.py` | `DodoPaymentsWebhookSource(WebhookSource)` (path `dodo-payments`, `StandardWebhooksVerifier`), `shape_dodo_payments_event`, the `get_webhook_source()` singleton |
+| `_events.py` | The one CloudEvents type, its factory and the `emit` wrapper |
+| `_credentials.py` | `DodoPaymentsCredential` (SDK-free): `_probe` finds the mode, `validate` saves it; `stored_mode` |
+| `icon.svg` / `dodo_payments.svg` / `meta.json` | Dodo's brandmark from its media kit (https://dodopayments.com/brand), node and credential icon; colour `#C6FE1E` |
+
+Config touched outside the folder: `config/credential_providers.json` (the
+`dodo_payments` card, `kind: "apiKey"`, fields `apiKey` and
+`dodo_payments_webhook_key`), `config/employee_apps.json` (the hire app,
+`side_effects: "money"`), `config/node_allowlist.json` (`dodoPaymentsAction`),
+`nodes/visuals.json` (skill binding), `constants.py` (`dodoPaymentsReceive` in
+`EVENT_TRIGGER_TYPES` and `WORKFLOW_TRIGGER_TYPES`), `pyproject.toml` /
+`uv.lock`. Paired skill:
+[`server/skills/payments_agent/dodo-payments-skill/SKILL.md`](../server/skills/payments_agent/dodo-payments-skill/SKILL.md).
+
+## Clients and retries
+
+`open_client` builds an `AsyncDodoPayments` per operation and closes it after.
+Calls that only read keep the SDK's default retries (`READ_RETRIES`, 2, on
+connection errors, 408, 409, 429 and 5xx). **Calls that write run with retries
+off**: the SDK retries POSTs as well, and Dodo's API takes no idempotency key,
+so a retried refund could be refunded twice. A write that times out or meets a
+5xx answers that its outcome is unknown and should be looked up before trying
+again. Every SDK error becomes a `NodeUserError`, which Temporal never retries,
+so an activity retry cannot repeat a write either. The per-request timeout is
+60 s (`CALL_TIMEOUT_SECONDS`); validation uses the credential's probe timeout
+and no retries.
+
+## Operations
+
+| Op | SDK call | Notes |
+|---|---|---|
+| `list_payments` | `payments.list` | `customer_id`, `subscription_id`, `product_id`, `payment_status` |
+| `get_payment` | `payments.retrieve(payment_id)` | |
+| `list_subscriptions` / `get_subscription` | `subscriptions.list` / `.retrieve` | `customer_id`, `product_id`, `subscription_status` |
+| `list_customers` / `get_customer` | `customers.list(email)` / `.retrieve` | |
+| `list_products` / `get_product` | `products.list` / `.retrieve(id)` | |
+| `list_refunds` | `refunds.list` | `customer_id`, `subscription_id`, `refund_status` |
+| `list_disputes` | `disputes.list` | `customer_id` |
+| `create_checkout_session` | `checkout_sessions.create` | One `product_cart` item; `customer` is `{customer_id}` or `{email, name}`; `discount_codes`; returns `checkout_url` (single use, 24 hours) |
+| `create_customer` | `customers.create(email, name)` | Both required by Dodo |
+| `create_customer_portal_link` | `customers.customer_portal.create` | `send_email=False`: the link comes back, Dodo emails no one |
+| `create_refund` | `refunds.create` | Whole payment; with `product_id` one item (`items=[{item_id}]`); with `amount` too, part of it |
+| `cancel_subscription` | `subscriptions.update` | `status="cancelled"`, or `cancel_at_next_billing_date=True` (the SDK has no cancel method) |
+| `change_subscription_plan` | `subscriptions.change_plan` | `product_id`, `quantity`, `proration_billing_mode` |
+| `call` | `<endpoint>(**request)` | Any indexed method; checked against its parameters before any credential or network use |
+| `list_operations` | the endpoint index | No credentials, no network |
+
+**Paging.** Lists answer with one page (`page` from 0, `page_size` up to 100)
+and report `count`, `page` and `page_size`. The SDK's own auto-pagination is
+not used: after page 0 it asks for page 2 (`next_page_info` assumes a 1-based
+start), and Dodo's envelope carries no total.
+
+**Dropdown values.** The status and proration dropdowns copy the SDK's
+`Literal`s; a test compares them with `dodopayments.types` so an SDK upgrade
+that adds a value fails loudly.
+
+## The endpoint index (`call` and `list_operations`)
+
+Nothing is vendored. `endpoint_index()` reflects a throwaway sync client once
+per process: each `functools.cached_property` that builds an API resource,
+recursively, and each public method's HTTP verb and path from its generated
+source (`self._get(path_template("/x/{id}", ...`, `_get_api_list`, `_post`,
+`_patch`, `_put`, `_delete`). Parameters come from the signature, minus the
+SDK's per-call keywords (`extra_headers`, `extra_query`, `extra_body`,
+`timeout`), which `call` refuses, since `extra_headers` could replace the
+Authorization header. Two kinds are left out: local helpers that make no
+request (`webhooks.unwrap`), and the whole `webhooks` resource, because
+webhook endpoints and their signing secrets configure this integration and a
+secret has no use in an agent's hands. A test fails if any other method's
+route is missed. Endpoints that answer with a file (invoice PDFs, payout CSVs)
+are refused with a clear message.
+
+## Approvals
+
+`ApprovalSpec(operations={"create_refund", "cancel_subscription",
+"change_subscription_plan", "call"})` with a `when` test: `call` waits only
+when its endpoint is not a GET (an unknown endpoint counts as writing).
+While the owner asks first, such a call is held as a draft card ("Make a
+change in Dodo Payments", details: operation, payment, subscription, product,
+amount, reason, endpoint) and runs after Send and the Undo window. Reads,
+checkout links, new customers and portal links run without asking: creating a
+link moves no money, and an approved call's result does not reach the
+employee, so holding a link would lose it. Unlike Stripe, nothing sets
+`refuse_while_asking`, so the owner gets a card instead of a refusal.
+
+## Webhooks
+
+Dodo signs every delivery per Standard Webhooks (`webhook-id`,
+`webhook-timestamp`, `webhook-signature`, HMAC-SHA256 under the endpoint's
+`whsec_` secret). `StandardWebhooksVerifier` checks the signature and refuses a
+timestamp more than five minutes from now (the spec's replay window); the base
+`WebhookSource` answers 503 with `Retry-After` when no secret resolves (the
+API key must be stored too, since the secret is read through the credential)
+and 400 on a bad signature or body. Dodo retries a refused delivery up to 8
+times over about a day.
+
+Every event travels under one CloudEvents type,
+`com.opencompany.dodo_payments.event.received`, with Dodo's type in `subject`
+and `data.event_type`: a deployed listener matches exactly one type. The
+envelope id is the `webhook-id`, which stays the same across Dodo's retries,
+so a deployed listener drops a retry as a duplicate; `workflow_id` stays unset,
+so every deployment carrying the trigger receives it. `handle` hands the event
+to the in-process waiter (canvas Run, Temporal-off deploy) and to
+`dispatch.emit` with `broadcast=False`: the payload carries customer details
+and no client reads it.
+
+Trigger output (`shape_dodo_payments_event`): `event_id`, `event_type`,
+`business_id`, `timestamp` (Dodo's ISO string), `payload_type` (`Payment`,
+`Subscription`, `Refund`, `Dispute`, ...) and `data`.
+
+## Tests
+
+[`server/tests/nodes/test_dodo_payments.py`](../server/tests/nodes/test_dodo_payments.py)
+runs the real SDK with respx at the HTTP transport, so requests are built
+exactly as the SDK builds them: registration and flat tool schema, dropdown
+values and modes against the SDK, mode detection and the saved mode,
+missing-credential envelopes, each typed operation's request, reads retried
+and writes not, Dodo's code and message in errors, `call` checks before any
+network use, the webhook exclusion, file answers refused, `list_operations`
+without credentials, the route pattern covering every SDK method, the approval
+rule and card, a clean-interpreter check that importing the plugin never loads
+the SDK, the catalogue / skill / app wiring, and for the trigger: signed,
+tampered, replayed and secret-less deliveries, the filter on both callers, a
+real canvas Run through the event waiter, and the deployed path. The verifier's
+window is covered in `tests/services/test_events.py`. `dodo_payments` is in
+`_MIGRATED_PLUGINS` of `tests/test_plugin_self_containment.py`, and the tool
+name is pinned in `tests/fixtures/tool_names_snapshot.json`.
+
+## Known limits
+
+- One Dodo business per install; a second key replaces the first.
+- Invoice PDFs and payout CSVs cannot be fetched through `call`.
+- No hire uses `dodoPaymentsReceive` as a trigger yet; `employee_apps.json`
+ keeps Dodo a tool-only app, as for Stripe.
+- `WebhookSource.receive()` queues each event on a push queue nothing drains
+ (shared with Stripe's source).
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index 75ac31ae..04dced0e 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -172,6 +172,11 @@ that a retired node remains registered.
- [Text Chunker (`textChunker`)](./document/textChunker.md)
- [Vector Store (`vectorStore`)](./document/vectorStore.md)
+### dodo_payments
+
+- [Dodo Payments (`dodoPaymentsAction`)](./dodo_payments/dodoPaymentsAction.md)
+- [Dodo Payments Receive (`dodoPaymentsReceive`)](./dodo_payments/dodoPaymentsReceive.md)
+
### email
- [Email Read (`emailRead`)](./email/emailRead.md)
diff --git a/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsAction.md b/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsAction.md
new file mode 100644
index 00000000..7d6d2fb3
--- /dev/null
+++ b/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsAction.md
@@ -0,0 +1,169 @@
+# Dodo Payments (`dodoPaymentsAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | payments / tool (dual-purpose) |
+| **Backend handler** | [`server/nodes/dodo_payments/dodo_payments_action.py`](../../../server/nodes/dodo_payments/dodo_payments_action.py) - `DodoPaymentsActionNode`; dispatched via `BaseNode.execute()` + the `@Operation("<op>")` methods; SDK glue in [`_sdk.py`](../../../server/nodes/dodo_payments/_sdk.py) |
+| **Tests** | [`server/tests/nodes/test_dodo_payments.py`](../../../server/tests/nodes/test_dodo_payments.py) |
+| **Skill (if any)** | [`server/skills/payments_agent/dodo-payments-skill/SKILL.md`](../../../server/skills/payments_agent/dodo-payments-skill/SKILL.md) |
+| **Dual-purpose tool** | yes - tool name `dodo_payments_action` (`usable_as_tool = True`; both canvas handles explicitly kept visible) |
+
+## Purpose
+
+Take payments and manage billing in Dodo Payments through its official Python
+SDK, authenticated by the API key saved in Credentials -> Dodo Payments.
+Typed operations cover the everyday flows (payments, subscriptions,
+customers, products, refunds, disputes, checkout and customer-portal links,
+refunds, cancellations, plan changes); `call` reaches any other SDK method by
+its dotted name, and `list_operations` discovers them from the installed SDK
+without credentials or network. Used both as a workflow node and as an
+AI-agent tool.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data; not consumed directly - all inputs come from `parameters` (or the LLM's tool args when used as a tool) |
+
+## Parameters
+
+(Pydantic `DodoPaymentsActionParams`, `extra="ignore"`; a
+`@model_validator(mode="before")` runs `coerce_blank_params(...,
+object_fields=("request",))` so the panel's `""` and LLM-stringified JSON both
+become a dict.)
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | options | `list_payments` | yes (dispatch reads the raw key) | - | `list_payments` / `get_payment` / `list_subscriptions` / `get_subscription` / `list_customers` / `get_customer` / `list_products` / `get_product` / `list_refunds` / `list_disputes` / `create_checkout_session` / `create_customer` / `create_customer_portal_link` / `create_refund` / `cancel_subscription` / `change_subscription_plan` / `call` / `list_operations` |
+| `payment_id` | string | `""` | yes for its ops | `get_payment`, `create_refund` | Payment id |
+| `subscription_id` | string | `""` | yes for its ops | `get_subscription`, `cancel_subscription`, `change_subscription_plan`, `list_payments`, `list_refunds` | Subscription id; a filter for the two lists |
+| `customer_id` | string | `""` | yes for `get_customer`, `create_customer_portal_link` | those, `create_checkout_session` and the payment / subscription / refund / dispute lists | Customer id; on a checkout, an existing customer |
+| `product_id` | string | `""` | yes for `get_product`, `create_checkout_session`, `change_subscription_plan` | those, `create_refund`, `list_payments`, `list_subscriptions` | Product id; on a refund, the item refunded |
+| `quantity` | int (`ge=1`) | `1` | no | `create_checkout_session`, `change_subscription_plan` | Units |
+| `customer_email` | string | `""` | yes for `create_customer` | `create_checkout_session`, `create_customer`, `list_customers` | New customer's email; a filter for `list_customers` |
+| `customer_name` | string | `""` | yes for `create_customer` | `create_checkout_session`, `create_customer` | Customer name |
+| `return_url` | string | `""` | no | `create_checkout_session`, `create_customer_portal_link` | Where the customer lands afterwards |
+| `discount_code` | string | `""` | no | `create_checkout_session` | Sent as `discount_codes: [code]` |
+| `amount` | int (`ge=1`) or empty | empty | no | `create_refund` | Part of the item to refund, smallest unit; needs `product_id` |
+| `reason` | string | `""` | no | `create_refund` | Refund reason |
+| `cancel_at_next_billing_date` | bool | `false` | no | `cancel_subscription` | Keep it until the paid period ends |
+| `proration_billing_mode` | options | `prorated_immediately` | no | `change_subscription_plan` | The SDK's five modes |
+| `payment_status` / `subscription_status` / `refund_status` | options | `all` | no | their list | The SDK's status values, kept in step by a test |
+| `page` | int (`ge=0`) | `0` | no | the six lists | Page number, from 0 |
+| `page_size` | int (`1..100`) | `20` | no | the six lists | Items per page |
+| `endpoint` | string (dynamic options: `dodoPaymentsEndpoints`) | `""` | yes for `call` | `call` | The SDK method's dotted name (`payouts.list`) |
+| `request` | object (JSON editor) | `{}` | no | `call` | The method's keyword arguments |
+| `search` | string | `""` | no | `list_operations` | Substring over endpoint names and routes |
+
+Field names `model`, `api_key`, `parameters`, `action`, `service_id` and
+`session_id` are deliberately avoided (name-based magic in `ParameterRenderer.tsx`).
+The mode is never a parameter: it comes from the credential.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `_shape(operation, **fields)` payload (see below); the same payload is returned to the LLM when wired to `input-tools` |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+```ts
+// DodoPaymentsActionOutput (extra="allow"); _shape drops only None, so [] / {} results stay
+{
+ operation: string;
+ mode?: "test_mode" | "live_mode"; // every operation that called Dodo
+ endpoint?: string; // call: the resolved SDK method
+ result: unknown; // Dodo's own JSON (fields as Dodo sent them); lists: the page's items;
+ // call on a list endpoint: the page, { items: [...] }
+ count?: number; // lists and list_operations: items returned
+ page?: number; // lists
+ page_size?: number; // lists
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[BaseNode.execute -> DodoPaymentsActionNode.&lt;operation&gt;] --> B{operation}
+
+ B -- list_operations --> L1[endpoint_index: reflect the installed SDK, no credentials, no network]
+ L1 --> L2[substring search] --> L3[_shape: result, count]
+
+ B -- call --> C1[resolve_endpoint: unknown -> difflib suggestions]
+ C1 -- unknown --> Eunk[NodeUserError with closest names, before any credential use]
+ C1 -- ok --> C2[check_request: unknown or missing keywords, extra_headers etc. refused]
+ C2 -- bad --> Ereq[NodeUserError with the accepted parameters]
+ C2 -- ok --> S
+
+ B -- typed ops --> V{required fields present?}
+ V -- no --> Ereq2[NodeUserError: field required]
+ V -- yes --> S[_run: DodoPaymentsCredential.resolve, then stored_mode]
+ S -- key missing / mode unknown --> Eperm[PermissionError provider=dodo_payments -> PermissionDeniedError envelope]
+ S -- ok --> X[open_client: key + ENVIRONMENTS mode passed explicitly<br/>retries: SDK default for reads, none for writes]
+ X --> I[invoke: getattr chain, await, to_plain via to_dict]
+ I -- APIStatusError --> Emap[NodeUserError: status, Dodo code and message, hint for 401 / 403 / 429]
+ I -- timeout / connection / 5xx on a write --> Eunknown[NodeUserError: outcome unknown, look it up before retrying]
+ I -- file answer --> Efile[NodeUserError: cannot return a file]
+ I -- ok --> O[_shape operation, mode, result, count, page, page_size]
+```
+
+## Decision Logic
+
+- **Validation**: dispatch requires the `operation` key; each typed op checks
+ its required ids before any credential or network use; `create_refund`
+ refuses `amount` without `product_id`.
+- **Mode**: the credential's saved `dodo_payments_mode` picks the base URL;
+ a key without one answers with the `PermissionDeniedError` envelope asking
+ to validate it again.
+- **Retries**: reads keep the SDK's default retries; writes (every op that
+ creates or changes something, and `call` on a non-GET endpoint) run with
+ none, because Dodo takes no idempotency key.
+- **Approval**: under Ask first, `create_refund`, `cancel_subscription`,
+ `change_subscription_plan` and a writing `call` are held as a draft card
+ (`ApprovalSpec`, `when` test on the endpoint); everything else runs.
+- **Paging**: one page per call; the SDK's auto-pagination is not used.
+- **Error paths**: missing credential or mode -> `PermissionDeniedError`
+ envelope; SDK `APIError` -> `NodeUserError`; anything else keeps its
+ traceback.
+
+## Side Effects
+
+- **Database writes**: none.
+- **Broadcasts**: per-node status via `BaseNode.execute`; the credential
+ path emits `credential.api_key.runtime_failed` when the key is missing.
+- **External API calls**: `https://test.dodopayments.com` or
+ `https://live.dodopayments.com` (from the SDK's `ENVIRONMENTS`, by the
+ key's mode), bearer-authenticated; `list_operations` makes none.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `DodoPaymentsCredential` (`ApiKeyCredential`, id
+ `dodo_payments`): the key under the provider id, plus `dodo_payments_mode`
+ (written by validation) and `dodo_payments_webhook_key` (`extra_fields`),
+ resolved via `DodoPaymentsCredential.resolve(user_id=ctx.credential_customer_id)`.
+ Modal probe: `GET /brands` in test mode, then live mode.
+- **Services**: option-loader registry (`dodoPaymentsEndpoints`), the
+ approvals subsystem (`services/approvals/`).
+- **Python packages**: `dodopayments` (with `httpx`, `pydantic`), imported
+ lazily inside `_sdk.py` only.
+- **Environment variables**: none. `DODO_PAYMENTS_*` variables never
+ authenticate or redirect a node: key and base URL are passed explicitly.
+
+## Edge cases & known limits
+
+- **Webhook endpoints are not reachable** through `call`: the `webhooks`
+ resource is left out of the index (secrets have no use in an agent's hands).
+- **File answers** (invoice PDFs, payout CSVs) are refused.
+- **A held link would be lost**: creating a checkout or portal link is not
+ gated, because an approved call's result does not reach the employee.
+- **One business per install**: a second key replaces the first.
+
+## Related
+
+- **Skills using this as a tool**: [`dodo-payments-skill/SKILL.md`](../../../server/skills/payments_agent/dodo-payments-skill/SKILL.md)
+- **Sibling**: [`dodoPaymentsReceive`](./dodoPaymentsReceive.md); companion payments node [`stripeAction`](../stripe/stripeAction.md)
+- **Architecture docs**: [Dodo Payments Service](../../dodo_payments_service.md), [Plugin System](../../plugin_system.md), [Chat Protocol (Approvals)](../../chat_protocol.md)
diff --git a/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsReceive.md b/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsReceive.md
new file mode 100644
index 00000000..bb034595
--- /dev/null
+++ b/docs-internal/node-logic-flows/dodo_payments/dodoPaymentsReceive.md
@@ -0,0 +1,140 @@
+# Dodo Payments Receive (`dodoPaymentsReceive`)
+
+| Field | Value |
+|------|-------|
+| **Category** | payments / trigger (class `group = ("payments", "trigger")`) |
+| **Backend handler** | [`server/nodes/dodo_payments/dodo_payments_receive.py`](../../../server/nodes/dodo_payments/dodo_payments_receive.py) (`DodoPaymentsReceiveNode`, on `WebhookTriggerNode`); webhook plumbing in [`_source.py`](../../../server/nodes/dodo_payments/_source.py) (`DodoPaymentsWebhookSource`, `shape_dodo_payments_event`); the CloudEvents factory and deployed-path emit in [`_events.py`](../../../server/nodes/dodo_payments/_events.py); framework base [`services/events/triggers.py`](../../../server/services/events/triggers.py), [`services/events/webhook.py`](../../../server/services/events/webhook.py), verifier [`services/events/verifiers/standard_webhooks.py`](../../../server/services/events/verifiers/standard_webhooks.py) |
+| **Tests** | [`server/tests/nodes/test_dodo_payments.py`](../../../server/tests/nodes/test_dodo_payments.py) |
+| **Skill (if any)** | none as a tool (the [dodo-payments-skill](../../../server/skills/payments_agent/dodo-payments-skill/SKILL.md) describes it in prose) |
+| **Dual-purpose tool** | no (trigger) |
+
+## Purpose
+
+Fire a workflow when Dodo Payments delivers a webhook event (a payment,
+refund, dispute, subscription, payout, license key, credit or dunning event),
+on a canvas Run and in a deployed workflow. A webhook endpoint added in the
+Dodo dashboard posts to `POST /webhook/dodo-payments`; the source verifies the
+Standard Webhooks signature against the endpoint's `whsec_` secret saved in
+Credentials -> Dodo Payments, flattens the delivery into the trigger's output
+(`shape_dodo_payments_event`), and wraps it in one `WorkflowEvent` type,
+`com.opencompany.dodo_payments.event.received`, with Dodo's type in `subject`
+and `data.event_type`. It hands that envelope to the in-process event waiter
+(a canvas Run, or a deploy that runs without Temporal) and to
+`services.events.dispatch.emit` (deployed listeners on Temporal). The node
+contributes the event-type filter, the precondition and the output unwrap.
+
+## Inputs (handles)
+
+None - this is a trigger; it is the head of a run.
+
+## Parameters
+
+`DodoPaymentsReceiveParams(BaseTriggerParams)`, `extra="ignore"`.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `event_type_filter` | string | `all` | no | - | `all`, an exact Dodo type (`payment.succeeded`), or a `prefix.*` glob (`subscription.*`). Matched against `data.event_type` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `DodoPaymentsReceiveOutput`: the shaped delivery, identical on a canvas Run and in a deployed run |
+
+### Output payload (TypeScript shape)
+
+`extra="allow"`. All fields are `Optional` on the model.
+
+```ts
+{
+ event_id: string; // the delivery's webhook-id (the same across Dodo's retries)
+ event_type: string; // Dodo's type, e.g. "payment.succeeded" ("unknown" when missing)
+ business_id: string | null;
+ timestamp: string | null; // Dodo's ISO 8601 event time
+ payload_type: string | null; // Payment, Subscription, Refund, Dispute, LicenseKey, ...
+ data: object; // the payment / subscription / refund / ... itself, {} when missing
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ D[Dodo webhook endpoint] -- POST --> W["webhook/dodo-payments route"]
+ W --> V{DodoPaymentsCredential.resolve -> dodo_payments_webhook_key}
+ V -- key or secret missing --> R503[503 + Retry-After 5]
+ V -- ok --> H[StandardWebhooksVerifier: headers, timestamp within 5 min, v1 HMAC-SHA256 base64 over id.ts.body]
+ H -- missing / stale / mismatch --> R400[400]
+ H -- ok --> J[json.loads body] -- invalid --> R400
+ J --> S[shape_dodo_payments_event -> envelope: id=webhook-id, type=com.opencompany.dodo_payments.event.received, subject=Dodo type]
+ S --> D1[event_waiter.dispatch envelope]
+ S --> D2[dispatch.emit broadcast=False]
+ D1 --> RUN[canvas Run waiter keyed on the same type: build_filter on data -> resolve -> shape_output unwraps data]
+ D2 --> DEP[deployed listener, EventType = that type: evaluate_trigger_filter_activity runs build_filter on data -> run starts with data as the trigger output]
+ subgraph canvas Run
+ P[_check_precondition: key and webhook secret saved?] --> RUN
+ end
+```
+
+## Decision Logic
+
+- **One CloudEvents type**: a deployed trigger listens for exactly one type
+ (`register_canary_trigger_type`), so every Dodo event shares it and the
+ node sets `event_type` to the same constant, which keys the canvas-Run
+ waiter.
+- **Two delivery paths**: `WebhookSource.handle` feeds the in-process waiter;
+ the source's `handle` override then calls `emit`, the only path to deployed
+ listeners on Temporal. The envelope carries no `workflow_id`, so every
+ deployment with the trigger receives it.
+- **Filter** (`build_filter`): both callers pass the envelope's `data` (an
+ envelope is accepted too); `event_type_filter` is matched against
+ `data.event_type` with `event_type_matches`; a non-dict payload is rejected.
+- **Output**: shaped once, in the source, so a canvas Run and a deployed run
+ see the same fields.
+- **Precondition** (canvas Run): without the API key, or without the webhook
+ secret, the run ends at once with what to save, instead of waiting on
+ deliveries that would all get a 503.
+- **Verification fails closed**: no secret -> 503 with `Retry-After: 5`;
+ missing headers, a timestamp more than five minutes off, or no matching
+ `v1,` signature -> 400. Several space-separated signatures are accepted
+ (secret rotation).
+
+## Side Effects
+
+- **Event dispatch**: `event_waiter.dispatch` and `dispatch.emit` with
+ `broadcast=False` (payment events carry customer details, and no client
+ reads them) for every verified delivery.
+- **Broadcasts**: none of its own on a canvas Run; a deployed trigger shows
+ `waiting` from the deployment manager.
+- **HTTP**: `POST /webhook/dodo-payments` answered by the router after
+ `handle()`; the source's `receive()` also enqueues the event on its
+ internal push queue (nothing consumes that queue for this source).
+- **Database writes**: none.
+
+## External Dependencies
+
+- **Credentials**: `DodoPaymentsCredential` (`id = "dodo_payments"`): the
+ webhook secret is the `dodo_payments_webhook_key` row; it resolves only
+ while the API key is stored too.
+- **Services**: Dodo's webhook delivery (up to 8 attempts over about a day),
+ which needs a public URL for `/webhook/dodo-payments`.
+- **Python packages**: stdlib `hmac` / `hashlib` / `base64`, `fastapi`,
+ `pydantic`. The SDK is not used on this path.
+- **Environment variables**: none.
+
+## Edge cases & known limits
+
+- `TRIGGER_START_TO_CLOSE` (24 h) bounds the Temporal activity for a canvas
+ Run; there is no shorter wait timeout.
+- Retried deliveries keep their `webhook-id`, so a deployed listener drops a
+ retry as a duplicate; events can arrive out of order, so order by
+ `timestamp`.
+- Dodo's own `dodo wh trigger` CLI sends unsigned mock events, which this
+ source refuses; use the dashboard's Testing tab, which signs them.
+- No hire uses `dodoPaymentsReceive` as a trigger yet:
+ `config/employee_apps.json` keeps Dodo a tool-only app.
+
+## Related
+
+- **Sibling**: [`dodoPaymentsAction`](./dodoPaymentsAction.md); companion payments trigger [`stripeReceive`](../stripe/stripeReceive.md)
+- **Architecture docs**: [Dodo Payments Service](../../dodo_payments_service.md), [Event Waiter System](../../event_waiter_system.md), [Event Framework](../../event_framework.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/payments_agent.md b/docs-internal/node-logic-flows/specialized_agents/payments_agent.md
index 709a374a..4057409d 100644
--- a/docs-internal/node-logic-flows/specialized_agents/payments_agent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/payments_agent.md
@@ -10,16 +10,20 @@
## Purpose
-AI agent pre-configured for payment processing and financial workflows.
-No first-party payment tools ship with OpenCompany yet, so users typically
-wire `httpRequest` against a payment provider (Stripe, Razorpay) as a tool.
+AI agent pre-configured for payment processing and financial workflows. The
+payment providers plug in as ordinary tools on its `input-tools` handle;
+there is no provider registry on the agent itself.
## What is unique to this node
-- **Intended tool set**: `httpRequest` against payment APIs.
-- **Intended skills**: no dedicated `server/skills/payments_agent/` folder
- ships today -- the node is a naming / theming shell around
- `SpecializedAgentBase` -> `execute_chat_agent`.
+- **Intended tool set**: the first-party payment tools
+ [`stripeAction`](../stripe/stripeAction.md) (Stripe CLI) and
+ [`dodoPaymentsAction`](../dodo_payments/dodoPaymentsAction.md) (Dodo
+ Payments SDK), or `httpRequest` against any other payment API.
+- **Intended skills**: `server/skills/payments_agent/` ships `stripe-skill`
+ and `dodo-payments-skill`, attached automatically when their tool is wired
+ to an agent (`nodes/visuals.json`). The node itself is a naming / theming
+ shell around `SpecializedAgentBase` -> `execute_chat_agent`.
- **Frontend theming**: green dracula accent.
## Behaviour
diff --git a/server/nodes/README.md b/server/nodes/README.md
index a5f0cee7..1e91ef66 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -238,6 +238,9 @@ workflow/ — start / approvalGate ("ask me before sending")
skill/ — masterSkill (skill/simple_memory is only an import shim for tool/simple_memory)
browser/ — browser (installed Chrome/Edge/Chromium + browser-use CLI; Chrome for Testing opt-in, profiles, live view and user takeover)
stripe/ — Stripe (CLI passthrough action + signed-webhook trigger)
+dodo_payments/ — Dodo Payments (dodopayments SDK: payments / subscriptions / customers / refunds /
+ checkout links / any endpoint via call + list_operations; Standard Webhooks trigger;
+ palette group "payments")
vercel/ — Vercel (CLI deploy / inspect / list / custom passthrough)
github/ — GitHub (gh CLI: clone / PRs / issues / custom; palette group "vcs")
cloudflare/ — Cloudflare (cf CLI: command search / zones / DNS / GraphQL analytics / custom; palette group "deployment")
diff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.md
index 55b9cbe4..0fbae4a0 100644
--- a/server/skills/GUIDE.md
+++ b/server/skills/GUIDE.md
@@ -29,7 +29,7 @@ server/skills/
├── gcloud/ # gcloud-skill (Google Cloud CLI)
├── github/ # github-skill (gh CLI)
├── language_agent/ # speech-skill, translation-skill
-├── payments_agent/ # stripe-skill
+├── payments_agent/ # stripe-skill, dodo-payments-skill
├── productivity_agent/ # Google Workspace + Microsoft 365 skills
│ google-gmail-skill, google-calendar-skill, google-drive-skill,
│ google-sheets-skill, google-tasks-skill, google-contacts-skill,