How to integrate stripe php into joomla

In 2026, integrating Stripe into Joomla remains one of the most practical ways to add robust subscription and payment handling to your Joomla CMS based site. This guide walks through building a custom Joomla plugin that uses the Stripe PHP library to handle payments, creates a subscription via the Stripe API, and ties that subscription to a Joomla user account.

The process involves three main stages: installing the Stripe CLI for command-line access to your Stripe integration, pulling in the Stripe PHP server-side SDK via Composer, and wiring the SDK into Joomla's plugin framework. The Stripe PHP SDK has matured considerably, and Stripe's API surface is now more consistent and better documented than ever — making this a realistic DIY project for developers comfortable with PHP and Joomla extension development.

Note – This integration requires a working knowledge of terminal commands, PHP, and the Joomla CMS plugin framework. Joomla 5.x is assumed throughout, though the plugin structure is broadly compatible with Joomla 4.x and Joomla 6.x.

Set up the Stripe Command Line Interface (CLI)

Install the CLI

Install the Stripe CLI from the command line using your operating system's preferred package manager or by downloading a versioned archive from the Stripe CLI documentation page.

• On macOS, the simplest route is Homebrew:

% brew install stripe/stripe-cli/stripe

• On Linux, Homebrew also works, or you can use the official apt/yum repositories documented on Stripe's site.
• On Windows, the CLI is available via Scoop or as a direct download.

Once installed, authenticate against your Stripe account. This opens a browser window and generates a set of restricted keys tied to your account:

% stripe login
Your pairing code is: xxxx-xxxxx-xxxxxx-xxxxxx
This pairing code verifies your authentication with Stripe.
Press Enter to open the browser or visit https://dashboard.stripe.com/stripecli/confirm_auth?t=xxxxxxxxxxxxxxxxxxxxxxx (^C to quit)
> Done! The Stripe CLI is configured with account id acct_xxxxxxxxxxxxxxxxx

Please note: this key will expire after 90 days, at which point you'll need to re-authenticate.
%

The CLI is now your primary tool for local webhook forwarding, triggering test events, and inspecting API calls in real time — all without leaving the terminal. If you want to go deeper, Stripe's CLI and API keys documentation covers the full range of capabilities.

One significant CLI improvement worth noting: the stripe listen command now supports automatic webhook secret rotation, so your local development environment stays in sync with your Stripe account without manual key updates. This is especially useful when you are iterating on subscription event handling in your plugin.

Install the Stripe PHP Library

With the CLI configured, install the Stripe PHP library into your plugin directory using Composer, PHP's standard dependency manager. Create a folder for your plugin and run:

% composer require stripe/stripe-php

Composer downloads the library into a vendor directory and generates a composer.json lockfile. Your directory structure will look like this:

├── composer.json
├── composer.lock
└── vendor
    ├── autoload.php
    ├── composer
    └── stripe

The current Stripe PHP SDK (v13.x as of 2026) ships with full PHP 8.2 and 8.3 compatibility, typed properties throughout, and first-class support for Stripe's newer APIs including the Payment Element and the Checkout Session model. If you are upgrading an older integration, review Stripe's migration guide — the v10+ releases introduced breaking changes to how resources are instantiated.

Create the Joomla Plugin Manifest File

The manifest is an XML file that tells Joomla how to install the plugin, what files it includes, and what configuration parameters it exposes. Create a file called payment.xml in your yourpluginname/ folder. At minimum the manifest should declare the plugin type, group, version, and author metadata, and define form fields for the Stripe Secret Key and Publishable Key so they can be stored securely in Joomla's plugin parameters rather than hard-coded in PHP.

In Joomla 5.x the manifest format is unchanged from Joomla 4.x, so existing manifests are portable. Declare your plugin in the payment group if you are building a payment handler, or in a custom group if the plugin serves a broader purpose within your extension package.

Create the Joomla Plugin PHP File

Create payment.php — the file where your plugin logic lives. This code loads the Stripe library via Composer's autoloader and handles the payment flow.

