HitPay Payment Gateway provides integration between Drupal Commerce 2.x and HitPay, enabling merchants to accept online payments using HitPay Hosted Checkout.
The module supports secure webhook-based payment processing, automatic webhook lifecycle management, full and partial refunds, sandbox and live environments, and optional debug logging for HitPay API requests and responses.
- HitPay Hosted Checkout
- Payment processing through verified webhooks
- Automatic webhook lifecycle management
- Commerce payment creation
- Customer return handling
- Full and partial refunds
- Sandbox and live environments
- Optional HitPay API debug logging
- Drupal 9.3 or later support and Drupal 10 support
- Drupal Commerce 2.x support
- Drupal 9.3 or later within the Drupal 9 release series, or Drupal 10
- Drupal Commerce 2.x
- PHP 7.4 or PHP 8.x
- Active HitPay merchant account
- HitPay API credentials
Clone the repository into the modules/custom directory of your Drupal installation.
If the custom directory does not exist, create it first:
cd [DRUPAL-ROOT]/modules
mkdir customThen clone the repository:
cd [DRUPAL-ROOT]/modules/custom
git clone https://github.com/hit-pay/drupal-commerce-2x.git commerce_hitpayAlternatively, download the ZIP archive from GitHub and extract it into the modules/custom directory.
Ensure that the module files are located at:
[DRUPAL-ROOT]/modules/custom/commerce_hitpay
[DRUPAL-ROOT] refers to the Drupal document root containing directories such as core, modules, sites, and themes.
Enable the module using Drush:
drush en commerce_hitpayAlternatively, enable the module through the Drupal administration interface:
Administration
→ Extend
→ HitPay Payment Gateway
Register the GitHub VCS repository:
composer config repositories.commerce_hitpay vcs https://github.com/hit-pay/drupal-commerce-2xInstall the development branch:
composer require hitpay/commerce_hitpay:dev-mainThen enable the module:
drush en commerce_hitpayWhen stable Git tags are available, install a tagged release instead:
composer require hitpay/commerce_hitpay:^1.0Or use the Drupal administration interface:
Administration
→ Extend
→ HitPay Payment Gateway
Navigate to:
Commerce
→ Configuration
→ Payment Gateways
Create a payment gateway and select HitPay.
Configure:
-
API Key
-
Mode
- Sandbox
- Live
-
Enable debug logging (optional)
Save the payment gateway.
The module automatically:
- Validates the supplied API credentials.
- Registers and synchronizes the HitPay webhook.
- Removes duplicate webhooks registered for the same endpoint before creating a replacement.
- Stores the webhook ID and webhook salt.
- Repairs missing or externally deleted webhooks.
- Recreates the webhook when required to recover missing webhook credentials.
- Attempts to remove the previous webhook when API credentials or environment change.
No manual webhook registration is required.
Enable debug logging when troubleshooting communication with the HitPay API.
When enabled, the module logs:
- HitPay API request method and endpoint.
- Sanitized request payloads.
- HTTP response status.
- Sanitized API response bodies.
- API error responses and request failures.
- Sandbox or live environment information.
Sensitive values, including webhook salts and customer information, are redacted from debug logs.
Debug logging should normally remain disabled in production and enabled temporarily when troubleshooting.
- The customer places an order and selects HitPay.
- Drupal Commerce creates a HitPay payment request.
- The customer is redirected to HitPay Hosted Checkout.
- The customer completes the payment.
- HitPay sends a signed webhook notification.
- The module verifies the webhook signature and payment notification.
- A Commerce payment is created for the successful HitPay payment.
- The customer return request continues the Commerce checkout flow.
Note: The customer return request and webhook notification are independent HTTP requests and may arrive in either order. Payment completion is determined from the verified HitPay payment notification rather than relying solely on the browser return request.
The module automatically manages the HitPay webhook lifecycle.
When the payment gateway is saved, the module:
- Creates a webhook when no stored webhook exists.
- Removes stale duplicate webhooks registered for the same endpoint before creating a replacement.
- Verifies that the stored webhook still exists remotely.
- Synchronizes webhook configuration when the endpoint changes.
- Recreates externally deleted webhooks.
- Recreates the webhook when the locally stored webhook salt is missing.
- Attempts to delete the previous webhook when API credentials or environment change.
- Stores the webhook ID and webhook salt required for future synchronization and signature verification.
Webhook synchronization failures are logged and prevent invalid webhook configuration from being silently accepted.
Incoming webhook requests are signature-verified before payment notifications are processed.
Refunds are integrated with Drupal Commerce and can be issued from the Commerce payment administration interface.
Supported operations:
- Full refunds
- Partial refunds
Before submitting a refund, the module:
- Verifies that the payment is refundable.
- Validates the requested refund amount.
- Verifies that the remote HitPay payment ID is available.
After a successful HitPay refund:
- The Commerce refunded amount is updated.
- Partial refunds set the payment state to
partially_refunded. - Full refunds set the payment state to
refunded. - Available HitPay refund metadata is stored on the order.
If HitPay successfully creates the refund but Drupal cannot persist the corresponding local payment or order changes, the module logs a critical error and warns administrators not to retry the refund blindly.
Use Sandbox mode to test the integration without processing live payments.
Recommended test workflows:
- API credential validation
- Hosted Checkout redirection
- Successful payment
- Customer return handling
- Webhook signature verification
- Commerce payment creation
- Missing remote webhook recovery
- Duplicate webhook cleanup
- Missing webhook salt recovery
- Webhook URL synchronization
- API credential and environment changes
- Invalid webhook signature handling
- Full refund
- Partial refund
- Invalid refund amount
- Missing remote payment ID
- Debug request and response logging
Deployment Check: Before enabling Live mode, verify that the production Drupal site uses HTTPS and can receive incoming HitPay webhook requests.
Temporarily enable debug logging in the HitPay payment gateway configuration to inspect sanitized HitPay API requests, responses, HTTP status codes, and request failures.
Review Drupal log messages under the commerce_hitpay logger channel.
Disable debug logging after troubleshooting, especially on production sites.
Verify that:
- The HitPay webhook can reach the Drupal site.
- The configured API key and environment are correct.
- The webhook signature is valid.
- The expected HitPay payment event is received.
- Drupal logs do not contain webhook processing or payment creation errors.
Enable debug logging to inspect HitPay API communication when additional diagnostics are required.
Verify that:
- The configured API key belongs to the selected environment.
- The Drupal webhook endpoint is publicly reachable.
- HitPay webhook API requests are succeeding.
- The stored webhook configuration has not been manually modified.
Enable debug logging and review the HitPay API request and response details.
Verify that:
- The stored webhook salt belongs to the registered HitPay webhook.
- The request body is not modified before signature verification.
- The correct HitPay environment and credentials are configured.
- Reverse proxies or other infrastructure are not modifying the webhook request.
The browser return request does not replace webhook payment verification.
Verify that the corresponding HitPay webhook was received, verified, and successfully processed.
Verify that:
- The Commerce payment is refundable.
- The payment contains the correct remote HitPay payment ID.
- The requested amount does not exceed the remaining refundable amount.
- The API credentials belong to the configured environment.
Enable debug logging to inspect the HitPay refund API request and response.
For bug reports, feature requests, and other issues, use the GitHub issue tracker for this project.
When reporting an issue, include:
- Drupal version
- Drupal Commerce version
- PHP version
- Module version or Git commit
- HitPay environment (Sandbox or Live)
- Relevant Drupal log messages
- Steps to reproduce the issue
See CHANGELOG.md for version history and release notes.
This project is licensed under the GNU General Public License v2 or later (GPL-2.0-or-later).
See the LICENSE file for details.