Module Offline Payments Laravel Package

Getting Started

1. Install into an Akaunting host app — this is a module, not a standalone package. Drop it into modules/OfflinePayments (or composer require akaunting/module-offline-payments if you use the private repo), then run:

   php artisan module:enable offline-payments
   php artisan module:publish offline-payments
   php artisan optimize:clear
   

   Enabling is the step people most often skip; without it, module.json isn't registered and the payment methods never appear.

2. Look here first — module.json (slug, version, providers), Providers/Main.php (config merge, view/translation namespace), Providers/Event.php (event listeners), Config/payments.php (the actual list of offline methods exposed to the UI), and Routes/ (admin.php for settings screens, portal.php for customer-facing use).

3. First useful scenario — open any invoice in the Akaunting UI → Add Payment → the modal's payment method dropdown now includes the offline methods this module registers (typically Cash, Bank Transfer, Cheque, Other). Recording one writes a Payment row against the invoice with payment_method set to the configured slug; no gateway is contacted. That's the whole value proposition: an audit trail for money received outside the app.

Implementation Patterns

• Consuming the methods in your own code. Don't hardcode 'cash' / 'bank_transfer'. Read from the merged config (config('payments.methods') or the module's config key) so future methods added via settings automatically show up in your reports and dropdowns.
• Adding a custom offline method. The cleanest path is not to edit this package (updates will wipe it). Instead, publish its config and append your method, or create a one-file sibling module that merges an extra entry into payments.methods. If you need extra fields (e.g. cheque number), listen to the payment-created event and store them in a related table rather than altering the module's migration.
• Post-payment hooks. Register listeners on Akaunting's invoice/payment events (App\Events\Invoice\PaymentCreated, PaymentDeleted) inside your own module's Providers/Event.php. Offline payments still fire these, which makes them a good integration point for ERP sync, receipting, or ledger exports — you get "payment happened" signals without dealing with a gateway callback.
• Overriding views. The module registers a view namespace (e.g. offline-payments::). Publish views and override under resources/views/vendor/offline-payments/ in the host app to relabel methods, reformat the settings screen, or hide methods per company.
• Settings screen integration. The admin routes under Routes/admin.php are the place to hook extra configuration (default method, per-company toggles). Follow the existing controller/request structure so permission checks and validation stay consistent.
• Testing flows locally. Seed a company, customer, invoice, then POST to the add-payment endpoint via the portal route. Because there's no external call, integration tests are fast and deterministic — a good candidate for feature tests that assert ledger totals after offline payments.

Gotchas and Tips

• No actual processing. This module records a payment; it does not validate, authorize, or reconcile anything. If you expected webhooks or status transitions, you're in the wrong package — use a real gateway module.
• Module enablement and cache. After install/update, module:enable + php artisan optimize:clear is mandatory. A stale bootstrap/cache or config cache is the #1 reason methods "disappear" from the dropdown.
• Slug/key mismatches. Payment methods are stored on the Payment record by their config key. Renaming a method's key later will orphan historical rows — keep keys stable and only change labels/translations.
• Translations. The module ships language files under Resources/lang (or lang/), keyed by method. If a method shows as a raw key in the UI, the host locale file is missing or the module's namespace isn't registered.
• Multi-company behaviour. Akaunting's per-company scoping applies to the payments created, not necessarily to the method list. If you need per-company method availability, implement it in the controller/listener layer rather than assuming the config is company-aware.
• Permissions. Any new admin route you add must be wired into the host's permission/ACL system; module routes without permission entries silently 403 for non-admins.
• Compatibility pinning. Last release 2024-04-30, very low star count — treat it as a thin reference implementation. Pin the version in composer.json and re-test after each Akaunting core upgrade, since module APIs (providers, event names) shift between major versions.
• Extension point of last resort. If you need anything substantial, copy the module's skeleton into your own namespace instead of forking it — its real value is as a template for "how an Akaunting payment module is wired," not as a long-lived dependency.