Knowledge & tools

Stripe tool

The Stripe tool lets an agent run the money side of a business in a Stripe account - manage customers, collect payments, send invoices, issue refunds, and view and cancel subscriptions. It has 25 actions, and one tool configuration maps to one Stripe account. Set it up once with an API key, then assign it to a bot.

The agent never handles card numbers - and that's by design. To collect a payment, it creates a payment link or an invoice, and the customer enters their card on Stripe's own secure page. There is no action that takes, stores, or asks for a card number, CVC or expiry. This keeps your business out of PCI scope: sensitive card data only ever touches Stripe, never Hania and never the agent.

Amounts are in cents, everywhere. 1500 means $15.00, not $1,500. This is how Stripe's API works, so any amount the agent sends is an integer number of cents. The agent is instructed to restate amounts in dollars and confirm with you before charging, but it's worth knowing when you read a trace.

What it can do

The agent chooses one action per call. The 25 actions, by area:

Customers - list_customers, get_customer, create_customer, update_customer, delete_customer, search_customers.
Products & prices - list_products, create_product, list_prices, create_price (recurring via an interval).
Collect payment - create_payment_link (returns a hosted URL to share), list_payments, get_payment, create_refund.
Invoices - add_invoice_item, create_invoice, finalize_invoice, send_invoice, void_invoice, get_invoice, list_invoices.
Subscriptions - list_subscriptions, get_subscription, cancel_subscription.
Account - get_balance.

How payments get collected

The agent has two ways to ask for money, and both keep card entry on Stripe's pages:

Payment link - create_payment_link with an amount and currency (or an existing price) returns a hosted URL. The agent shares the URL, and the customer pays on Stripe's page.
Invoice - the agent adds line items, creates the invoice, finalizes it, and sends it. Stripe emails the customer a hosted, payable invoice (due in 30 days by default).

A payment link or invoice being created is a request for payment, not payment received. Creating the link or sending the invoice doesn't move any money - the customer still has to open it and pay. Use list_payments / get_payment to check whether a payment actually came through.

Getting your API key

The tool needs one Stripe API key. A restricted key is the recommended choice - it can do only what you grant it, so you can scope the agent narrowly and widen later.

In the Stripe Dashboard, go to Developers → API keys.
Click Create restricted key, and grant Write on the resources the agent should manage: Customers, Products, Prices, Payment Links, Payment Intents, Charges, Refunds, Invoices, Invoice Items and Subscriptions; and Read on Balance. (A full secret key works too, but it grants everything - restricted is safer.)
Copy the key and paste it into the Hania form.

Test first, safely. Use a test-mode key (rk_test_… or sk_test_…) to try the agent end to end - test payments use Stripe's test cards and move no real money. Switch to a live key (rk_live_… / sk_live_…) when you're ready. If a restricted key is missing a permission, only that one action fails, with a clear permission error the agent reports - so you can grant more later without breaking anything. The tool pins a modern Stripe API version internally, so it works whatever your account's default version is.

Field reference

Secret or Restricted API Key (required, secret) - a Stripe secret key (sk_live_ / sk_test_) or restricted key (rk_live_ / rk_test_) from Developers → API keys. A restricted key can do only what its permissions allow; the tool surfaces Stripe's permission errors. Stored encrypted and never returned.

What the agent can and can't do

The actions above are the full set. A few boundaries are deliberate:

Never handles card details. The agent cannot take, store, or enter a card number, CVC or expiry - collection is always through a Stripe-hosted page. This is enforced in the tool, so it's a promise you can rely on.
Doesn't create subscriptions. Starting a subscription needs a saved payment method, which is an advanced flow; the agent can list, view and cancel existing subscriptions, but not create new ones.
Not included - Connect / marketplace, disputes, payouts, tax, and Terminal (in-person) are outside this tool.

What it does do that's worth stating plainly: it can issue refunds and cancel subscriptions, and it can delete customers - all real, high-stakes actions, which is why the tool is set up to confirm before it acts (see Safety).

A note on amounts

The agent works in the account's currency and, because Stripe amounts are integer cents, it restates every amount in dollars and confirms with you before it charges, refunds, or sends an invoice. If a trace shows 1500, that's $15.00.

Troubleshooting

403 permission error - a restricted key is missing the permission that action needs. Add it to the key in the Stripe Dashboard; only that action was affected.
400 "add items before creating an invoice" and similar - a validation error the agent self-corrects (here, by adding invoice items first), so it may flash through a trace before the call succeeds.
402 on a test payment - a declined test card. Use one of Stripe's test cards that simulates success.
Missing amount / missing customer - retry-shaped validation the agent fills in and retries. Error text comes verbatim from Stripe.

Safety in autonomous runs

Like any tool, the Stripe tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because refunds, cancellations, deletes and collecting money are all high-stakes, a new configuration is created with Read-only switched off, Destructive switched on, and Sends data externally on - so destructive actions are gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, and prefer the tighter control: a restricted key scoped to exactly what the agent needs enforces a limit at Stripe, not just in the app. Interactive chat is never gated by these flags.

Security

The API key is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a key is set. Editing a configuration without retyping the key preserves the stored one, so you must retype it to replace it. To revoke access, roll or delete the key in the Stripe Dashboard.

Blueprint

The fastest way to a working payments agent is the Payments Assistant blueprint (finance category) - a pre-built agent wired for customer, payment and invoice workflows, including the restate-in-dollars and confirm-before-charging habits described above. Pick it from the blueprint gallery when creating a bot; the only thing you supply is the API key from this guide.