Billing Hub

Gateway-agnostic billing layer for Drupal 10 / 11. Manages subscriptions,
invoices, tax, and dunning. Integrates with Membership Manager for access
control. Supports Stripe, PayPal, Braintree, and custom payment gateways via a Plugin API.

Requirements

• Drupal 10.2+ or Drupal 11
• PHP 8.2+
• drupal:user (core)
• membership_manager module

Gateway dependencies

# Stripe
composer require stripe/stripe-php

# PayPal
composer require paypal/paypal-server-sdk

Installation

composer require drupal/billing_hub
drush en billing_hub billing_hub_stripe
drush cr

Visit /admin/billing to configure.

Architecture Overview

CheckoutService → BillingManagerService → GatewayPlugin
BillingPortalController → BillingManagerService → SubscriptionService
WebhookController → WebhookDispatcherService → BillingManagerService
DunningService → Queue → DunningQueueWorker → GatewayPlugin::retryInvoice()
TaxService ← BillingPlan + TaxRate
AnalyticsService ← billing_subscription + billing_invoice tables

BillingManagerService is the central entry point.

Billing Plans

Gateway Configuration

Stripe example

secret_key: sk_live_...
publishable_key: pk_live_...
webhook_secret: whsec_...
test_mode: false

Checkout Flow

PHP Example

$checkout = \Drupal::service('billing_hub.checkout');

$preview = $checkout->preview(
  plan_id: 'pro_monthly',
  country_code: 'DE',
  tax_id: 'DE123456789'
);

$result = $checkout->checkout(
  user: $user,
  plan_id: 'pro_monthly'
);

AJAX Preview

fetch('/billing/checkout/pro_monthly/preview', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({ country_code: 'DE' })
});

Subscription Lifecycle

active → canceled
active → paused → active
active → past_due → unpaid
trialing → active

Webhooks

Dunning

Retry schedule: 0, 1, 3, 7, 14 days

Tax

Modes

VAT validation hook

function mymodule_billing_hub_vat_validate(string $vat_number): bool {
  return my_vies_client()->validate($vat_number);
}

Analytics

$analytics = \Drupal::service('billing_hub.analytics');

$analytics->getMRR();
$analytics->getARR();
$analytics->getChurnRate(30);

User Billing Portal

Membership Integration

BillingPlan.membership_plan_id → assignMembership()
→ MembershipManagerService::assign()

Custom Gateway

/**
 * @Gateway(
 *   id = "my_gateway",
 *   label = @Translation("My Gateway")
 * )
 */
class MyGateway extends GatewayPluginBase {}

Hooks

Coupon

function mymodule_billing_hub_coupon_validate(string $code): float {
  return 10.0;
}

Redirect

function mymodule_billing_hub_checkout_success_url(...) {
  return '/members/welcome';
}

Maintainers

Dmytro Porokhnya

License

GPL-2.0-or-later