Process payments, manage customers, issue refunds, and handle subscriptions via the Stripe CLI. Pass any Stripe command (customers, charges, payment_intents, refunds, invoices, products, prices, subscriptions) and the tool runs it for you and returns parsed JSON.
Process payments, manage customers, issue refunds, and handle subscriptions via the Stripe CLI. Pass any Stripe command (customers, charges, payment_intents, refunds, invoices, products, prices, subscriptions) and the tool runs it for you and returns parsed JSON.
Pass-through over the official Stripe CLI.
The tool runs stripe <command> --api-key <stored-key> for you and
returns parsed JSON. Every Stripe resource the CLI supports works
without code changes — products and prices created tomorrow work the
same way.
Tool: stripe_action
Single field: command — a string identical to what you would type
after stripe on the terminal.
stripe trigger is invaluable for testing webhook flows — it sends
the event to Stripe, which sends it back through the same stripe listen daemon and into your stripeReceive trigger node.
The CLI accepts custom headers via -H. Stripe deduplicates by the
key for 24 hours.
Test mode vs live mode
The stored API key (set in the Credentials Modal) determines mode:
Key prefix
Mode
Effect
sk_test_…
Test
Fake money, fake events, no real charges. Always use this for development.
sk_live_…
Live
Real money. Real customers. Use only after thorough testing.
rk_test_… / rk_live_…
Restricted
Scoped permissions; recommended for production agents that don't need full account access.
The CLI reports livemode: true/false on every response object so
you can verify which environment a result is from.
Errors
Stripe returns structured errors that surface in the tool's error
field. Common ones:
Error code
Meaning
Recovery
resource_missing
The id you passed doesn't exist
Verify the id; list to find the right one
card_declined
Card payment failed
Use a different --payment-method; in test mode try pm_card_visa
invalid_request_error
Wrong / missing argument
Check stripe <resource> create --help
authentication_required
3DS challenge needed
Use a setup_intent or off-session payment_method
rate_limit_error
Too many requests
Pause and retry; Stripe rate limit is 100/sec in live, 25/sec in test
The CLI's stderr always contains the Stripe request id (req_…) —
include it when reporting issues.
Webhooks (stripeReceive trigger)
When the Stripe daemon is connected (Credentials Modal → Stripe →
Connect), every event Stripe sends is forwarded to OpenCompany and
delivered to any active stripeReceive trigger nodes after
HMAC-SHA256 signature verification (Stripe-Signature header).
To test event delivery without making real payments, use the
trigger command above. Events fire through the same path as real
ones.
Filters on the trigger node (event_type_filter):
Filter
Matches
all
every event
charge.succeeded
exact match
charge.*
every charge.* event (succeeded, refunded, failed, …)
Authentication is delegated entirely to the Stripe CLI. There is no
API key to paste into OpenCompany. The Credentials Modal's Login
with Stripe button drives the CLI's two-step machine-friendly
login:
Browser-side: the modal opens
https://dashboard.stripe.com/stripecli/auth/... in a new tab and
shows a verification code. The user signs in to Stripe and
confirms the code.
CLI-side: the CLI polls Stripe until the user authorises,
then writes credentials (one restricted key per mode, valid for
90 days) to ~/.config/stripe/config.toml (or
$XDG_CONFIG_HOME/stripe/config.toml).
OpenCompany-side: when login completes, the listen daemon
starts automatically and captures the webhook signing secret.
After login, every stripe … command run via this tool reads its
credentials from the CLI's config file — no --api-key flag in any
command you'd type.
Logout (Credentials Modal → Disconnect) stops the listen daemon
and runs stripe logout --all to clear the config file.
Best practices
Restricted keys are auto-issued. When you stripe login, the
CLI generates restricted keys with CLI-appropriate scopes (one
per test/live mode) — you don't pick scopes manually.
Default to test mode for development. The CLI distinguishes
modes; livemode: true/false is on every response.
Add idempotency keys to all create operations. Especially for
charges and refunds — accidental retry without a key duplicates
the charge.
Quote string arguments with spaces (--name 'Acme Inc').
Use PaymentIntents, not raw charges for new integrations.
Surface Stripe error messages verbatim to the user. They are
precise and actionable; don't paraphrase them.
Don't include --api-key in your command string. The CLI
already has stored credentials; an inline --api-key overrides
them and risks key leakage in process listings and logs.
Setup checklist
Stripe CLI binary — auto-downloaded on first Login with
Stripe click if not already on PATH. Resolution order:
OpenCompany package cache at
<DATA_DIR>/packages/stripe/bin/stripe[.exe] (populated
automatically from GitHub releases — pinned to a known-good
CLI version).
Credentials Modal → Stripe → Login with Stripe → a browser
tab opens to the Stripe Dashboard with a pairing code. Authorise.
The modal flips to "Connected" when the CLI's login --complete
subprocess returns and the listen daemon spins up
(webhook_secret_captured: true).
The Stripe action node is connected to your agent's
input-tools handle.
(For webhook flows) A stripeReceive trigger node is wired into
your workflow with the event-type filter you care about.
