stripe-skill

name: stripe-skill description: 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. allowed-tools: "stripe_action" metadata: author: machina version: "1.0" category: payments

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

Field	Type	Required	Description
command	string	Yes	Stripe CLI command (e.g. `"customers create --email a@b.com"`). Quote arguments that contain spaces.

Response

{
  "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

Command	Purpose
`customers create --email <addr>`	Create a customer. Optional: `--name`, `--description`, `--phone`, `--metadata key=val`.
`customers retrieve <cus_id>`	Fetch a customer by id.
`customers list --limit 10`	List recent customers. Optional: `--email <addr>` filter.
`customers update <cus_id> --email <new>`	Update fields on a customer.
`customers delete <cus_id>`	Permanently delete a customer.

Search:

Command	Purpose
`customers search --query "email:'a@b.com'"`	Server-side search across customers. Stripe Search query syntax.

PaymentIntents (recommended for charges)

Command	Purpose
`payment_intents create --amount 2000 --currency usd`	Create a PaymentIntent for $20.00. Amount is in the smallest currency unit (cents for USD).
`payment_intents create --amount 2000 --currency usd --customer cus_123`	Create attached to a saved customer.
`payment_intents create --amount 2000 --currency usd --confirm --payment-method pm_card_visa`	Create + confirm in one shot (most common test path).
`payment_intents retrieve pi_123`	Fetch by id.
`payment_intents list --limit 20`	List recent intents.
`payment_intents cancel pi_123`	Cancel an unconfirmed or processing intent.

Charges (legacy direct-charge path)

Command	Purpose
`charges retrieve ch_123`	Fetch a charge by id.
`charges list --limit 10`	List recent charges.
`charges list --customer cus_123`	List charges for a specific customer.

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

Refunds

Command	Purpose
`refunds create --payment-intent pi_123`	Refund a PaymentIntent in full.
`refunds create --payment-intent pi_123 --amount 500`	Partial refund (in smallest currency unit).
`refunds create --charge ch_123`	Refund by charge id (older flow).
`refunds retrieve re_123`	Fetch a refund by id.
`refunds list --limit 10`	List recent refunds.

Invoices & Subscriptions

Command	Purpose
`invoices create --customer cus_123`	Draft an invoice.
`invoices finalize_invoice in_123`	Finalize a draft (locks for sending/charging).
`invoices pay in_123`	Charge the customer for a finalized invoice.
`invoices list --customer cus_123`	List invoices for a customer.
`subscriptions create --customer cus_123 --items='[{"price":"price_xxx"}]'`	Create a subscription.
`subscriptions retrieve sub_123`	Fetch a subscription.
`subscriptions cancel sub_123`	Cancel immediately.
`subscriptions update sub_123 --cancel-at-period-end true`	Cancel at end of current billing period.

Products & Prices

Command	Purpose
`products create --name "Pro Plan"`	Create a product.
`prices create --product prod_123 --unit-amount 2000 --currency usd --recurring='{"interval":"month"}'`	Create a recurring price tied to a product.
`prices list --product prod_123`	List prices for a product.

Trigger (synthetic test events)

Command	Purpose
`trigger payment_intent.succeeded`	Fire a synthetic PaymentIntent succeeded event.
`trigger charge.refunded`	Fire a synthetic refund event.
`trigger customer.subscription.created`	Fire a synthetic subscription event.

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

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

returns cus_…. Then:

{ "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

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

read data[0].id, then:

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

Set up a recurring subscription

{ "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:

You want to send	Type this in `command`
`--name=Acme Inc`	`customers create --name 'Acme Inc'`
metadata with spaces	`customers update cus_x --metadata 'plan=Acme Pro'`
a JSON array as a flag value	`subscriptions create --items='[{"price":"price_xxx"}]'`

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:

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:

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 MachinaOs 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, …)
`payment_intent.*`	every PaymentIntent event

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