Back to documentation

API reference

HappyClaw exposes external checkout so your application can send users here to pay; when checkout completes, our webhook notifies your backend to apply premium access (or balance updates on your side). Integration questions? Contact us.

Redirect URL (query parameters)

Send the user to /external-checkout with:

  • package — internal tier id (e.g. credit120)
  • user_id — stable id in your system (string)
  • website_a_url — base URL of your app (used for return link and webhook target derivation)
https://your-happyclaw-domain.com/external-checkout?package=credit120&user_id=USER_ID&website_a_url=https%3A%2F%2Fyour-app.com

Test helpers

GET /api/external-checkout/test returns a ready-made URL and environment checklist.

POST /api/external-checkout/test with JSON { "userId", "websiteAUrl", "packageId" } returns checkoutUrl.

Webhook → your app API

On checkout.session.completed, when metadata.source is external_checkout, HappyClaw POSTs to:

POST {WEBSITE_A_API_BASE_URL || websiteAUrl}/api/user/credits

Headers: X-Webhook-Signature (HMAC-SHA256 of body with WEBSITE_A_WEBHOOK_SECRET), X-Idempotency-Key. Body JSON: userId, credits (numeric allocation), packageId, timestamp.

Environment variables

  • NEXT_PUBLIC_APP_URL — public origin of this HappyClaw deployment
  • NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
  • WEBSITE_A_WEBHOOK_SECRET — shared secret with your app for HMAC verification
  • WEBSITE_A_API_BASE_URL (optional) — override base URL for the webhook endpoint (e.g. /api/user/credits)
  • STRIPE_PRICE_* — per-package price ids (see lib/stripe-config.ts)