Stripe Skill

Stripe Skill

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.

Schema

Response

jsonCopy code
{
  "command": "customers create --email a@b.com",
  "success": true,
  "result": {
    "id": "cus_NkXz123",
    "email": "a@b.com",
    "object": "customer",
    "created": 1730000000,
    ...
  },
  "stdout": "<raw CLI stdout>"
}

On CLI failure the tool raises an error with Stripe's own message (e.g. "No such customer: cus_invalid").

Common commands

Customers

Search:

PaymentIntents (recommended for charges)

Charges (legacy direct-charge path)

For new integrations prefer PaymentIntents over direct charges create — Stripe deprecated raw card-token charge creation.

Refunds

Invoices & Subscriptions

Products & Prices

Trigger (synthetic test events)

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.

Common workflows

Create a customer and charge them

jsonCopy code
{ "command": "customers create --email rosy@sparrow.com --name 'Rosy Sparrow'" }

returns cus_…. Then:

jsonCopy code
{ "command": "payment_intents create --amount 2000 --currency usd --customer cus_xxx --payment-method pm_card_visa --confirm" }

Refund the most recent payment for a customer

jsonCopy code
{ "command": "payment_intents list --customer cus_123 --limit 1" }

read data[0].id, then:

jsonCopy code
{ "command": "refunds create --payment-intent pi_xxx" }

Set up a recurring subscription

jsonCopy code
{ "command": "products create --name 'Pro Plan'" }     -> prod_xxx
{ "command": "prices create --product prod_xxx --unit-amount 2000 --currency usd --recurring='{\"interval\":\"month\"}'" }   -> price_xxx
{ "command": "subscriptions create --customer cus_xxx --items='[{\"price\":\"price_xxx\"}]'" }

Quoting and escaping

The command string is parsed with shlex.split before being handed to stripe. Use single quotes for arguments that contain spaces:

JSON inside --items / --recurring etc. should be a single quoted JSON string with no internal spaces — the CLI parses it on the server side.

Idempotency

For any create/charge that you don't want to duplicate on retry, add an idempotency key:

Copy code
customers create --email a@b.com -H "Idempotency-Key: order_42_user_7"

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:

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:

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):

The trigger output mirrors Stripe's event shape: event_id, event_type, created, livemode, api_version, request_id, account, data.

Authentication — stripe login (browser OAuth)

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:

1. 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.
2. 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).
3. 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

1. 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.
2. Default to test mode for development. The CLI distinguishes modes; livemode: true/false is on every response.
3. Add idempotency keys to all create operations. Especially for charges and refunds — accidental retry without a key duplicates the charge.
4. Quote string arguments with spaces (--name 'Acme Inc').
5. Use PaymentIntents, not raw charges for new integrations.
6. Surface Stripe error messages verbatim to the user. They are precise and actionable; don't paraphrase them.
7. 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

1. Stripe CLI binary — auto-downloaded on first Login with Stripe click if not already on PATH. Resolution order:
   • System install (brew install stripe/stripe-cli/stripe, scoop install stripe, apt install stripe, or a direct binary from https://stripe.com/docs/stripe-cli#install).
   • OpenCompany package cache at <DATA_DIR>/packages/stripe/bin/stripe[.exe] (populated automatically from GitHub releases — pinned to a known-good CLI version).
2. 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).
3. The Stripe action node is connected to your agent's input-tools handle.
4. (For webhook flows) A stripeReceive trigger node is wired into your workflow with the event-type filter you care about.