BitPay

This module is available for all self-hosted WHMCS installations and for WHMCS Cloud’s Growth and Expansion plans.

BitPay is the first and most experienced company in Bitcoin payments. BitPay builds powerful tools for secure Bitcoin payment acceptance, savings, and spending.

Supported Features

Type: Third-Party

One-TimeRecurringRefundsReversals
✓✖️✖️✖️
3D SecureRemote Update CardRemote Delete CardAddPayMethod API
✖️✖️✖️✖️

Adding the BitPay Payment Gateway

This module requires either the GMP or BCMATH PHP extensions. You can confirm that your PHP environment has at least one these extensions at Utilities > System > PHP Info.

To set up the BitPay payment gateway in WHMCS:

  1. Generate a point-of-sale (POS) token (a BitPay API token scoped for POS integrations) in BitPay: a. Log in to BitPay. b. Go to Payment Tools > API Tokens. c. Create a new API token and uncheck Require Authentication. d. Copy the generated POS token.
  2. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
  3. Click BitPay.
  4. Check Show on Order Form to display this payment method in the Client Area during checkout.
  5. Enter a display name.
  6. Paste the token you copied from BitPay into POS Token.
  7. Select a transaction speed.
    • The transaction speed setting determines how quickly an invoice payment is “confirmed,” which would be the status at which you would fulfill and complete the order.
    • For more information, see the BitPay documentation.
  8. Click Save Changes.

Test Mode

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration.

When you enable Test Mode, generate a separate testnet token at test.bitpay.com and paste it into POS Token. Enabling Test Mode does not clear the existing POS Token value, so you must replace it yourself when you switch between live and test tokens.

Troubleshooting

You can find information about most payment gateway-related errors in the logs at Billing > Gateway Log and in the Module Log.

For more information, see Troubleshooting Payments.

You may encounter the following common issues when using BitPay:

Error or IssueCauseMore Information
Token Rejected: Verify that Test Mode matches the token environment. or POS Facade Required: The token must be a POS-Facade token. or Gateway Not Configured: The system could not find the POS token. or Gateway Not Configured: You must add a POS token to your BitPay payment gateway configuration. or Configuration Error: The system detected a configuration error.Your BitPay gateway configuration’s POS Token value is missing, doesn’t match your Test Mode setting, or isn’t a point-of-sale token.BitPay Token Errors
WHMCS shows an Action Required alert on the BitPay module’s settings.Your stored POS Token value is shorter than 30 characters, which identifies it as a legacy token from an earlier BitPay integration.BitPay Token Migration Alerts
A payment completes in BitPay, but WHMCS never records it.BitPay sent the payment callback while your POS Token was temporarily invalid, and BitPay does not retry an acknowledged callback.Missed BitPay Notifications
payment-gateways third-party-gateway bitpay

Last modified: 2026 September 30