• The plugin hooks into an appropriate Joomla event — in Joomla 5.x the preferred approach uses the event-based dispatcher and typed event classes rather than the older onAfterInitialise hook, which is now deprecated in favour of the new event architecture introduced in Joomla 4.2 and formalised in Joomla 5.
• It checks whether a payment action has been requested via the current input.
• The processStripePayment() function initialises Stripe with your secret key, creates a PaymentIntent (or a Checkout Session if you prefer Stripe's hosted UI), and returns the clientSecret needed to complete the payment on the frontend.
• API keys are retrieved securely from plugin parameters using $this->params->get() — never hard-code credentials in source files.

If you are building subscription billing rather than one-off payments, you will also need to create a Customer object in Stripe, attach a PaymentMethod, and then create a Subscription referencing your Price ID. Stripe's subscription model has been stable for several years, but the recommended flow now uses the Payment Element on the frontend rather than the older Card Element, as it handles 3D Secure authentication and a wider range of payment methods automatically.

Add Stripe to the Joomla Frontend

You need to add the Stripe payment form and JavaScript to your Joomla site's frontend so users can complete a payment. For prototyping, a Custom HTML module is the quickest route. For a production-grade extension you will want a dedicated installable module packaged alongside the plugin — in which case wrap both in a Joomla package extension, which lets you install multiple extensions in a single operation.

When creating your Custom HTML module:

• Give the module a clear name so you can identify it in the module manager.
• Assign it to a module position that is not a template position — you will be loading it directly into an article.
• Check the Menu Assignment tab and ensure the module is set to display on the relevant pages. This is the most common reason a module silently fails to appear.

Stripe's Payment Element is now the recommended frontend component. It replaces the older Card Element and renders a single, adaptive UI that supports cards, wallets, and local payment methods — all determined automatically based on the customer's location and your Stripe account settings. Integrating it requires loading Stripe.js from Stripe's CDN, initialising it with your publishable key, and mounting the Payment Element into a DOM node in your module's HTML output.

Load the Module into an Article

Make sure the Content – Load Modules plugin is enabled before you try to embed your module in an article.

• Go to Extensions > Plugins and search for "Load Modules".
• Confirm it is enabled — enable it if not.

• Use the shortcode in your article body, replacing 123 with your module's ID, to embed the payment form inline.
• In Joomla 5.x the syntax {loadmoduleid} is the canonical form — the older brace-style variants still work but the ID-based version is more reliable across editor configurations.

Your Stripe Payment Module Should Look Like This

Package and Install the Plugin

Joomla requires a specific archive structure to install an extension via the admin console. Navigate to the parent directory of your plugin folder and create a ZIP archive:

zip -r foldername.zip pluginname/

The -r flag recurses into all subdirectories. Make sure the manifest XML file sits at the top level of the archive — Joomla reads it first to understand what it is installing. The archive should contain:

yourpluginname/payment.php
yourpluginname/payment.xml
yourpluginname/vendor/stripe/

Once the ZIP is ready, install it via Extensions > Manage > Install in the Joomla admin panel. A green success banner confirms the installation completed without errors.

• Find the plugin in Extensions > Plugins by searching for "stripe".
• Open the plugin record and enter your API keys in the configuration fields.
• Enable the plugin and save.
• Visit the frontend, complete the payment form, and verify the flow end-to-end.

Setting Up Credentials for Testing

Stripe's test mode lets you exercise every part of your integration — successful payments, card declines, 3D Secure challenges, subscription renewals, and webhook events — without processing real money. Stripe also offers sandboxes, which are fully isolated environments with their own set of API keys and data, useful for staging environments or parallel development streams. Sandboxes are worth exploring once your basic integration is stable, though they are beyond the scope of this guide.

To get started with testing:

• Log in to your Stripe Dashboard and switch the toggle to Test mode.
• Copy your test Publishable key and Secret key from the API keys section.
• Paste them into your plugin's configuration parameters and save.
• Create a test subscription product and price in the Dashboard — you will need the Price ID in your subscription form.
• Optionally configure multiple subscription tiers to test plan switching logic.
• Use Stripe's built-in test card numbers (such as 4242 4242 4242 4242 for a successful payment) to simulate transactions.

Use stripe listen --forward-to localhost/index.php?option=com_yourcomponent during local development to forward webhook events from Stripe to your local Joomla instance. This lets you test subscription lifecycle events — renewals, cancellations, payment failures — without deploying to a public server.

Skip the Build: Use a Ready-Made Extension

If building and maintaining a custom plugin from scratch is more than your project warrants, there is a ready-made solution that handles all of the above out of the box. Payments via Stripe for Joomla, our own extension is available from the Joomla Extensions Directory and covers the full subscription and payment flow — including webhook handling, user account linking, and multi-tier subscription support — without requiring you to write or maintain any custom PHP.

• Install directly from the Joomla Extensions Directory listing.
• Or purchase and download directly from Multizone.

For teams who want full control over the codebase, the DIY route described in this guide remains the right choice. For everyone else, the extension removes a significant amount of complexity and keeps pace with Stripe API changes without requiring developer intervention on every update.