FastSpring for WHMCS Setup Guide

This guide explains how to install and configure the FastSpring for WHMCS payment gateway module.

Follow each step carefully. After setup, customers can pay WHMCS invoices through FastSpring, and WHMCS can handle invoice payments, subscription IDs, renewals, refunds, and cancellations.

What This Module Does

FastSpring for WHMCS connects WHMCS invoices to FastSpring checkout.

It supports:

• One-time payments
• Monthly subscriptions
• Quarterly subscriptions
• Semi-annually subscriptions, billed every 6 months
• Annually subscriptions, billed every 12 months
• Biennially subscriptions, billed every 2 years
• Triennially subscriptions, billed every 3 years
• Setup fees
• Invoice credits and discounts
• Full refunds
• Partial refunds
• Subscription ID mapping into WHMCS
• Automatic renewal invoice payments through FastSpring webhooks
• Manual subscription cancellation from WHMCS

Requirements

Before you begin, make sure you have:

• An active WHMCS installation
• Access to your WHMCS admin area
• FTP, SFTP, SSH, or file manager access to your WHMCS files
• An active FastSpring account
• FastSpring API username and password
• FastSpring Storefront ID
• FastSpring webhook signing secret
• A valid module license key
• FastSpring catalog products for the billing intervals you want to use

Step 1: Upload The Module Files

Upload the module files into your WHMCS installation.

The main files should be located at:

• modules/gateways/fastspring.php
• modules/gateways/callback/fastspring.php
• modules/gateways/fastspring/lib/FastSpringApi.php

If your package includes additional files inside modules/gateways/fastspring/, upload those files as well.

After uploading, the module should appear in WHMCS under payment gateways.

Step 2: Create FastSpring Catalog Products

In FastSpring, create catalog products for each billing interval you want to support.

You do not need to use these exact names, but your WHMCS settings must match the FastSpring product paths exactly.

Example product paths:

• whmcs-item for one-time invoice items
• monthly-sub for monthly subscriptions
• quarterly-sub for quarterly subscriptions
• semiannual-sub for subscriptions billed every 6 months
• annual-sub for annual subscriptions
• biennial-sub for subscriptions billed every 2 years
• triennial-sub for subscriptions billed every 3 years

Important: FastSpring product paths are case-sensitive.

For example, biennial-sub and Biennial-Sub are different paths.

Step 3: Configure Subscription Intervals In FastSpring

Each FastSpring subscription product must have the correct billing interval configured inside FastSpring.

Use this mapping:

• Monthly Product Path: FastSpring subscription billed every 1 month
• Quarterly Product Path: FastSpring subscription billed every 3 months
• Semi-Annually Product Path: FastSpring subscription billed every 6 months
• Annually / Yearly Product Path: FastSpring subscription billed every 12 months
• Biennially Product Path: FastSpring subscription billed every 2 years
• Triennially Product Path: FastSpring subscription billed every 3 years

WHMCS selects the FastSpring product path, but FastSpring controls the actual renewal interval for that catalog product.

This means the product itself must be configured correctly in FastSpring.

Step 4: Get FastSpring API Credentials

In your FastSpring account, locate or create your API credentials.

You will need:

• API Username
• API Password

These credentials allow WHMCS to create checkout sessions, validate product paths, process refunds, and cancel subscriptions.

Step 5: Get Your FastSpring Storefront ID

Find your FastSpring Storefront ID.

This is usually your FastSpring storefront domain or storefront path.

Example:

yourstore.test.onfastspring.com

or:

yourstore.onfastspring.com

Enter this value exactly in the WHMCS gateway settings.

Step 6: Configure FastSpring Webhooks

FastSpring must send webhook events to WHMCS.

Set your webhook endpoint URL to:

https://yourdomain.com/modules/gateways/callback/fastspring.php

Replace yourdomain.com with your real WHMCS domain.

Enable these webhook events:

• order.completed
• subscription.created
• subscription.activated
• subscription.charge.completed

These events are important:

• order.completed marks the initial WHMCS invoice as paid.
• subscription.created and subscription.activated help save the FastSpring Subscription ID into WHMCS.
• subscription.charge.completed helps WHMCS mark future renewal invoices as paid automatically.

Step 7: Copy The Webhook Signing Secret

In FastSpring webhook settings, copy the webhook signing secret.

You will enter this value into WHMCS as:

HMAC Secret Key

This is used to verify that webhook requests are really coming from FastSpring.

If the webhook secret is wrong, FastSpring callback requests will fail.

Step 8: Activate The Gateway In WHMCS

Log in to your WHMCS admin area.

Go to:

System Settings > Payment Gateways

Then activate:

FastSpring

Depending on your WHMCS version, this area may also appear under:

Setup > Payments > Payment Gateways

Step 9: Enter Gateway Settings

In the FastSpring gateway settings, enter the required values.

License Settings

• License Key: Enter your module license key.
• Local License Data: Leave this empty unless support tells you otherwise.

FastSpring API Settings

• API Username: Enter your FastSpring API username.
• API Password: Enter your FastSpring API password.
• Storefront ID: Enter your FastSpring Storefront ID.
• HMAC Secret Key: Enter your FastSpring webhook signing secret.

Product Path Settings

Enter your FastSpring product paths.

• One-Time Product Path
• Monthly Product Path
• Quarterly Product Path
• Semi-Annually Product Path
• Annually / Yearly Product Path
• Biennially Product Path
• Triennially Product Path

