Tax Configuration

STRIPE_TAX_ENABLED=true

'tax' => [
    'provider' => env('TAX_PROVIDER', 'stripe_tax'),

    'stripe_tax' => [
        'enabled' => env('STRIPE_TAX_ENABLED', false),
    ],
],

interface TaxProviderInterface
{
    /**
     * Calculate tax for a given amount and context.
     * Tax is calculated in the same currency as the amount.
     */
    public function calculate(Money $amount, TaxContext $context): TaxCalculation;

    /**
     * Validate a VAT number with the tax authority.
     */
    public function validateVatNumber(string $vatNumber, string $countryCode): bool;

    /**
     * Determine if reverse charge applies for B2B transactions.
     */
    public function isReverseCharge(TaxContext $context): bool;

    /**
     * Get the standard tax rate for a jurisdiction.
     *
     * @param  string  $countryCode  ISO 3166-1 alpha-2 country code
     * @param  string|null  $region  State/province for US, CA, etc.
     * @return float Tax rate as decimal (e.g., 0.20 for 20%)
     */
    public function getTaxRate(string $countryCode, ?string $region = null): float;
}

final readonly class TaxContext
{
    public function __construct(
        public string $customerCountry,        // ISO 3166-1 alpha-2 (e.g., 'FR', 'US')
        public ?string $customerPostalCode = null,
        public ?string $customerState = null,   // For US, CA, AU, etc.
        public ?string $vatNumber = null,        // EU VAT number for B2B
        public ?string $taxCode = null,          // Stripe product tax code
        public string $reference = 'subscription',
    ) {}
}

final readonly class TaxCalculation
{
    public function __construct(
        public Money $taxableAmount,           // Amount before tax
        public Money $taxAmount,               // Calculated tax
        public Money $totalWithTax,            // Amount + tax
        public float $rate,                    // Rate as decimal (0.20 = 20%)
        public string $jurisdiction,           // Tax jurisdiction code
        public string $taxType,                // e.g., 'vat', 'sales_tax', 'gst'
        public bool $isReverseCharge,          // true for B2B intra-EU
        public ?string $providerCalculationId = null,  // Stripe calculation ID
    ) {}
}

final class TaxBreakdownMapper
{
    /**
     * Map Stripe invoice tax breakdown to TaxRecordDraft array.
     *
     * @return TaxRecordDraft[]
     */
    public function map(StripeObject $stripeInvoice): array
}

final readonly class TaxRecordDraft
{
    public function __construct(
        public string $taxType,             // 'vat', 'sales_tax', 'gst'
        public string $jurisdiction,         // Country/region code
        public float $rate,                  // Decimal rate (0.200000)
        public int $taxableAmountCents,      // Taxable base in minor units
        public int $taxAmountCents,          // Tax amount in minor units
        public ?string $stripeCalculationId = null,
    ) {}
}

BILLING_COMPANY_NAME=Your Company
BILLING_COMPANY_ADDRESS=123 Main Street
BILLING_COMPANY_CITY=Paris
BILLING_COMPANY_POSTAL_CODE=75001
BILLING_COMPANY_COUNTRY=FR
BILLING_COMPANY_VAT_NUMBER=FR12345678901

'company' => [
    'name' => env('BILLING_COMPANY_NAME', 'Your Company'),
    'address' => env('BILLING_COMPANY_ADDRESS', ''),
    'city' => env('BILLING_COMPANY_CITY', ''),
    'postal_code' => env('BILLING_COMPANY_POSTAL_CODE', ''),
    'country' => env('BILLING_COMPANY_COUNTRY', 'FR'),
    'vat_number' => env('BILLING_COMPANY_VAT_NUMBER', ''),
],

'invoices' => [
    'retention_years' => env('INVOICE_RETENTION_YEARS', 10),
    'storage_disk' => env('INVOICE_STORAGE_DISK', 'local'),
    'legal_mentions' => [
        'default' => env('INVOICE_LEGAL_MENTION', ''),
    ],
],