Installation & Usage Guide

Accept 100+ cryptocurrencies on WHMCS invoices with the JOVEpay for WHMCS gateway module. Clients pay on JOVEpay's hosted checkout page; completed payments are reported back to WHMCS automatically via Instant Payment Notifications (IPN).

This guide walks through prerequisites, installation, dashboard setup, gateway configuration, testing, and day-to-day usage.

Prerequisites

Before installing the module, make sure your WHMCS installation meets these requirements:

Important: WHMCS invoicing must already work before you add JOVEpay. The module cannot process payments until your JOVEpay account is activated.

What you'll need from JOVEpay

After creating and activating your JOVEpay account, gather the following from the dashboard:

• API Key — authenticates checkout requests from WHMCS
• IPN Secret — used to verify incoming webhook (IPN) notifications
• Merchant wallet / payout settings — configured in the dashboard so settled funds reach your wallet or bank account

If you do not have an account yet, register at https://app.jovepay.com/signup.

Install the module

Download the package and copy the gateway files into your WHMCS installation.

• JOVEpay plugin page: jovepay.com/plugins/whmcs
• Direct download (v1.0.0): jovepay-whmcs-1.0.0.zip

Package contents

After extraction, the module provides:

modules/gateways/jovepay.php
modules/gateways/callback/jovepay.php
modules/gateways/jovepay/whmcs.json
modules/gateways/jovepay/logo.svg
modules/gateways/jovepay/images/logo.svg
modules/gateways/jovepay/images/coins/

Installation steps

1. Copy the contents of modules/ into your WHMCS root directory so the files above exist under your installation.
2. In the WHMCS admin area, go to Configuration () → System Settings → Apps & Integrations.
3. Find JOVEpay Crypto Payments and click Activate.

Alternatively:

1. Go to Configuration () → System Settings → Payment Gateways.
2. Select JOVEpay from Activate New Gateway.
3. Click Save Changes.

Set up your JOVEpay account

If this is your first time using JOVEpay, complete merchant setup in the dashboard before configuring the gateway.

1. Create an account at https://app.jovepay.com/signup (or log in if you already have one).
2. Complete your business profile and payout / wallet settings so you can receive settled payments.
3. Open Payment Settings in the dashboard:
   • API credentials: app.jovepay.com/en/payments-settings#api
   • Webhooks / IPN: app.jovepay.com/en/payments-settings#webhooks

Copy your API Key

On the API tab of Payment Settings, copy your API Key. You will paste this into the WHMCS gateway settings.

Copy your IPN Secret

On the Webhooks tab, copy your IPN Secret. This secret is used to verify that payment notifications sent to WHMCS are genuinely from JOVEpay.

Configure the gateway in WHMCS

Step 1 — Open gateway settings

1. In WHMCS admin, go to Configuration () → System Settings → Payment Gateways.
2. Open the JOVEpay gateway configuration.

Step 2 — Fill in the settings

3. In Configuration () → System Settings → General Settings, confirm Domain / System URL is your public client-area URL (for example https://example.com/whmcs). This URL is used to build the IPN callback and payment button image paths.

4. Click Save Changes.

Note: The API Key is required. Without it, the payment button will not start checkout.

Step 3 — IPN callback URL

WHMCS receives payment notifications at:

https://your-domain.com/whmcs/modules/gateways/callback/jovepay.php

(Replace the path with your actual WHMCS System URL.)

The callback URL is sent automatically when a client starts checkout. Requests are verified with the X-JOVEPAY-SIG HMAC header using your configured IPN Secret.

How invoice payment works

When a client pays an invoice with JOVEpay:

1. The client opens an unpaid invoice and chooses JOVEpay.
2. The client submits the payment button and is redirected to the JOVEpay hosted payment widget.
3. The client pays with a supported cryptocurrency.
4. JOVEpay sends a signed Instant Payment Notification to WHMCS.
5. WHMCS verifies the X-JOVEPAY-SIG HMAC header and records the invoice payment.
6. The client returns to the WHMCS invoice return URL.

Invoice references sent to JOVEpay use the format WHMCS-{invoiceId}.

Test your integration

Use the JOVEpay demo environment to verify everything works before going live.

Demo dashboard credentials

Sign in with these credentials, copy the API Key and IPN Secret from Payment Settings, and paste them into the WHMCS gateway settings.

Enable test mode

In the gateway settings, enable Testnet Mode while testing. This routes payments through JOVEpay's test environment instead of live networks.

Live demo store

Visit the pre-configured demo to see the full invoice payment flow in action:

https://whmcs.jovepay.com/

Testnet faucets

Demo environments run on test networks. Use these faucets to obtain test tokens for trial payments:

• Tron Nile Testnet
• BNB Testnet
• Solana Devnet
• Solana USDC Devnet

Testing checklist

1. Enable Testnet Mode and save the gateway.
2. Log in to the demo dashboard and copy API Key + IPN Secret.
3. Create or open a test invoice and select JOVEpay.
4. Complete payment on the JOVEpay hosted page.
5. Confirm the WHMCS invoice is marked as paid.
6. Disable Testnet Mode and switch to your production credentials when ready to go live.

Supported cryptocurrencies

JOVEpay supports 100+ cryptocurrencies including popular assets such as:

• Bitcoin (BTC), Ethereum (ETH), Litecoin (LTC), Dogecoin (DOGE)
• BNB Smart Chain (BEP20), Polygon (POL), Arbitrum (ARB), Optimism (OP), Solana (SOL)
• Stablecoins: USDT, USDC, DAI, BUSD, TUSD, PYUSD, and more

Clients can pay with any supported coin; JOVEpay handles conversion and settlement according to your dashboard configuration.

Troubleshooting

JOVEpay does not appear on invoices

• Confirm the gateway files are in the correct paths under modules/gateways/.
• Confirm JOVEpay is activated under Payment Gateways.
• Check that the API Key is saved.

Invoice status does not update after payment

• Verify the IPN Secret in WHMCS matches the value in your JOVEpay dashboard.
• Confirm System URL in General Settings matches your public WHMCS URL.
• Ensure modules/gateways/callback/jovepay.php is reachable over HTTPS (not blocked by a firewall).

Payment button images or callback URL look wrong

Set Domain / System URL in General Settings to the full public URL of your client area (including the WHMCS subdirectory if applicable).

Payments fail in test mode

Ensure Testnet Mode is enabled and you are using credentials from the demo dashboard. Use testnet faucets to fund your test wallet before attempting a payment.

Going live

When you are satisfied with testing:

1. Disable Testnet Mode in the gateway settings.
2. Replace demo credentials with your production API Key and IPN Secret.
3. Confirm payout / wallet settings in your JOVEpay dashboard.
4. Place a small real invoice payment to verify end-to-end settlement.

Support and resources

• Plugin page: jovepay.com/plugins/whmcs
• Create an account: app.jovepay.com/signup
• Dashboard login: app.jovepay.com/login
• Demo: whmcs.jovepay.com
• Contact: [email protected]

For installation help or merchant onboarding, reach out to the JOVEpay team — support is available 24/7.