System Requirement
- WHMCS 8.8 through 8.11
- PHP 8.1 with ionCube Loader v13
Installation
1. Download the ZIP File
- Download the ZIP file containing the
stripecheckout.php
andcallback
files.
2. Extract Files
- Extract the ZIP file directly into the following directory:
/modules/gateways/
This will place:
- The
stripecheckout.php
file into the /modules/gateways/ directory. - The
stripecheckoutcallback.php.php
file into the /modules/gateways/callback/ directory automatically.
Configuration
Once the files are uploaded, follow these steps to configure the Stripe Checkout module:
1. Navigate to Payment Gateways Settings:
-
- Log in to your WHMCS Admin Area.
- On the top menu, click on Configuration
- Go to System Settings and then click on Payment Gateways.
2. Visit Apps & Integrations:
- To activate or explore other payment gateway integrations, you can click on the “Visit Apps & Integrations” button.
- This will redirect you to the Apps & Integrations page, where you can find a comprehensive list of payment gateway integrations, including StripeCheckout.
3. Activate Stripe Checkout:
- From the Apps & Integrations page, search for StripeCheckout.
- Once found, click on the Activate button next to it.
4. Configure the Module
In the configuration form, enter the required details:
- Publishable Key: Enter your Stripe Publishable Key from your Stripe dashboard.
- Restricted Key: Enter your Stripe Restricted .
- Webhook Secret: Enter your Stripe Webhook Secret.
Note: The keys can be found in your Stripe Dashboard.
Permissions for Restricted Key
- Charges: Enable Write. This allows your module to create charges for payments and view charge information.
- PaymentIntents: Enable Write. PaymentIntents are a core part of handling payments through Stripe.
- PaymentMethods: Enable Write. This is necessary to manage customer payment methods like cards or other methods supported by Stripe.
- Customers: Enable Write. This allows the system to create and update customer records.
- Checkout Sessions: Enable Write. This is crucial for Stripe Checkout to function, as it involves creating and handling checkout sessions.
- Refunds: Enable Write. This will allow the system to process refunds when requested.
- Webhook Endpoints: Enable Write. Webhooks are important for receiving payment updates from Stripe to your system.
- Tokens: Enable Write. This is necessary to create tokens for payment methods securely.
Webhook Configuration
To ensure payments and refunds are processed correctly, you need to set up webhooks in your Stripe dashboard:
1. Go to Webhooks in Stripe Dashboard
- Log in to your Stripe Dashboard.
- Navigate to Developers > Webhooks.
2. Add a New Webhook Endpoint
- Click Add endpoint.
- In the URL field, enter the following:
https://yourwhmcsdomain.com/modules/gateways/callback/stripecheckoutcallback.php
Replace
yourwhmcsdomain.com
with your actual WHMCS domain.
3. Select Events to Listen
- Choose
checkout.session.completed
to capture successful payments.
4. Save Webhook
- Copy the Webhook Secret provided by Stripe and paste it into the WHMCS module configuration under Webhook Secret.
Stripe Adaptive pricing
To enable Stripe Adaptive Pricing for your Stripe Checkout, you can follow these steps:
Go to the Stripe Dashboard:
1-Log into your Stripe Dashboard and navigate to your payment settings.
2-In the payment settings, you will find the option to enable Adaptive Pricing for both test and live modes.
- Check Country Support:
- Before enabling Adaptive Pricing, make sure that your country supports this feature. You can check the full list of supported countries by visiting the official documentation at Stripe Adaptive Pricing Supported Countries.
- Test Adaptive Pricing:
- Create a test Checkout Session to confirm that pricing is shown in the customer’s local currency and that the feature is working as expected
How to Enable Alipay and Other Payment Methods in Stripe
To offer Alipay, Cash App, or other supported payment methods in your WHMCS Stripe Checkout module:
- Login to Stripe Dashboard:
- Visit the Stripe Dashboard and log in to your account.
- Navigate to Payment Methods Settings:
- Go to Settings in the Dashboard.
- Under Payments select Payment Methods.
- Enable Alipay and Other Payment Methods:
- Look for Alipay, Cash App, and any other supported payment methods.
- Toggle them on to enable these payment options for your customers.
Usage
For Customers:
- During checkout, customers will see the Stripe Checkout option along with support for Card, Alipay, and Cash App.
- Once they click Pay Now, they will be redirected to Stripe’s secure payment page.
- Upon successful payment, customers will be redirected back to the WHMCS invoice page.
For Admins:
- Admins can track payment transactions via the Transactions tab in WHMCS.
- All payment details, including Transaction ID and Amount Paid, are logged for auditing.
Refunds
Refunds can be handled directly through the WHMCS admin area.
How to Issue a Refund:
- Navigate to the Invoice:
- Go to Billing > Invoices and locate the invoice you want to refund.
- Initiate Refund:
- In the invoice, click on the Refund button.
- Enter the refund amount (if it’s a partial refund) and proceed.
Logging:
- All refunds are logged using WHMCS’s
logModuleCall()
for auditing purposes. - Any errors encountered during the refund process will be logged in the Module Log.
Error Handling & Logs
1. Error Messages:
- If a payment or refund fails, a generic error message will be shown to the customer to prevent exposure of internal details.
2. Logs for Debugging:
- Detailed errors (including Stripe API errors) will be logged in WHMCS using
logModuleCall()
. - To view logs, go to Configuration > System Logs > Module Log
Security
1. API Key Security:
- The Secret Key and Webhook Secret are stored securely in WHMCS’s database and are never exposed to users.
2. Input Validation:
- All inputs (invoice ID, amount, transaction ID) are sanitized and validated before processing to prevent security vulnerabilities.
3. HTTPS:
- Ensure your WHMCS installation uses HTTPS for secure communication with Stripe.
Support
If you need help configuring or using the module, please reach out to RackNode Support.
Version History
Version History
v2.1
- Added Support for WHMCS 10.11
- Added Support for Stripe restricted key
- Removed Stripe secret key support
v2.0
- Added Support for Adaptive Pricing:
- Integrated Stripe’s Adaptive Pricing feature, allowing customers to pay in their local currencies.
- Automatically handles currency conversion based on the customer’s location.
- Enhances international customer experience by displaying prices in familiar currencies.
v1.1
- Initial Release of the Stripe Checkout Module:
- Supported payment methods: Credit/Debit Cards, Alipay, and Cash App.
- Implemented refund functionality directly from WHMCS.
FAQ
Q: What payment methods are supported?
A: This module supports Card, Alipay, and Cash App. Additional payment methods can be added by modifying the payment_method_types
array in the code.
Q: Can I issue partial refunds?
A: Yes, partial refunds are supported. You can specify the refund amount when processing the refund through the WHMCS admin area.