Skip to main content

​
Configuration File

The configuration file is published to config/billing.php: 
php artisan vendor:publish --tag=billing-config

​
Default Configuration

config/billing.php
return [
    /*
    |--------------------------------------------------------------------------
    | Table Prefix
    |--------------------------------------------------------------------------
    |
    | The prefix for all billing-related database tables.
    |
    */
    'table_prefix' => 'billing_',

    /*
    |--------------------------------------------------------------------------
    | Default Currency
    |--------------------------------------------------------------------------
    |
    | The default currency code (ISO 4217) to use when not specified.
    |
    */
    'default_currency' => env('BILLING_DEFAULT_CURRENCY', 'EUR'),

    /*
    |--------------------------------------------------------------------------
    | Proration Behavior
    |--------------------------------------------------------------------------
    |
    | Whether to prorate charges when changing plans.
    |
    */
    'prorate_on_plan_change' => true,
];

​
Billable Configuration

Configure how the package resolves the billable entity in AppServiceProvider:
app/Providers/AppServiceProvider.php
use Eufaturo\Billing\Billing;

public function boot(): void
{
    Billing::resolveBillableUsing(function () {
        return auth()->user();
    });
}

Billing::resolveBillableUsing(fn() => auth()->user());

Billing::resolveBillableUsing(function () {
    return auth()->user()?->activeCompany ?? auth()->user();
});

Billing::resolveBillableUsing(function () {
    return match(true) {
        request()->has('company_id') => Company::find(request('company_id')),
        auth()->user()->activeCompany => auth()->user()->activeCompany,
        default => auth()->user()
    };
});

​
Payment Gateway Configuration

​
Interactive Configuration

Use the Artisan command to configure gateways interactively: 
php artisan billing:gateway:install stripe
This will:
  1. Prompt for API credentials
  2. Allow UI customization
  3. Install default payment methods
  4. Store configuration in database
Gateway configuration is stored in the billing_payment_gateways table, not in config files.

​
Stripe Configuration

When configuring Stripe, you’ll be prompted for: API Credentials:
  • Secret Key (sk_...)
  • Publishable Key (pk_...)
  • Webhook Secret (whsec_...) - Optional
UI Customization:
  • Theme (stripe, night, flat)
  • Primary color
  • Background color
  • Text color
  • Danger/error color
  • Font family
  • Spacing unit
  • Border radius
Payment Methods:
  • Credit/Debit Card
  • SEPA Direct Debit

​
Programmatic Configuration

You can also configure gateways programmatically: 
use Eufaturo\Billing\PaymentGateways\Models\PaymentGateway;

PaymentGateway::updateOrCreate(
    ['slug' => 'stripe'],
    [
        'name' => 'Stripe',
        'is_active' => true,
        'config' => [
            'api_keys' => [
                'secret_key' => env('STRIPE_SECRET'),
                'publishable_key' => env('STRIPE_KEY'),
                'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
            ],
            'stripe_elements_appearance' => [
                'theme' => 'night',
                'variables' => [
                    'colorPrimary' => '#635BFF',
                    'colorBackground' => '#1A1B25',
                    'colorText' => '#E3E8EE',
                ],
            ],
        ],
    ]
);

​
Currency Setup

​
Create Currencies

Use the CreateCurrency action to create currencies: 
use Eufaturo\Billing\Currencies\Actions\CreateCurrency;
use Eufaturo\Billing\Currencies\Dto\CreateCurrencyDto;

// Create EUR
$eur = app(CreateCurrency::class)->execute(
    new CreateCurrencyDto(
        isoCode: 'EUR',
        name: 'Euro',
        symbol: '€',
        rate: 100, // 1:1 exchange rate
    )
);

// Create USD
$usd = app(CreateCurrency::class)->execute(
    new CreateCurrencyDto(
        isoCode: 'USD',
        name: 'US Dollar',
        symbol: '$',
        rate: 110, // Example: 1 EUR = 1.10 USD
    )
);

