The Coinbase Payment Gateway module for WHMCS requires an API Key and an API Shared Secret from your Coinbase Commerce account. You must whitelist the URL of your WHMCS installation, create a webhook subscription that points to https://WHMCSURL/modules/gateways/callback/coinbase.php, and enable only the events the module supports. Both credentials and the webhook must be configured before the gateway can create charges or update invoices automatically.

These settings establish authenticated communication between WHMCS and Coinbase Commerce and secure the incoming webhook payloads with signature validation. Without the shared secret, WHMCS cannot verify that payment status notifications originated from Coinbase. Incorrect webhook URLs or extra events result in silent failures where invoices remain unpaid even after the customer sends cryptocurrency.

#Prerequisites

  • Active Coinbase Commerce account with API access enabled
  • WHMCS installation with the Coinbase Commerce gateway module uploaded and activated in the module settings
  • Administrative access to the Coinbase Commerce developer dashboard
  • Knowledge of whether your WHMCS installation runs in a subdirectory

#Step-by-Step Configuration in Coinbase Commerce

Log in to Coinbase Commerce and navigate to the API and webhook management area. The following exact steps are required to prepare the account for the WHMCS module. Perform them in order so that the shared secret and webhook endpoint are available when you configure the gateway inside WHMCS.

  • Select "Whitelisted Domains" and add the full URL of your WHMCS installation. If WHMCS runs in a subdirectory such as /clientarea, include that path.
  • Select "API keys", choose "Create an API key", and generate a new key. Copy the key immediately; it will be pasted into the WHMCS gateway configuration page.
  • Select "Webhook subscriptions" then "Add an endpoint" and configure the URL exactly as shown below.
  • Return to "Webhook subscriptions" and select "Show shared secret" to reveal the secret value needed for WHMCS.

#Webhook Endpoint and URL Format

The webhook tells Coinbase Commerce where to POST payment events. The module listens at the standard WHMCS callback location. Replace WHMCSURL with your actual domain. For our own installation the correct URL is shown in the code block below. If your WHMCS instance lives in a subdirectory you must include the full path so that the callback script can be reached.

plaintext 
https://billing.aspnix.com/modules/gateways/callback/coinbase.php

After the endpoint is added, Coinbase will display a list of available events. The module only processes a defined subset of these events. Enabling additional events is unnecessary and can generate extraneous HTTP requests to your WHMCS server.

#Supported Webhook Events

Our module supports the webhook events required for charge creation, confirmation, and failure handling. No other events should be enabled. Limiting the subscription to only the events the module understands prevents unexpected payload processing and reduces log noise inside WHMCS.

#Common Pitfalls and Troubleshooting

  • Forgetting to replace WHMCSURL with the real domain or omitting a subdirectory causes 404 errors on callback requests.
  • Whitelisting only the root domain when WHMCS runs in a subfolder blocks the callback from being reached.
  • Enabling every available webhook event instead of only those the module requires leads to unhandled payloads and potential gateway errors.
  • Storing the API key or shared secret in version-controlled files or sharing them in support tickets exposes credentials unnecessarily.

After entering the API Key and Shared Secret into the WHMCS gateway settings, run a test transaction using Coinbase's sandbox mode. Confirm that the invoice moves to Paid status automatically and that no errors appear in the WHMCS gateway log. If transactions do not update, double-check the webhook URL, the shared secret value, and that only the supported events remain active. This setup delivers reliable cryptocurrency payment processing with minimal manual intervention.