Only enter paths that exist in your FastSpring catalog.

The values must match FastSpring exactly, including lowercase and uppercase letters.

Step 10: Configure WHMCS Products

Create or edit your WHMCS products as usual.

For recurring hosting products, choose the correct WHMCS billing cycle:

• Monthly
• Quarterly
• Semi-Annually
• Annually
• Biennially
• Triennially

When a customer pays, the module uses the WHMCS invoice and billing cycle to select the matching FastSpring product path.

Step 11: Test A One-Time Payment

Create a test invoice with a one-time item.

Choose FastSpring as the payment method.

Click Pay Now.

Confirm that:

• FastSpring popup checkout opens.
• The checkout amount matches the WHMCS invoice total.
• The payment completes successfully.
• WHMCS marks the invoice as paid.

Step 12: Test A Subscription Payment

Create a test recurring product invoice.

Use one of these billing cycles:

• Monthly
• Quarterly
• Semi-Annually
• Annually
• Biennially
• Triennially

Choose FastSpring as the payment method and complete checkout.

After payment, check the WHMCS service.

Go to:

WHMCS Admin > Clients > Products/Services

Open the purchased service and check:

Subscription ID

The Subscription ID should be populated automatically after FastSpring sends the subscription webhook.

Step 13: Test Invoice Credits And Setup Fees

Create an invoice with:

• A recurring product
• A setup fee
• A credit or discount

Open FastSpring checkout and confirm that the checkout total matches the WHMCS invoice total.

The module is designed to charge the correct first payment amount while preserving the correct recurring renewal amount for the subscription.

Example:

• Initial WHMCS invoice total: $300.00
• Future recurring renewal amount: $450.00

FastSpring checkout should charge $300.00 first, while the subscription renewal amount remains connected to the recurring product amount.

Step 14: Test Automatic Renewals

For automatic renewal handling, the WHMCS service must have a FastSpring Subscription ID saved.

When FastSpring charges a subscription renewal, it sends:

subscription.charge.completed

The module then tries to find the matching unpaid WHMCS renewal invoice by Subscription ID.

If a matching unpaid invoice is found, WHMCS will mark it as paid automatically.

Step 15: Test Refunds

Open a paid WHMCS invoice.

Use the WHMCS refund option.

You can test:

• Full refund
• Partial refund with a custom amount

For partial refunds, enter the amount you want to refund in WHMCS.

The module sends the partial refund request to FastSpring and prevents it from accidentally becoming a full refund.

Step 16: Test Subscription Cancellation

Open the WHMCS service that has a Subscription ID.

Use the WHMCS subscription cancellation option.

The module will send a cancellation request to FastSpring for the saved Subscription ID.

If the Subscription ID field is empty, cancellation cannot be sent to FastSpring automatically.

Troubleshooting

FastSpring Checkout Shows The Wrong Billing Interval

Check the product path configured in WHMCS.

Then check the matching product in FastSpring.

The FastSpring product itself must have the correct subscription interval.

FastSpring Checkout Shows The Wrong Amount

Check the WHMCS Activity Log for:

FastSpring Checkout Debug

Confirm these values:

• WHMCS Amount
• Amount Source
• FastSpring Gross Item Total
• Coupon Discount
• Expected Checkout Total
• Product Path

Expected Checkout Total should match the WHMCS invoice total.

Product Path Not Found

FastSpring product paths are case-sensitive.

Make sure the WHMCS product path exactly matches the FastSpring catalog path.

Example:

annual-sub

is not the same as:

Annual-Sub

Webhook Signature Error

If WHMCS logs an invalid webhook signature, check the HMAC Secret Key.

The HMAC Secret Key in WHMCS must match the webhook signing secret in FastSpring.

Invoice Is Paid In FastSpring But Not Paid In WHMCS

Check that FastSpring webhooks are configured correctly.

Confirm that the webhook URL is:

https://yourdomain.com/modules/gateways/callback/fastspring.php

Check that the order.completed event is enabled.

Then check the WHMCS Gateway Log and Activity Log for callback errors.

Subscription ID Is Not Showing In WHMCS

Check that these webhook events are enabled in FastSpring:

• subscription.created
• subscription.activated
• order.completed

If the original webhook was already sent before the latest module version was installed, resend the related FastSpring webhook from the FastSpring dashboard.

The WHMCS Activity Log should show a message similar to:

FastSpring Subscription ID ... mapped to hosting ... for invoice ...

Renewal Invoice Is Not Marked Paid Automatically

Check that:

• The WHMCS service has a Subscription ID.
• FastSpring sent the subscription.charge.completed webhook.
• The WHMCS renewal invoice was unpaid when the webhook arrived.
• The service payment method is FastSpring.

Important Notes

• FastSpring product paths are case-sensitive.
• Semi-Annually means every 6 months.
• Biennially means every 2 years.
• Triennially means every 3 years.
• Each FastSpring subscription product must be configured with the correct billing interval inside FastSpring.
• Do not use the same FastSpring monthly product path for annual, biennial, or triennial WHMCS products.

Support

If you need help, include the following information when contacting support:

• WHMCS version
• PHP version
• Module version
• Invoice ID
• FastSpring order ID
• FastSpring subscription ID, if available
• Screenshot of the WHMCS invoice
• Relevant WHMCS Gateway Log entry
• Relevant WHMCS Activity Log entry

Never send your FastSpring API password or webhook secret in plain text unless support specifically asks for it through a secure support channel.