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

Connect PayPal to Fondoo

Live5 min readUpdated

If customers pay you through PayPal, this connection lets Fondoo see those payments, refunds and subscriptions. Your AI agent can then include PayPal in your revenue reports, credit sales to the visits that led to them, and keep subscribers' plans up to date. Fondoo only reads. It cannot charge, refund or cancel.

What Fondoo can do with it

Five read-only actions, used through connector_action:

  • transactions.pull: completed payments and refunds from PayPal Transaction Search, read in 31-day windows.
  • subscriptions.pull: PayPal subscription status (active, past due, cancelled).
  • webhooks.verify: asks PayPal's own API whether a webhook delivery is genuine.
  • webhooks.parse: reads payment, refund and subscription webhook events.
  • dashboard.link: a link to the transaction or subscription in PayPal for a person to open.

There is no customer list, because PayPal has no customer directory API.

After you bind the connection with connect_revenue_source, Fondoo imports payments as orders and analytics conversions. Subscriptions become entitlements that can update a customer's plan in your app.

What needs your approval: an agent binding a live source or changing its product map needs the owner's approval. Reads never do. Refunds and cancellations stay in PayPal.

Before you start

  • A PayPal Business account (or a verified Premier account) for live data (go live). Sign in to developer.paypal.com with the same login.
  • Sandbox or live. Sandbox apps only see sandbox payments. Make a live app for real sales.
  • Live mode in Fondoo needs a paid Fondoo plan. Test mode works on any plan.
  • Expect a delay. PayPal can take up to three hours to list a new transaction in Transaction Search (Transaction Search). Webhooks fill that gap.

Step by step: get your credentials

  1. Sign in to the PayPal Developer Dashboard.
  2. Open Apps & Credentials. Use the Sandbox / Live toggle to pick the environment (REST getting started).
  3. Under REST API apps, click Create App. Name it Fondoo and create it. You can also use an existing app, but a separate app is easier to revoke.
  4. On the app page, copy the Client ID and the Secret.
  5. In the app's settings, turn on Transaction Search and save. Fondoo needs it to read payments. PayPal's own page for this step was offline when this guide was written, so the label may differ. If the option is missing, contact PayPal support. A new permission can take several hours to apply to an app that is already in use.
  6. If you sell subscriptions, make sure the app can use the Subscriptions API. The permission Fondoo checks for is https://uri.paypal.com/services/subscriptions. Transaction Search is https://uri.paypal.com/services/reporting/search/read.

What goes where:

Fondoo fieldWhat to paste
PayPal REST app client ID (clientId)the Client ID
PayPal REST app secret (clientSecret)the Secret
Environment (production or sandbox) (environment)sandbox for a sandbox app. Leave empty for live
PayPal webhook ID (webhookId)leave empty for now. Add it in the Webhooks step

Connect it in Fondoo

In the dashboard

  1. Open Connections.
  2. Under Available, find PayPal (in Payments) and click Use a key.
  3. Click Open secure key entry (single use, expires after 15 minutes). Paste the Client ID, Secret and environment, then save.
  4. Click Check connection on the new card.

By asking your agent

Example prompt:

Connect my PayPal business account to my site so you can track PayPal sales. Send me a secure link for the credentials.

The agent runs:

add_connection_key({ provider: "paypal", siteId: "<site id>" })
test_connection({ connectionId: "<id>" })
connect_revenue_source({ siteId: "<site id>", connectionId: "<id>", mode: "live",
  productMap: { "<PayPal plan ID, P-...>": "pro" } })   // plan ID or item code → Fondoo plan
sync_revenue_source({ sourceId: "<source id>" })

For a help link only: connect_service({provider:"paypal", siteId}) (signed, 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":"paypal","siteId":"<site id>"}.

Webhooks

  1. Copy the webhookUrl returned by connect_revenue_source (or get_revenue_sources). It looks like https://<Fondoo API host>/webhooks/revenue/<connectionId>.
  2. In the Developer Dashboard, open the same app and find its webhooks section. Add a webhook with that URL (webhooks).
  3. Choose these event types (event names):
    • PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED
    • PAYMENT.SALE.COMPLETED, PAYMENT.SALE.REFUNDED
    • BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED, BILLING.SUBSCRIPTION.PAYMENT.FAILED
  4. Save, then copy the Webhook ID that PayPal shows for the URL.
  5. In Fondoo, run rotate_connection_key({connectionId}). On the secure page, paste the Client ID, Secret and environment again, plus the Webhook ID. The page replaces all fields together.

PayPal webhooks aren't signed with a shared secret. Fondoo sends each delivery back to PayPal's verify-webhook-signature API, together with your Webhook ID, and only accepts it if PayPal confirms it. Fondoo also refuses deliveries more than 5 minutes old. If one is refused, the next Transaction Search sync still records the payment.

Attribution: to credit a sale to a visit, set the PayPal order's custom_id (or invoice_id) to visit_id=<uuid>;external_user_id=<id>, or the same as JSON. The limit is 127 characters.

Test that it works

  1. Run test_connection. It gets a PayPal token and reads one day of Transaction Search. A pass confirms Transaction Search works. Subscriptions and webhook verification stay "unknown" until first used.
  2. Run sync_revenue_source({sourceId}) and check get_revenue_sources({siteId}) for lastSyncAt and no lastError.
  3. In sandbox, make a payment with a sandbox buyer account. The webhook event should arrive quickly. Transaction Search may take up to three hours to show it.

PayPal's webhook simulator events cannot be verified through the API, so use a real sandbox payment for testing.

Troubleshooting

  • 401 invalid_client. The Client ID or Secret is wrong, or the app is in the other environment. Sandbox apps need Environment set to sandbox.
  • 403 (not authorized) on Transaction Search. Transaction Search isn't enabled for the app yet. Turn it on and wait. It can take hours to apply to an app already in use.
  • Recent sales missing. Transaction Search can lag by up to three hours. Set up the webhook for faster updates.
  • Subscriptions don't load. Fondoo uses PayPal's list-subscriptions call. It is documented, but it has not been tested on a live account, so this may differ for yours. If PayPal rejects it, pass subscriptionIds (for example from BILLING.SUBSCRIPTION.* webhooks) to subscriptions.pull.
  • Webhooks rejected. Check the Webhook ID belongs to this exact URL and app. Simulator events always fail verification.
  • 429 RATE_LIMIT_REACHED. PayPal doesn't publish fixed limits (rate limiting). Fondoo keeps to 30 requests per minute. Wait and retry.

Limits, data and security

  • What Fondoo stores: the client secret, encrypted. The client ID, webhook ID and environment are stored as plain identifiers. From PayPal it keeps payment and refund amounts, subscription status, and the payer's ID and email when PayPal includes them.
  • Rotate: in the app page, generate a new secret. Then run rotate_connection_key({connectionId}) and remove the old secret in PayPal.
  • Disconnect: disconnect_revenue_source({sourceId}) stops the feed (imported data stays). delete_connection({connectionId}) removes the stored credentials. Then delete the app or its webhook in PayPal.
  • Fondoo matches refunds to payments using PayPal behaviour that is observed but not documented (refund reference IDs and amount signs). Dashboard links use observed PayPal URL patterns. This may differ for your account.