Troubleshooting Payments and Apps

Purpose and Scope

Use this page when payment features or third-party app integrations appear unavailable after a self-hosted Cal.diy installation. The most common pattern is not a runtime crash, but an integration that remains hidden, disabled, or unable to complete OAuth because its required credentials were never added to the environment files or its provider dashboard callback URL does not match the deployed Cal.diy URL. The app documentation in this repository treats Stripe, Google, Daily, and HubSpot as provider-specific setup flows, while the documentation metadata groups them under the Apps section for self-hosters who are configuring integrations after installation.

Sources: apps/docs/content/apps/stripe.mdx, apps/docs/content/apps/google.mdx, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/hubspot.mdx, apps/docs/content/apps/_meta.ts

The troubleshooting approach is therefore credential-first and URL-first. Before changing application code, confirm that the provider account exists, the correct provider dashboard feature is enabled, the expected environment variable names are populated, and every redirect or webhook endpoint uses the public Cal.diy URL for the instance you are testing. Stripe has the broadest checklist because it uses public and private API keys, Connect OAuth, a client identifier, and a webhook secret. Google and HubSpot depend on OAuth callback configuration, while Daily primarily depends on an API key and an optional scale-plan flag.

Sources: apps/docs/content/apps/stripe.mdx, apps/docs/content/apps/google.mdx, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/hubspot.mdx

Relevant Source Files

apps/docs/content/apps/stripe.mdx - Defines the Stripe setup sequence, including API keys, Connect OAuth, payment callback URL, webhook URL, webhook events, and required Stripe environment variables.
apps/docs/content/_meta.ts - Places Apps in the main documentation navigation beside installation, migrations, upgrades, Docker, and deployments, which signals that integration setup is part of the self-hosting path.
apps/docs/content/apps/_meta.ts - Lists the app documentation entries, including Google, Daily, HubSpot, Stripe, Sendgrid, Twilio, Microsoft, Zoom, and Zoho.
apps/docs/content/apps/daily.mdx - Documents the Daily credential fields used for video meetings and the optional scale-plan setting.
apps/docs/content/apps/google.mdx - Documents Google Calendar API enablement, OAuth consent, required calendar scopes, redirect URIs, credential JSON placement, and app-store reseeding.
apps/docs/content/apps/hubspot.mdx - Documents HubSpot app creation, client ID and secret storage, OAuth callback URL, contact scopes, and expected booking-to-meeting behavior.

Diagnostic Model

Start by classifying the failure. If paid events or app-store payment options are missing, inspect Stripe configuration first. If a provider button appears but returns to an error page, compare the OAuth callback registered in the provider dashboard with the callback path documented for that app. If a provider was recently added but is absent from the Cal.diy app store, refresh or reseed the app-store data where the relevant guide calls for it. This model keeps troubleshooting close to the documented setup steps instead of treating every integration problem as a generic deployment issue.

Sources: apps/docs/content/apps/stripe.mdx, apps/docs/content/apps/google.mdx

The second diagnostic step is to separate root application environment from app-store environment. The Stripe troubleshooting guidance notes that payment availability can depend on variables split across the root environment file and the app-store environment file. The Google guide also asks self-hosters to place the downloaded OAuth client JSON into both environment locations under the same credential key. When an integration works in one part of the product but is unavailable in another, this split is a strong clue that one environment file was updated while the other was left stale.

Sources: apps/docs/content/apps/stripe.mdx, apps/docs/content/apps/google.mdx

Stripe Payment Checklist

Stripe requires a complete provider-side and Cal.diy-side setup. In the Stripe dashboard, create or open an account, use test mode when testing, save the public token and private secret key, enable OAuth for Standard Accounts in Connect settings, add the payment callback URL, create the connected-application webhook, choose all payment intent and setup intent events, and copy the webhook signing secret. In Cal.diy, map those values to the documented environment variable names exactly. If any of these values are empty, payment-related features can be unavailable even though the rest of the scheduling application continues to run.

Sources: apps/docs/content/apps/stripe.mdx

NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_...
STRIPE_PRIVATE_KEY=sk_test_...
STRIPE_CLIENT_ID=ca_...
STRIPE_WEBHOOK_SECRET=whsec_...

Use the deployed Cal.diy base URL when entering Stripe endpoints. The payment OAuth callback path is shown as a route under the application URL, and the webhook path is a separate route for connected application events. A common mistake is to configure one of these paths with a local development host or an old domain after moving the instance. Another common mistake is to create a webhook but omit the documented event families. If the webhook secret is copied from the wrong webhook or environment, Cal.diy cannot verify the incoming payment events correctly.

Sources: apps/docs/content/apps/stripe.mdx

<Cal.diy URL>/api/integrations/stripepayment/callback
<Cal.diy URL>/api/integrations/stripepayment/webhook

App Credential and OAuth Failures

Google Calendar failures usually come from an incomplete Google Cloud setup rather than a Cal.diy-only defect. The documented flow enables the Google Calendar API, configures the OAuth consent screen, adds calendar event and read-only scopes, adds test users where appropriate, creates a web application OAuth client, and registers two authorized redirect URIs. The downloaded client JSON must be copied as the full string into the documented credential key in both environment files. After adding the credentials, the guide instructs self-hosters to repopulate the app store so the Google Calendar integration becomes available.

Sources: apps/docs/content/apps/google.mdx

<Cal.diy URL>/api/integrations/googlecalendar/callback
<Cal.diy URL>/api/auth/callback/google

Daily has a smaller surface area, so troubleshooting is correspondingly direct. Confirm that the Daily account exists, the developer dashboard API key was copied, and the key is present in the documented Daily environment field. If the deployment expects recording or other scale-plan behavior, also confirm that the optional scale-plan variable is set to true only when the Daily account actually has that plan. A missing Daily key can affect video meeting creation, while a mismatched plan flag can make operators expect features that the account or configuration does not provide.

Sources: apps/docs/content/apps/daily.mdx

HubSpot uses a familiar OAuth app pattern. Create a HubSpot developer app, copy the client ID and client secret into the documented environment fields, set the OAuth redirect URL to the Cal.diy HubSpot callback, and grant read and write access for the contacts object scope. If bookings are not appearing as HubSpot meetings for contacts, verify the OAuth app was saved after changing scopes and redirect URLs, then re-authorize the integration. This is especially important after changing the Cal.diy public domain, because OAuth providers compare callback URLs exactly.

Sources: apps/docs/content/apps/hubspot.mdx

Compact Reference

Integration	Required values or provider setup	Callback or endpoint to verify	Troubleshooting signal
Stripe	Public key, private key, Connect OAuth, client ID, webhook secret, payment intent and setup intent webhook events	`<Cal.diy URL>/api/integrations/stripepayment/callback` and `<Cal.diy URL>/api/integrations/stripepayment/webhook`	Paid events or app-store payment integration unavailable
Google Calendar	Calendar API enabled, consent screen, calendar scopes, test users, OAuth client JSON, `GOOGLE_LOGIN_ENABLED=false` when using the documented internal app setup	`<Cal.diy URL>/api/integrations/googlecalendar/callback` and `<Cal.diy URL>/api/auth/callback/google`	OAuth errors, missing calendar app, or stale app-store entry
Daily	Daily API key and optional scale-plan flag	No OAuth callback in the supplied setup guide	Video meeting features unavailable or scale-plan expectations mismatch
HubSpot	Client ID, client secret, contacts read and write scope	`<Cal.diy URL>/api/integrations/hubspot/callback`	Bookings do not create expected HubSpot contact meetings

Next Steps

After correcting credentials, restart the relevant Cal.diy services so the new environment values are loaded. If the integration is app-store backed, follow the app-specific instruction to repopulate the app store when the guide calls for it, as Google does with the database seed command. Then test one provider at a time: connect the app, complete OAuth, create a booking or paid event, and confirm the provider-side record or webhook delivery. For broader context, read the Apps Overview for the provider catalog and the Stripe Payments Integration page for the full payment setup sequence.

Ask a question...