Self-improving AI Employees for everyone
Dodo Payments Service
Self-contained plugin at 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 tooldodo_payments_action): typed operations for the everyday flows (payments, subscriptions, customers, products, refunds, disputes, checkout and customer-portal links),callfor any other SDK method, andlist_operationsto 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 @Operations, 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.
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
Literals; 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
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
dodoPaymentsReceiveas a trigger yet;employee_apps.jsonkeeps Dodo a tool-only app, as for Stripe. WebhookSource.receive()queues each event on a push queue nothing drains (shared with Stripe's source).