`
### 2. Configure in WHMCS Admin
1. Login to WHMCS Admin Area
2. Navigate to: **Setup** > **Payments** > **Payment Gateways**
3. Click on **All Payment Gateways** tab
4. Find and activate **Stripe In-House Payment Gateway**
### 3. Choose Your Mode
#### TEST MODE (Development & Testing)
1. **Enable Test Mode**: Check the "Test Mode" checkbox
2. **Get Test API Keys** from [Stripe Dashboard](https://dashboard.stripe.com/):
- Dashboard ? Developers ? API Keys
- Look for keys starting with `pk_test_` and `sk_test_`
3. **Enter Test Keys**:
- Test Publishable Key: `pk_test_...`
- Test Secret Key: `sk_test_...`
4. Use test card numbers (see below)
#### LIVE MODE (Production)
1. **Disable Test Mode**: Uncheck the "Test Mode" checkbox
2. **Get Live API Keys** from [Stripe Dashboard](https://dashboard.stripe.com/):
- Dashboard ? Developers ? API Keys
- Look for keys starting with `pk_live_` and `sk_live_`
3. **Enter Live Keys**:
- Live Publishable Key: `pk_live_...`
- Live Secret Key: `rk_live_...` (or `sk_live_...`)
4. **ONLY use real credit cards** in live mode!
### 4. Setup Webhooks (Recommended)
1. Login to your [Stripe Dashboard](https://dashboard.stripe.com/)
2. Navigate to: **Developers** > **Webhooks**
3. Click **Add endpoint**
4. Enter webhook URL: `https://yourdomain.com/account/modules/gateways/callback/stripe_inhouse.php`
5. Select events to listen for:
- `payment_intent.succeeded`
- `payment_intent.payment_failed`
- `invoice.payment_succeeded`
- `customer.subscription.deleted`
6. Copy the **Signing secret** and paste it in WHMCS gateway configuration
7. Note: Test and Live mode have separate webhook endpoints!
## How It Works
### One-Time Payments
1. Customer selects Stripe as payment method on invoice
2. Stripe Elements form loads with secure card input
3. Customer enters card details
4. Payment is processed immediately
5. Invoice is marked as paid upon success
### Recurring Subscriptions
1. System detects if invoice is for a recurring service
2. Creates Stripe subscription with customer's payment method
3. Stores subscription ID for future reference
4. Automatic billing happens on renewal dates
5. Webhooks notify WHMCS of successful recurring payments
### Refunds
1. Admin initiates refund from WHMCS invoice
2. Module processes refund through Stripe API
3. Funds returned to customer's original payment method
## File Structure
### stripe_inhouse.php
Main gateway module containing:
- Gateway configuration and metadata
- Payment form generation with Stripe Elements
- Refund functionality
- Subscription cancellation
### callback/stripe_inhouse.php
Payment processing handler for:
- Form submissions with payment method tokens
- One-time payment intent creation
- Recurring subscription creation
- Webhook event processing
- Payment success/failure handling
### stripe_inhouse/StripeAPI.php
Helper class providing:
- Reusable API methods
- Customer management
- Payment intent operations
- Subscription management
- Webhook signature verification
- Amount formatting utilities
## Supported Payment Scenarios
### Scenario 1: New Customer One-Time Payment
- Customer pays single invoice
- Stripe customer account created
- Payment processed immediately
- Invoice marked paid
### Scenario 2: Existing Customer One-Time Payment
- System finds existing Stripe customer
- Payment processed with existing customer ID
- Invoice marked paid
### Scenario 3: New Recurring Service
- Customer purchases hosting/service with recurring billing
- Stripe subscription created
- First payment processed immediately
- Subscription ID stored for future billing
- Automatic renewals handled by Stripe
### Scenario 4: Recurring Payment Renewal
- Stripe automatically charges customer on renewal date
- Webhook notifies WHMCS
- New invoice created and marked paid
- Service renewed automatically
## Testing
### Access Diagnostic Test Tool
Visit: `https://yourdomain.com/account/modules/gateways/stripe_inhouse/test.php`
This will show you:
- ? Current mode (TEST or LIVE)
- ? API key configuration status
- ? Webhook configuration
- ? Test card numbers for your mode
- ? Troubleshooting guide
### Test Mode (Development)
Enable **TEST MODE** in gateway configuration and use Stripe test cards:
**Successful Payment:**
- Card: `4242 4242 4242 4242`
- Expiry: Any future date (MM/YY)
- CVC: Any 3 digits
**Failed Payment:**
- Card: `4000 0000 0000 0002`
- Expiry: Any future date (MM/YY)
- CVC: Any 3 digits
**Requires Authentication:**
- Card: `4000 0025 0000 3155`
- Expiry: Any future date (MM/YY)
- CVC: Any 3 digits
### Live Mode (Production)
**IMPORTANT:**
- ? Do NOT use test cards with LIVE API keys
- ? Do NOT enable LIVE MODE until you're ready for production
- ? Always test thoroughly in TEST MODE first
- ? Only disable TEST MODE when ready to accept real payments
### Common Test Issues & Solutions
**Issue:** "Your card was declined. Your request was in live mode, but used a known test card."
- **Solution:** You're mixing test cards with live API keys
- Make sure TEST MODE is ENABLED for testing
- Use test API keys (starting with `pk_test_` and `sk_test_`)
- Never use test cards in LIVE MODE
**Issue:** Payment form not appearing
- Check browser console for JavaScript errors
- Verify API keys are correctly configured
- Ensure HTTPS/SSL is enabled
- Check that Stripe.js is loading
**Issue:** API errors about invalid keys
- Confirm you're using the correct key format:
- TEST: `pk_test_...` and `sk_test_...`
- LIVE: `pk_live_...` and `sk_live_...` (or `rk_live_...`)
- Verify keys haven't been revoked in Stripe Dashboard
- Check keys are copied completely (no extra spaces)
### Test Webhooks
Use Stripe CLI to forward webhooks to localhost:
```bash
stripe listen --forward-to http://localhost/account/modules/gateways/callback/stripe_inhouse.php
```
### Test Mode - Old Documentation
~~Tick to enable test mode (use test API keys)~~
~~Most modules install in under 15 minutes!~~
## Security Features
1. **PCI Compliance**: Card data never touches your server
2. **Stripe Elements**: Secure iframe-based card input
3. **Webhook Signatures**: Verify authentic Stripe requests
4. **HTTPS Required**: SSL certificate required for production
5. **API Key Security**: Secret keys stored encrypted in WHMCS
## Troubleshooting
### Payment Not Processing
- Check API keys are correct (publishable and secret)
- Verify webhook URL is accessible
- Check WHMCS system activity log for errors
- Review Stripe Dashboard for payment attempts
### Webhooks Not Working
- Verify webhook secret is configured
- Check webhook URL is publicly accessible
- Review Stripe webhook logs in dashboard
- Ensure events are selected in webhook settings
### Recurring Payments Failing
- Verify customer has valid payment method
- Check subscription is active in Stripe Dashboard
- Review webhook event logs
- Confirm subscription ID is stored in WHMCS
## Support
For technical support or custom development:
- Email: info@hiredhosting.com
- Website: https://hiredhosting.com
## License
Copyright (c) 2025 Hired Hosting. All rights reserved.
## Changelog
### Version 1.0.0 (2025-10-27)
- Initial release
- One-time payment support
- Recurring subscription support
- Refund functionality
- Webhook integration
- Stripe Elements integration
