Skip to content

Self-improving AI Employees for everyone

11.1 KB
Raw Blame

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 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 @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 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).