README

Billing module for Laravel with ports and adapters architecture.

Installation

composer require andmarruda/billing-module

Laravel package auto-discovery loads Andmarruda\BillingModule\BillingModuleServiceProvider.

Layers

• UseCases/: application workflows.
• Ports/: repository and service contracts.
• Infrastructure/: adapter implementations.
• Http/: controllers, requests, resources and routes.
• Events/, Listeners/, Console/Commands/: async workflows and cron entry points.

Implemented Scope

• One-time payments.
• Recurring billing managed by module cron flows (not Stripe subscriptions product).
• Stripe webhook processing with signature validation and idempotent event storage.
• NFSe integration adapter (FocusNFe package integration point).
• Reconciliation and retry commands.
• Optional coin credit flow for MVPs (ledger + user balance) on PaymentSucceeded.

Routes

• POST /billing/payments/one-time
• POST /billing/subscriptions/recurring
• POST /billing/subscriptions/{id}/cancel
• GET /billing/invoices/{id}
• POST /billing/webhooks/stripe
• GET /billing/subscriptions/current when billing.stores.enabled = true
• POST /billing/webhooks/google-play when billing.stores.enabled = true
• POST /billing/webhooks/app-store when billing.stores.enabled = true

Commands

• billing:renew-subscriptions
• billing:retry-failed-payments
• billing:sync-nfse
• billing:reconcile
• billing:expire-store-subscriptions

Scheduling is configured by Config/billing.php under crons.

Coins (MVP)

• Enable with billing.coins.enabled = true.
• Configure monthly coin recharge by plan with billing.coins.monthly_plan_credits.
• You can also credit coins in one-time payments by passing metadata.coins.
• Credits are idempotent per payment (coin_ledger_entries.payment_id is unique).

Route Middleware

• Configure API middleware via billing.route_middleware (string or array).
• Configure webhook middleware independently via billing.webhook_middleware.
• Example:
  • billing.route_middleware = ['auth:sanctum']
  • billing.webhook_middleware = ['throttle:60,1']

NFSe Async Emission

• InvoiceIssued triggers IssueNfseForInvoice, which is queueable (ShouldQueue).
• Queue processing strategy stays in the host app (driver/workers/supervision).

Stripe Webhook Security

• Signature validation supports timestamp tolerance through:
  • billing.stripe.webhook_tolerance_seconds (default 300).

Store-Driven Subscriptions

• Enable mobile store flows with billing.stores.enabled = true.
• Configure product mapping in billing.stores.google_play.product_map and billing.stores.app_store.product_map.
• Bind concrete implementations for:
  • Andmarruda\BillingModule\Ports\Services\GooglePlayWebhookVerifierInterface
  • Andmarruda\BillingModule\Ports\Services\AppStoreNotificationVerifierInterface
• Default verifier implementations are null adapters and intentionally do not accept webhooks.

Observability Events

• Andmarruda\BillingModule\Events\NfseIssueFailed
  • Dispatched when NFSe issuance returns error, misses external_id, or provider call throws.
• Andmarruda\BillingModule\Events\WebhookProcessingFailed
  • Dispatched when webhook event persistence fails for a non-duplicate reason.