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

Connect Stripe to Fondoo (read-only revenue)

Live5 min readUpdated

Use this when you already sell with Stripe and want Fondoo to see your sales without being able to change anything. You give Fondoo a restricted Stripe key that can only read, and your AI agent can then look at recent charges and subscriptions. Fondoo charges no fee here and never creates, refunds or cancels anything in your account.

To sell through Fondoo instead, use the stripe (Fondoo-managed) or stripe_direct (your own key) guides.

What Fondoo can do with it

The stripe_revenue connector has two read actions, both used through connector_action:

  • orders.list: the 50 most recent charges in your account.
  • subscriptions.list: the 50 most recent subscriptions.

Neither needs approval, because both only read. The connector has no write, refund or cancel action. Checkout, payments and refunds stay with Fondoo's normal payment operations or your Stripe Dashboard.

Optional: automatic revenue tracking. If you also want each sale recorded in Fondoo as it happens (orders, refunds, subscription status, analytics), the owner can add a read-only Stripe connection with a webhook. It uses connect_existing_stripe_readonly. See the Webhooks section. It is also read-only and has a 0% fee.

Before you start

  • A Stripe account with the sales you want Fondoo to see.
  • Permission to create API keys in that account (an Administrator or Developer role in Stripe).
  • Test and live are separate. A sandbox key (rk_test_) only sees sandbox data. A live key (rk_live_) sees real sales.
  • No Stripe plan or fee is needed for API access.

Step by step: get your credentials

  1. Sign in to Stripe. Pick live mode (or a sandbox for testing) with the switch on the API keys page.
  2. Open API keys: https://dashboard.stripe.com/apikeys. You can also go through Developers → Workbench, then API keys → Manage on the Overview tab.
  3. Click Create restricted key. Give it a Key name such as Fondoo read-only.
  4. Leave everything at None except these, which you set to Read:
    • Charges (for orders.list).
    • Subscriptions (for subscriptions.list).
    • Accounts (the "Direct" read permission). Fondoo's connection test reads your own account. Without it the test can fail with a permission error. If you can't find the label, the permissions reference calls it connected_account_read.
    • If you will also set up automatic tracking, add Read for PaymentIntents, Checkout Sessions, Invoices (and Invoice payments, if listed), Customers, Products and Prices.
  5. Do not give any Write permission. Fondoo doesn't need it.
  6. Click Create key, confirm with two-step verification and copy the key. Stripe shows a live key you create only once (Stripe API keys).

Connect it in Fondoo

In the dashboard

  1. Open Connections.
  2. Under Available, search for Stripe. In the Payments group, pick the Stripe card that has a Use a key button (that is stripe_revenue; the other Stripe card is the managed setup) and click Use a key.
  3. Click Open secure key entry. The page is single-use and expires after 15 minutes.
  4. Paste the restricted key into apiKey and save.
  5. Back on Connections, click Check connection on the new card.

By asking your agent

Example prompt:

Connect my Stripe account read-only so you can see my sales. Send me a secure link for the key.

The agent calls add_connection_key({provider:"stripe_revenue", siteId}) without fields. It returns a secure paste link, so the key never enters the chat. After you paste the key, the agent runs test_connection({connectionId}), then for example:

connector_action({ connectionId: "<id>", action: "orders.list", input: {} })

For a help link only, connect_service({provider:"stripe_revenue", siteId}) returns signed instructions valid for 15 minutes.

Over REST:

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

{"provider":"stripe_revenue","siteId":"<site id>"}

The same pattern works for /v1/ops/test_connection and /v1/ops/connector_action.

Webhooks

The stripe_revenue connector does not use webhooks. It reads when asked.

For automatic tracking, the owner connects a separate read-only connection that does use a webhook:

  1. In Stripe, open Developers → Workbench → Webhooks and click Create an event destination (Workbench may label it Add destination). Choose Your account.
  2. Choose the Snapshot payload and select these events: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, charge.refunded, charge.dispute.created.
  3. Choose Webhook endpoint and enter https://<your Fondoo API host>/webhooks/stripe/readonly/<siteId>/<mode>, where mode is test or live. On hosted Fondoo the host is normally api.getfondoo.com. Check it against the webhookUrl Fondoo returns in step 5.
  4. Open the endpoint and click Reveal secret to copy the whsec_ signing secret (Stripe webhooks).
  5. The owner runs connect_existing_stripe_readonly({siteId, mode, restrictedKey, webhookSecret}) (REST: POST /v1/ops/connect_existing_stripe_readonly). It only accepts an rk_ restricted key whose mode matches.

Stripe signs each event in the Stripe-Signature header. Fondoo verifies the raw body before using it, and Stripe's libraries reject events older than 5 minutes. A site and mode can have only one Stripe payment connection, so you can't add this to a site that already takes payments through Fondoo.

Test that it works

  1. Run test_connection (or click Check connection). A pass means the key works and can read your account.
  2. Ask: "Show my last Stripe charges." The agent runs orders.list. Check that the charges match your Stripe Dashboard.
  3. Ask for subscriptions (subscriptions.list). If this fails with a permission error, add Subscriptions: Read to the key.
  4. If you set up the webhook, make a sandbox test purchase. Then confirm in Stripe that the event shows a successful delivery.

Troubleshooting

  • Permission error that names a permission. The key is missing it. Stripe's error message names the permission. Edit the key in Stripe or create a new one, then paste it again with rotate_connection_key.
  • Test passes but you see no data. You probably used a sandbox key for live sales, or the reverse. Check the prefix: rk_live_ for real sales.
  • "Key mode mismatch" (read-only webhook setup). The key must start with rk_test_ or rk_live_ to match mode. A secret sk_ key is refused.
  • "Payment account already connected". This site and mode already takes payments through Fondoo. Use another site or mode.
  • Webhook deliveries fail in Stripe. Check the URL (site ID and mode) and that the signing secret is the one for this endpoint. Sandbox and live endpoints have different secrets.
  • 429 responses. Stripe allows about 100 requests per second live and 25 in sandboxes. Fondoo also limits this connector to 60 actions per minute.

Limits, data and security

  • What Fondoo stores: the key, encrypted, never shown again. list_connections shows only a masked version. Results of orders.list are returned to you, not kept as a copy. The webhook connection stores the account ID and the orders and subscription states it records.
  • Rotate: in Stripe use ⋯ → Rotate key. Then run rotate_connection_key({connectionId}) and paste the new key on the secure page.
  • Disconnect: run delete_connection({connectionId}) (it removes the stored key and needs owner approval for agents). Then expire the key in Stripe (⋯ → Expire key). Fondoo cannot revoke the key in Stripe for you.