Stripe Checkout WHMCS — Documentation

Installation • Configuration • Webhooks • Pricing • Operations • Security • FAQ

Stripe Checkout WHMCS Module

This documentation covers installation, configuration, webhooks, pricing options, and operations for the Stripe Checkout WHMCS Module. Use the sidebar to jump between topics.

Order Link

marketplace.whmcs.com/product/7566

Support

Open a ticket → my.racknode.net

System Requirements

WHMCS

  • WHMCS 8.0 and later (8.10, 8.11, 8.13, and WHMCS 9 supported)

PHP

  • PHP 7.4 or later (7.4, 8.1, 8.2, 8.3 supported)
  • Earlier versions are not supported due to security and Stripe API compatibility

ionCube Loader (minimum versions)

PHP VersionMinimum ionCube Loader
7.414+
8.114+
8.214+
8.314+

Installation

  1. Download the ZIP file containing the gateway and callback files.
  2. Extract the ZIP directly into /modules/gateways/

    This places stripecheckout.php into /modules/gateways/, stripecheckoutcallback.php into /modules/gateways/callback/, and the stripecheckout/ folder (containing license verification, module metadata, and logo) into /modules/gateways/stripecheckout/

Configuration

Step 1: Enable gateway in WHMCS

  1. Log in to WHMCS Admin → Configuration → System Settings → Payment Gateways.
  2. Click Visit Apps & Integrations and locate StripeCheckout.
  3. Click Activate next to StripeCheckout.

Step 2: Fill configuration fields

  • License Key — Enter the license key provided upon purchase of this module. The license status (Active, Expired, Suspended, or Invalid) is displayed alongside a Recheck button.
  • Publishable Key — Your Stripe Publishable Key (begins with pk_live or pk_test).
  • Restricted Key — Your Stripe Restricted Key used for server-side API calls (creating checkout sessions, processing refunds).
  • Webhook Secret — Your Stripe Webhook Secret for verifying webhook signatures.
  • Custom Pay Button Text — Change the checkout button label (e.g., “Pay Securely”, “Checkout with Stripe”). Defaults to Pay Now.
  • Allowed Payment Methods (optional) — Comma-separated list of payment methods to only allow (e.g., card, paypal, ideal). When set, only these methods are shown and the Excluded field is ignored. Leave empty for dynamic mode.
  • Excluded Payment Methods (optional) — Comma-separated list of payment methods to exclude (e.g., cashapp, crypto, klarna). Only used when Allowed Payment Methods is empty.
Permissions to enable on the Restricted Key
  • Checkout Sessions (Write)
  • PaymentIntents (Read)
  • Charges and Refunds (Write)
  • Payment Links (Write)
  • PaymentMethods (Write)
  • Payment Method Domains (Write)
  • Customers (Write)
  • Webhook Endpoints (Write)
  • Tokens (Write)

Webhook Configuration

Step 1: Create a webhook endpoint in Stripe

  1. Go to Developers → Webhooks → Add endpoint in Stripe Dashboard.
  2. Endpoint URL:
    https://yourwhmcsdomain.com/modules/gateways/callback/stripecheckoutcallback.php

    Replace the domain with your WHMCS installation domain.

  3. Select and subscribe to these events:
  • checkout.session.completed
  • payment_intent.processing
  • payment_intent.succeeded
  • payment_intent.payment_failed

Step 2: Add the Webhook Secret to WHMCS

Copy the Webhook Secret from Stripe and paste it into the module configuration.

Stripe Adaptive Pricing (Optional)

To enable Stripe Adaptive Pricing for your Stripe Checkout, follow these steps:

Step 1: Enable Adaptive Pricing in 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.

Step 2: Check Country Support

Before enabling Adaptive Pricing, make sure that your country supports this feature. Check the full list of supported countries by visiting the official documentation:

Stripe Adaptive Pricing Supported Countries

Step 3: 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.

Payment Methods

This module uses Stripe’s Automatic Payment Methods. Stripe dynamically shows the most relevant payment methods based on the customer’s location, currency, and transaction amount. You can also control which methods appear using the configuration fields.

Three operating modes

ModeHow to enableBehavior
Dynamic (default)Leave both Allowed and Excluded fields emptyStripe automatically selects the best payment methods for each customer based on location, currency, and amount.
Allowed listEnter methods in Allowed Payment Methods (e.g., card, paypal, ideal)Only the listed methods are shown. The Excluded field is ignored.
Excluded listLeave Allowed empty, enter methods in Excluded Payment Methods (e.g., cashapp, crypto, klarna)Dynamic mode with specific methods blocked. Note: Apple Pay, Google Pay, and Link cannot be excluded this way — use wallet-specific settings in the Stripe Dashboard instead.

Enable methods in Stripe Dashboard

In Stripe Dashboard → Settings → Payments → Payment Methods, toggle on Alipay, Cash App, PayPal, and other supported methods for your account.

Very Important: Only enable payment methods in WHMCS that are enabled/supported in your Stripe Dashboard; otherwise the module will not function.

Usage

For Customers

  • Choose Stripe Checkout during invoice payment.
  • Redirected to Stripe's hosted page, then back to WHMCS after payment.

For Admins

  • Track transactions in WHMCS under the Transactions tab.
  • All payment details (Transaction ID, Amount Paid) are logged.

Refunds

  1. Go to Billing → Invoices and open the target invoice.
  2. Click Refund and enter amount (partial refunds supported).
  3. All refunds are logged via logModuleCall(). Errors appear in the Module Log.

Error Handling & Logs

  • Customers receive generic messages on errors to avoid leaking internals.
  • Detailed errors (including Stripe API errors) are logged via logModuleCall().
  • View at Configuration → System Logs → Module Log.

Security

  • Restricted Key and Webhook Secret are stored securely by WHMCS and not exposed to users.
  • Webhook callbacks verify the Stripe signature using \Stripe\Webhook::constructEvent() to reject tampered or forged requests.
  • Strict input validation of invoice ID, amount, and transaction IDs.
  • Always use HTTPS on your WHMCS installation.

FAQ

Q: Why is my invoice not marked as paid after a successful payment?

Ensure that:

  • The Webhook is correctly configured in Stripe Dashboard
  • The Webhook Secret is accurately entered in the WHMCS module configuration
  • Update your Stripe webhook to include these events:
  • checkout.session.completed
  • payment_intent.processing
  • payment_intent.succeeded
  • payment_intent.payment_failed

Check the Module Log in WHMCS for any errors or missing event handling.

Q: Why am I not receiving webhook notifications from Stripe?

Check the following items in your Stripe Dashboard and WHMCS installation:

  • The webhook endpoint URL is correct and publicly reachable over HTTPS.
  • Your server firewall, WAF, or Cloudflare rules are not blocking Stripe requests.
  • Stripe shows a successful 2xx response for webhook deliveries instead of 4xx or 5xx errors.
  • The webhook events include checkout.session.completed, payment_intent.processing, and payment_intent.succeeded.
  • The Webhook Secret in WHMCS matches the current endpoint secret in Stripe.

If Stripe reports failed deliveries, inspect the response body and the WHMCS Module Log to identify the exact rejection or error.

Q: How do I ensure the module works across different PHP versions?

Use the correct ionCube Loader version for your PHP version (see the table in System Requirements section).

Company

Mustafa Tech LLC — Registration Number: 7702442

Premium Web Hosting Company

Email: [email protected]