JoomInvoice Payments - Setup Stripe Webhook

This guide walks you through setting up Stripe payments in JoomInvoice so your customers can pay invoices online with credit/debit cards.

Prerequisites

Before you begin, ensure you have:

• Stripe Account: Create a free account at stripe.com if you don't have one
• JoomInvoice Component: Installed and working on your Joomla site
• SSL Certificate: Your site must use HTTPS (required by Stripe)
• Stripe Payment Plugin: The "JoomInvoice - Payment - Stripe" plugin must be installed

Step 1: Get Your Stripe API Keys

1. Log in to your Stripe Dashboard
2. Navigate to Developers → API Keys

3. You'll see two sets of keys:

   • Test keys (prefixed with pk_test_ and sk_test_) - Use these for testing
   • Live keys (prefixed with pk_live_ and sk_live_) - Use these for real payments

4. Copy the following keys (you'll need them for plugin configuration):

   • Publishable key (pk_test_... or pk_live_...)
   • Secret key (sk_test_... or sk_live_...)

Security Note: Never share your Secret key publicly. Keep it confidential.

Step 2: Enable the Stripe Plugin

1. In Joomla Administrator, go to Extensions → Plugins
2. Search for "stripe" or "JoomInvoice - Payment - Stripe"
3. Click on the plugin name to open its settings
4. Set Status to Enabled

Step 3: Configure Plugin Settings

In the plugin configuration, set the following options:

Mode

• Test: Use for development and testing (recommended to start)
• Live: Use for real payments in production

API Keys

For Test Mode:

• Test Secret key: Enter your sk_test_... key
• Test Publishable key: Enter your pk_test_... key

For Live Mode:

• Secret key: Enter your sk_live_... key
• Publishable key: Enter your pk_live_... key

Webhooks (Optional but Recommended)

• Enable Webhooks: Set to "Yes" for more reliable payment tracking
• Webhook secret: Enter the signing secret from Stripe (see Step 4)

Additional Options

• Description text: The message shown above the payment button (default: "Click on the button to pay with Stripe")
• Require billing address: Set to "Yes" to collect customer billing address during checkout

Click Save & Close when done.

Step 4: Set Up Webhooks (Recommended)

Webhooks provide reliable payment confirmation, especially if a customer closes their browser after payment.

Create the Webhook in Stripe

1. Go to Stripe Dashboard → Developers → Workbench (or press W on your keyboard to open Workbench directly) → Webhooks
2. Click Add endpoint
3. Enter your Endpoint URL:

https://www.yourwebsite.com/index.php?option=com_joominvoice&task=process_payment&ptype=payment_stripe&paction=webhook

Important: Replace www.yourwebsite.com with your actual domain.

1. Under Events to send, select:

   • checkout.session.completed

2. Click Add endpoint

Get the Webhook Signing Secret

1. After creating the endpoint, click on it to view details
2. Under Signing secret, click Reveal to see the secret (starts with whsec_)
3. Copy this secret and paste it into the Webhook secret field in the plugin settings

Webhook URL Requirements

To avoid 303 redirect errors:

• Use HTTPS (required by Stripe)
• Ensure www vs non-www matches your site's canonical URL
• Do not add trailing slashes or extra parameters
• The URL must be publicly accessible

Step 5: Test Your Setup

Use Test Mode First

1. Ensure the plugin is set to Test mode
2. Create a test invoice in JoomInvoice
3. View the invoice in the frontend and click the Stripe payment button
4. Use Stripe's test card numbers:

Use any future expiry date, any 3-digit CVC, and any postal code.

Verify the Payment Flow

1. Complete a test payment with 4242 4242 4242 4242
2. Check that the invoice status updates to "Paid" in JoomInvoice
3. Verify the payment appears in your Stripe Dashboard under Payments

Step 6: Go Live

Once testing is complete:

1. In the plugin settings, change Mode from "Test" to "Live"
2. Enter your Live Secret key and Live Publishable key
3. If using webhooks, create a new webhook endpoint for live mode:
   • Stripe requires separate webhooks for test and live modes
   • Use the same endpoint URL
   • Copy the new webhook signing secret to the plugin
4. Save the plugin settings
5. Test with a small real transaction to confirm everything works

Troubleshooting

Payment Not Marked as Paid

Without Webhooks:

• The payment is processed when the customer returns to your site
• If they close the browser before returning, the payment won't be recorded
• Solution: Enable webhooks for reliable payment tracking

With Webhooks:

• Check that the webhook URL is correct and accessible
• Verify the webhook secret matches in both Stripe and the plugin
• Check the Stripe Dashboard → Developers → Workbench → Webhooks for delivery errors

303 Redirect Errors

Common causes:

• URL mismatch between www and non-www versions
• Missing HTTPS
• Extra parameters or trailing slashes in the webhook URL

Solution:

1. Check your site's canonical URL in Joomla Global Configuration
2. Use the exact same format in your webhook URL
3. Ensure your SSL certificate is valid

Invalid Signature Errors in Webhooks

• The webhook signing secret may be incorrect
• Copy the secret again from Stripe Dashboard (Workbench → Webhooks) and update the plugin
• Make sure there are no extra spaces when pasting

"Invalid Session" Warning

• The payment session has expired or was already used
• Ask the customer to initiate the payment again from the invoice page

Security Best Practices

1. Always use HTTPS - Stripe requires secure connections
2. Keep keys secret - Never expose your Secret key in frontend code or public repositories
3. Use webhooks - They provide reliable payment confirmation
4. Test thoroughly - Always test in Test mode before going live
5. Monitor payments - Regularly check your Stripe Dashboard for suspicious activity