​
Using Database Seeder

Create a seeder for currencies using the Billing facade:
database/seeders/CurrencySeeder.php
use Eufaturo\Billing\Billing;
use Illuminate\Database\Seeder;

class CurrencySeeder extends Seeder
{
    public function run(): void
    {
        $currencies = [
            ['iso_code' => 'EUR', 'name' => 'Euro', 'symbol' => '€', 'rate' => 100],
            ['iso_code' => 'USD', 'name' => 'US Dollar', 'symbol' => '$', 'rate' => 110],
            ['iso_code' => 'GBP', 'name' => 'British Pound', 'symbol' => '£', 'rate' => 115],
        ];

        foreach ($currencies as $data) {
            // Skip if currency already exists
            if (Billing::currencies()->find($data['iso_code'])) {
                continue;
            }

            Billing::currencies()->create(
                isoCode: $data['iso_code'],
                name: $data['name'],
                symbol: $data['symbol'],
                rate: $data['rate'],
            );
        }
    }
}

​
Route Configuration

​
Disable Default Routes

If you want to use custom routing:
app/Providers/AppServiceProvider.php
use Eufaturo\Billing\Billing;

public function boot(): void
{
    Billing::ignoreRoutes();
}

​
Environment Variables

Add these to your .env file:
.env
# Billing Configuration
BILLING_DEFAULT_CURRENCY=EUR

# Stripe Configuration
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Database (if different from main app)
BILLING_DB_CONNECTION=mysql
BILLING_DB_HOST=127.0.0.1
BILLING_DB_PORT=3306
BILLING_DB_DATABASE=billing_db

​
Multi-Tenancy Configuration

For multi-tenant applications:

​
Option 1: Tenant-Scoped Billable

Billing::resolveBillableUsing(function () {
    return tenant()->company; // Using Tenancy for Laravel
});

​
Option 2: Per-Request Resolution

Billing::resolveBillableUsing(function () {
    $tenantId = request()->header('X-Tenant-ID');
    return Company::findOrFail($tenantId);
});

​
Option 3: Subdomain-Based

Billing::resolveBillableUsing(function () {
    $subdomain = request()->getHost();
    return Company::where('subdomain', $subdomain)->firstOrFail();
});

​
Testing Configuration

In your test setup, reset and configure the billable resolver:
tests/TestCase.php
use Eufaturo\Billing\Billing;

protected function setUp(): void
{
    parent::setUp();

    Billing::resetBillableResolver();
    Billing::resolveBillableUsing(fn() => $this->createTestUser());
}

private function createTestUser()
{
    return User::factory()->create();
}

​
Advanced Configuration

Modify the table prefix in config/billing.php:
'table_prefix' => 'my_custom_billing_',
Then re-publish and run migrations:
php artisan vendor:publish --tag=billing-migrations --force
php artisan migrate
You can customize how gateways are resolved:
use Eufaturo\Billing\PaymentGateways\GatewayManager;

app()->bind(GatewayManagerInterface::class, function ($app) {
    $manager = new GatewayManager();

    // Register custom gateways
    $manager->register('custom', new CustomGateway());

    return $manager;
});
Register listeners for billing events:
use Eufaturo\Billing\Subscriptions\Events\SubscriptionCreated;
use Illuminate\Support\Facades\Event;

Event::listen(SubscriptionCreated::class, function ($event) {
    // Send welcome email, trigger analytics, etc.
});

​
Configuration Checklist

After installation, ensure you’ve configured:
  • Billable resolver in AppServiceProvider
  • At least one currency
  • At least one payment gateway
  • Payment methods for your gateway
  • Environment variables (.env)
  • Billable trait on your model

​
Next Steps

Quick Start

Create your first subscription

Payment Gateways

Learn about gateway integration

Products & Plans

Set up your product catalog

Features

Configure feature entitlements