{"id":16773,"library":"better-auth-streampay","title":"Better Auth StreamPay Plugin","description":"better-auth-streampay is a community-developed plugin designed to seamlessly integrate StreamPay payment and subscription functionalities into applications utilizing the `better-auth` authentication framework. Currently at version 1.0.0, this package provides robust features such as checkout integration with lazy consumer creation, a comprehensive customer portal for managing subscriptions and invoices, and secure handling of StreamPay webhooks with HMAC-SHA256 signature verification. It also allows for optional eager consumer provisioning upon user signup and ensures consumer data synchronization on user updates or deletions. The plugin differentiates itself by offering a tightly coupled solution specifically for StreamPay users within the Better Auth ecosystem, providing distinct sub-plugins for various functionalities like `checkout`, `portal`, `subscriptions`, and `webhooks` for modular integration. While there's no fixed release cadence, being a v1.0.0 community plugin, updates are typically driven by feature development and bug fixes.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Genie-sa/better-auth-streampay","tags":["javascript","better-auth","better-auth-plugin","streampay","stream-pay","payments","subscriptions","saudi-arabia","fintech","typescript"],"install":[{"cmd":"npm install better-auth-streampay","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-streampay","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-streampay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for direct interaction with the StreamPay API client.","package":"@streamsdk/typescript","optional":false},{"reason":"The foundational authentication framework that this plugin extends and integrates with.","package":"better-auth","optional":false},{"reason":"Used internally for schema validation, ensuring data integrity for configurations and payloads.","package":"zod","optional":false}],"imports":[{"note":"The primary server-side plugin factory, used within `betterAuth` configuration. ESM-only due to Better Auth's modern tooling.","wrong":"const streampay = require('better-auth-streampay');","symbol":"streampay","correct":"import { streampay } from 'better-auth-streampay';"},{"note":"Named import for a sub-plugin used to compose functionality within `streampay`. Other sub-plugins like `portal`, `subscriptions`, and `webhooks` are imported similarly.","wrong":"import checkout from 'better-auth-streampay/checkout';","symbol":"checkout","correct":"import { checkout } from 'better-auth-streampay';"},{"note":"The client-side counterpart plugin for `better-auth/react`, imported from a dedicated client entry point.","wrong":"import { streampayClient } from 'better-auth-streampay';","symbol":"streampayClient","correct":"import { streampayClient } from 'better-auth-streampay/client';"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\";\nimport StreamSDK from \"@streamsdk/typescript\";\nimport {\n  streampay,\n  checkout,\n  portal,\n  subscriptions,\n  webhooks,\n} from \"better-auth-streampay\";\n\n// Ensure these environment variables are set in your .env file\n// STREAMPAY_API_KEY=your_base64_encoded_api_key:api_secret\n// STREAMPAY_WEBHOOK_SECRET=your_webhook_secret (if using webhooks)\n// BETTER_AUTH_SECRET=your_session_signing_secret (min 32 chars)\n// BETTER_AUTH_URL=your_app_public_url (required in prod)\n\nconst streamPayClient = StreamSDK.init(process.env.STREAMPAY_API_KEY ?? '');\n\nconst auth = betterAuth({\n  plugins: [\n    streampay({\n      client: streamPayClient,\n      // createConsumerOnSignUp defaults to false; set to `true` to provision\n      // a StreamPay consumer at signup instead of lazily on first payment.\n      use: [\n        checkout({\n          products: [\n            { productId: \"aaaa-bbbb-cccc-dddd\", slug: \"pro\" }\n          ],\n          successUrl: \"/dashboard?checkout=success\",\n          failureUrl: \"/dashboard?checkout=failure\",\n          authenticatedUsersOnly: true,\n        }),\n        portal(),\n        subscriptions(),\n        webhooks({\n          secret: process.env.STREAMPAY_WEBHOOK_SECRET ?? '',\n          onPaymentSucceeded: async (payload) => {\n            console.log('Payment Succeeded:', payload);\n            // Implement logic to provision user access or update status\n          },\n          onSubscriptionCanceled: async (payload) => {\n            console.log('Subscription Canceled:', payload);\n            // Implement logic to revoke user access or update status\n          },\n        }),\n      ],\n    }),\n  ],\n});\n\nconsole.log('Better Auth with StreamPay plugin initialized successfully.');","lang":"typescript","description":"This quickstart demonstrates the server-side setup of the `better-auth-streampay` plugin, configuring the core `streampay` plugin with its sub-plugins: `checkout`, `portal`, `subscriptions`, and `webhooks`. It initializes the StreamPay SDK client and integrates webhook handlers for payment success and subscription cancellation events."},"warnings":[{"fix":"Be aware of the support channel distinction. For core StreamPay service issues, contact StreamPay support. For plugin integration issues, open an issue on the plugin's GitHub repository.","message":"This is a community-developed plugin and is NOT officially affiliated with Stream or StreamPay. For plugin-specific bugs or feature requests, use the GitHub issue tracker for this repository. Direct StreamPay support channels will not handle issues related to this plugin.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all peer dependencies are installed correctly and meet the specified version ranges, e.g., `pnpm add better-auth-streampay @streamsdk/typescript better-auth zod`.","message":"The plugin has strict peer dependency requirements for `@streamsdk/typescript`, `better-auth`, and `zod`. Failing to install these or using incompatible versions will lead to runtime errors or build failures.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Define all required environment variables in your `.env` file or deployment configuration, ensuring `STREAMPAY_API_KEY` is correctly Base64-encoded.","message":"Critical environment variables must be configured for the plugin to function. `STREAMPAY_API_KEY` (a Base64-encoded `apiKey:apiSecret` pair), `BETTER_AUTH_SECRET`, and `BETTER_AUTH_URL` are generally required, with `STREAMPAY_WEBHOOK_SECRET` being necessary for webhook functionality.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Execute the appropriate database migration command for your ORM/CLI after installation (e.g., `npx @better-auth/cli migrate`, `npx drizzle-kit generate && npx drizzle-kit migrate`, or `npx prisma migrate dev`).","message":"The plugin adds a `streampayConsumerId` column to the `user` table. A database migration MUST be run after installing this plugin, regardless of whether you are using Drizzle, Prisma, or the Better Auth CLI for migrations.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add `STREAMPAY_API_KEY=your_base64_encoded_api_key` to your `.env` file or environment variables.","cause":"The `STREAMPAY_API_KEY` environment variable, which holds the Base64-encoded StreamPay API key, is not set.","error":"Error: Missing required environment variable: STREAMPAY_API_KEY"},{"fix":"Ensure `@streamsdk/typescript` is installed via `pnpm add @streamsdk/typescript` and imported correctly as `import StreamSDK from '@streamsdk/typescript';`.","cause":"The `@streamsdk/typescript` peer dependency is either not installed or improperly imported/configured.","error":"TypeError: Cannot read properties of undefined (reading 'init') at StreamSDK"},{"fix":"Ensure sub-plugins are correctly composed within the `use` array: `streampay({ client: streamPayClient, use: [checkout(...), portal()] })`.","cause":"The sub-plugins (e.g., `checkout`, `portal`) are not being passed as an array to the `use` property of the `streampay` plugin factory.","error":"TypeError: streampay.use is not a function"},{"fix":"Verify that `STREAMPAY_WEBHOOK_SECRET` in your environment exactly matches the webhook secret configured in your StreamPay dashboard.","cause":"The `STREAMPAY_WEBHOOK_SECRET` environment variable is either missing, incorrect, or the webhook payload has been tampered with.","error":"Error: HMAC-SHA256 signature verification failed for StreamPay webhook"}],"ecosystem":"npm","meta_description":null}