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

Connect Paddle to Fondoo

Live5 min readUpdated

If you sell with Paddle Billing, this connection lets Fondoo see your paid transactions, refunds and subscriptions. Your AI agent can then report revenue, credit sales to the visits that led to them, and keep your customers' plans in sync. Fondoo only reads. It cannot refund, cancel, credit or charge.

What Fondoo can do with it

Six read-only actions, used through connector_action:

  • transactions.pull: completed and paid transactions, plus approved refund adjustments.
  • subscriptions.pull: subscription status (active, past due, cancelled).
  • customers.list: customer IDs and emails.
  • webhooks.verify and webhooks.parse: check and read Paddle notifications.
  • dashboard.link: a link into the Paddle dashboard for a person to open.

When you bind the connection to a site with connect_revenue_source, Fondoo imports sales as orders and analytics conversions. Subscriptions become entitlements that can update a customer's plan in your app. Webhooks and sync_revenue_source keep this current.

What needs your approval: an agent binding a live source or changing its product map needs the owner's approval. Reads never do. There is no refund or charge action. Do those in Paddle.

Before you start

  • A Paddle Billing account. This guide does not cover Paddle Classic, which has a separate system and no longer takes new signups (Paddle Classic).
  • Sandbox or live. Paddle sandbox and live are separate accounts with separate keys and notification settings (sandbox). Sandbox dashboard: sandbox-vendors.paddle.com. Live: vendors.paddle.com.
  • Live mode in Fondoo needs a paid Fondoo plan. Test mode works on any plan.
  • API access has no extra cost. Paddle's sales fees are on its pricing page.

Step by step: get your credentials

  1. Sign in to the Paddle dashboard for the environment you want (sandbox or live).
  2. Open Authentication and the API keys tab. Paddle's docs place it under your account settings (Paddle → My account → Settings → Authentication). Fondoo's earlier notes call this Developer tools → Authentication. Use whichever your dashboard shows (API keys).
  3. Click New API key.
  4. Fill in Name (for example Fondoo) and an optional Description.
  5. Under Permissions, choose only these read permissions (permissions):
    • transaction.read: for sales.
    • adjustment.read: for refunds.
    • subscription.read: for subscription status.
    • customer.read: for customer IDs and emails.
  6. Set an Expiry date. The default is 90 days, and the maximum is one year. Put a reminder in your calendar.
  7. Save, then copy the key. Paddle shows it only once. Live keys start with pdl_live_apikey_, and sandbox keys with pdl_sdbx_apikey_.

What goes where:

Fondoo fieldWhat to paste
API key (apiKey)the key from step 7
Environment (environment)optional: production or sandbox. Fondoo reads it from the key prefix anyway
Notification destination secret key (webhookSecret)leave empty for now. Add it in the Webhooks step

Connect it in Fondoo

In the dashboard

  1. Open Connections.
  2. Under Available, find Paddle (in Payments) and click Use a key.
  3. Click Open secure key entry (single use, expires after 15 minutes). Paste the key and save.
  4. On the new card under Connected, click Check connection.

By asking your agent

Example prompt:

Connect my Paddle account to my site and import my sales. Send me a secure link for the key.

The agent runs:

add_connection_key({ provider: "paddle", siteId: "<site id>" })
test_connection({ connectionId: "<id>" })
connect_revenue_source({ siteId: "<site id>", connectionId: "<id>", mode: "live",
  productMap: { "pro_01h...": "pro" } })     // Paddle product ID → Fondoo plan; returns webhookUrl
sync_revenue_source({ sourceId: "<source id>" })

Products you don't map are still recorded as revenue. For a help link only, use connect_service({provider:"paddle", siteId}). It is signed and valid for 15 minutes.

Over REST: POST https://api.getfondoo.com/v1/ops/<operation> with Authorization: Bearer <your Fondoo API key> and the same JSON body, for example POST /v1/ops/add_connection_key with {"provider":"paddle","siteId":"<site id>"}.

Webhooks

  1. Copy the webhookUrl returned by connect_revenue_source (also in get_revenue_sources). It looks like https://<Fondoo API host>/webhooks/revenue/<connectionId>.
  2. In Paddle open Notifications (Paddle's docs: Paddle → Events → Notifications) and click New destination (notification destinations).
  3. Enter a Description, choose the webhook type, and paste the URL.
  4. Select these events: transaction.paid, transaction.completed, adjustment.created, adjustment.updated, and all subscription.* events (created, activated, updated, past_due, paused, resumed, canceled, trialing, imported).
  5. Click Save destination. Copy the destination's secret key right away. Paddle's docs disagree on whether you can view it again later, so don't rely on that.
  6. In Fondoo, run rotate_connection_key({connectionId}). On the secure page, paste the API key again and the secret in Notification destination secret key. The page replaces all fields together.

Paddle signs each delivery with a Paddle-Signature header (ts=...;h1=...), an HMAC-SHA256 of the timestamp and raw body (signature verification). Fondoo rejects signatures older than 5 seconds, as Paddle recommends.

Fondoo checkouts set custom_data.visit_id and custom_data.external_user_id on the transaction, so sales can be credited to the visit that led to them.

Test that it works

  1. Run test_connection. It confirms transaction.read. The other three permissions show as "unknown" until Fondoo first uses them. That's expected.
  2. Run sync_revenue_source({sourceId}). Check get_revenue_sources({siteId}) for a fresh lastSyncAt and no lastError.
  3. In sandbox, complete a test checkout. In Paddle, the notification log should show a successful delivery to Fondoo.

Troubleshooting

  • "API key does not match the selected environment". You set environment to sandbox with a pdl_live_ key, or the reverse. Fix the field or leave it empty.
  • 403 forbidden on reads. The key is missing a permission, or it belongs to the other environment. Edit the key's permissions in Paddle, or create a new key and rotate it in.
  • 401 after a few months. The key expired (90 days by default). Create a new one and run rotate_connection_key.
  • Webhooks rejected. Check that the secret matches this destination and that the URL has the right connection ID. Fondoo also refuses signatures more than 5 seconds old. The notification log in Paddle shows each failed delivery, and a sync (sync_revenue_source) still imports the sale.
  • "This site and mode already has a source for this provider". One Paddle source per site and mode. Find it with get_revenue_sources.
  • 429 Too Many Requests. Paddle allows 240 requests per minute per IP and blocks for 60 seconds when exceeded (rate limiting). Fondoo budgets 120 per minute.

Limits, data and security

  • What Fondoo stores: the API key and destination secret, encrypted, never shown again. From Paddle it keeps transaction and refund amounts, subscription status, and customer IDs and emails.
  • Rotate: make a new key in Paddle, then rotate_connection_key({connectionId}). Paddle also offers a Rotatable option when you create a key. It can't be changed later.
  • Disconnect: disconnect_revenue_source({sourceId}) stops the feed (imported data stays). delete_connection({connectionId}) removes the stored key. Then revoke the key and delete the destination in Paddle.
  • Dashboard links use observed Paddle routes that Paddle doesn't document. A link may open a general page. This may differ for your account.