Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect your own Stripe account to Fondoo (direct mode)

Live5 min readUpdated

Direct mode lets Fondoo sell through a Stripe account you already own, using a key you create. There is no Stripe Connect account and no Fondoo application fee on these checkouts. Your AI agent can still manage products, prices, coupons and checkout links, and buyers pay straight into your account.

If you are new to Stripe, the simpler option is the Fondoo-managed stripe setup. If you only want Fondoo to read your sales, use stripe_revenue.

What Fondoo can do with it

After you connect your key, Fondoo uses the same payment operations as the managed setup, but against your own account:

  • Catalog: create and update products (upsert_product), add prices (upsert_price, prices can't be edited in Stripe, so a change creates a new one), create percentage coupons (create_coupon), list and archive products (list_products, archive_product).
  • Checkout: create Stripe-hosted Checkout links (create_checkout_link) and pricing blocks on your pages (add_pricing_block). Creating a link never charges anyone.
  • Customers: customer portal links (get_customer_portal_link) and automatic tax (configure_payment_tax, once Stripe Tax is active in your account).
  • Status: get_payments_status shows the connected account and whether charges are enabled.

Your existing Stripe Payment Links, invoices and subscriptions are left alone. Fondoo only touches objects it creates.

What needs your approval: connecting the key is an owner-only action. Agent changes to live products, prices and coupons need your approval. Agents cannot refund, pay out or answer disputes. Do those in the Stripe Dashboard.

Fees: you pay Stripe's normal fees (Stripe pricing). In direct mode Fondoo does not attach a Stripe application fee to checkouts.

Before you start

  • A Stripe account that is activated for live payments, if you want live mode. Sign in at dashboard.stripe.com.
  • A paid Fondoo plan for live mode. Test mode works on any plan.
  • Owner access to the Fondoo workspace. Only the owner can connect a payment key.
  • One key per mode. A test key (rk_test_ or sk_test_) connects test mode. A live key (rk_live_ or sk_live_) connects live mode. Fondoo rejects a key whose mode doesn't match.

Step by step: get your credentials

Use a restricted key. It limits what the key can do if it ever leaks (Stripe restricted keys).

  1. Sign in to Stripe. Choose sandbox (for test mode) or live mode with the switch on the API keys page.
  2. Go to the API keys page: https://dashboard.stripe.com/apikeys. You can also reach it from Developers → Workbench → Overview → API keys → Manage.
  3. Click Create restricted key. If Stripe offers preset permissions, you can skip them and set each permission yourself.
  4. Enter a Key name, for example Fondoo direct.
  5. Set these permissions. Every resource starts at None. Write also lets the key read.
    • Write: Products, Prices, Coupons, Checkout Sessions, Customer portal.
    • Read: Customers, Subscriptions, Invoices (and Invoice payments, if listed), Tax settings.
    • Read: Accounts (the "Direct" account permission). Fondoo reads your own account once to check the key belongs to you. Stripe's labels in this editor can change. If a label is missing, search the permissions reference for connected_account_read.
  6. Click Create key and complete two-step verification.
  7. Copy the key now. In live mode Stripe shows a key you create only once. Store it in your password manager until you paste it into Fondoo.

Connect it in Fondoo

Direct mode is connected with the owner-only operation configure_payment_provider. It takes the key itself, so run it in a place you control. Avoid pasting a live key into a chat where it will be stored in the history.

In the dashboard

There is no direct-mode form in the Fondoo dashboard today. On Connections, find Stripe under Payments and click Connect Stripe for the steps. Then run the call below yourself, or ask your agent with an owner key.

By asking your agent

Example prompt (owner session):

Connect my own Stripe account to my store site in test mode. I'll give you the restricted key.

The agent calls:

configure_payment_provider({ siteId: "<site id>", mode: "test", secretKey: "rk_test_..." })

Fondoo checks the key mode, reads your Stripe account to confirm it, encrypts the key and switches the site's payment provider to stripe_direct. The response shows configured: true and your Stripe accountId.

For instructions only, connect_service({provider:"stripe_direct", siteId}) returns a signed help link valid for 15 minutes. add_connection_key and test_connection are not used for this provider.

Over REST:

POST https://api.getfondoo.com/v1/ops/configure_payment_provider
Authorization: Bearer <your Fondoo owner API key>
Content-Type: application/json

{"siteId":"<site id>","mode":"test","secretKey":"rk_test_..."}

Use the same call with mode:"live" and a live key when you are ready.

Webhooks

Stripe tells Fondoo about paid checkouts and subscription changes through webhooks. For direct mode, Fondoo accepts these only on self-hosted Fondoo. There, the operator creates a Stripe webhook endpoint for https://<your Fondoo API host>/webhooks/stripe/direct/<siteId>/<mode> and adds its whsec_ signing secret to STRIPE_DIRECT_WEBHOOK_SECRETS. Subscribe to: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, charge.refunded and charge.dispute.created. Stripe signs each event with the Stripe-Signature header, and Fondoo verifies it before reading anything (Stripe webhooks).

On hosted Fondoo there is no owner setting for a direct-mode signing secret. Orders and subscriptions from direct checkouts may not be recorded automatically. This may differ for your account. If you need automatic order tracking on hosted Fondoo, use the managed stripe option, or ask Fondoo support.

Test that it works

  1. Ask your agent: "Check my payments status for test mode." It calls get_payments_status({siteId, mode:"test"}). Look for connected: true and chargesEnabled: true.
  2. Create a test product with a price (upsert_product), then a checkout link (create_checkout_link).
  3. Open the link and pay with a Stripe test card such as 4242 4242 4242 4242 (Stripe testing).
  4. Check the payment in your Stripe Dashboard (sandbox view).

Troubleshooting

  • "Stripe key mode mismatch; prefer a restricted key". The key's mode doesn't match mode. Use rk_test_/sk_test_ with test, and rk_live_/sk_live_ with live.
  • "Live payments require a paid workspace plan". Upgrade Fondoo, or connect test mode first.
  • A Stripe permission error naming a permission. The restricted key is missing a permission. Stripe's error says which one. Edit the key in Stripe, or create a new key with that permission and connect again.
  • chargesEnabled is false. Your Stripe account isn't activated for payments yet. Finish activation in the Stripe Dashboard.
  • Forbidden / owner required. Only the workspace owner (or an owner API key) can run configure_payment_provider.
  • 429 errors from Stripe. You hit Stripe's rate limit (about 100 requests per second live, 25 in sandboxes). Wait and retry (Stripe rate limits).

Limits, data and security

  • What Fondoo stores: your key, encrypted, plus your Stripe account ID and mode. The key is never shown again. Fondoo also stores the products, prices and checkouts it creates.
  • Rotate the key: in Stripe, open the key's ⋯ menu and choose Rotate key. Pick an expiration so the old key keeps working while you switch (up to 7 days). Then run configure_payment_provider again with the new key (Stripe API keys).
  • Revoke access: in Stripe, use ⋯ → Expire key. Fondoo can no longer act on your account. To switch the site back to Fondoo-managed payments, the owner can run set_provider({siteId, capability:"payments", provider:"stripe"}).