Add Paystack, Flutterwave, and Hubtel for encounter billing.

Clinics on Pro/Enterprise can connect their own gateway in Integrations and collect card or MoMo on bills with 0% Ladill fee, while cash payments and balance totals stay correct for pending checkouts.

app/Http/Controllers/Api/BillController.php

@@ -58,12 +58,14 @@ class BillController extends Controller
         $this->authorizeAbility($request, 'payments.manage');
         $this->authorizeBill($request, $bill);
 
+        $manualMethods = array_keys(collect(config('care.payment_methods', []))->except(['gateway'])->all());
+
         $payment = $this->bills->recordPayment(
             $bill,
             $this->ownerRef($request),
             $request->validate([
                 'amount_minor' => ['required', 'integer', 'min:1'],
-                'method' => ['required', 'string', 'in:'.implode(',', array_keys(config('care.payment_methods')))],
+                'method' => ['required', 'string', 'in:'.implode(',', $manualMethods)],
                 'reference' => ['nullable', 'string', 'max:100'],
             ]),
             $this->ownerRef($request),

app/Http/Controllers/Care/BillController.php

@@ -8,9 +8,11 @@ use App\Models\Bill;
 use App\Models\Visit;
 use App\Services\Care\BillService;
 use App\Services\Care\OrganizationResolver;
+use App\Services\Payments\MerchantGatewayService;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
+use RuntimeException;
 
 class BillController extends Controller
 {
@@ -18,6 +20,7 @@ class BillController extends Controller
 
     public function __construct(
         protected BillService $bills,
+        protected MerchantGatewayService $gateway,
     ) {}
 
     public function index(Request $request): View
@@ -62,14 +65,26 @@ class BillController extends Controller
             ->can($this->member($request), 'bills.manage');
         $canPay = app(\App\Services\Care\CarePermissions::class)
             ->can($this->member($request), 'payments.manage');
+        $organization = $this->organization($request);
+        $gatewayConfigured = $this->gateway->isConfigured($organization);
+        $gateway = $this->gateway->settingFor($organization);
+
+        // Manual record form excludes gateway method (online checkout is separate).
+        $manualMethods = collect(config('care.payment_methods', []))
+            ->except(['gateway'])
+            ->all();
 
         return view('care.bills.show', [
             'bill' => $bill,
             'statuses' => config('care.bill_statuses'),
             'lineTypes' => config('care.bill_line_types'),
             'paymentMethods' => config('care.payment_methods'),
+            'manualPaymentMethods' => $manualMethods,
             'canManage' => $canManage,
             'canPay' => $canPay,
+            'gatewayConfigured' => $gatewayConfigured,
+            'gatewayProvider' => $gateway?->provider,
+            'gatewayLabels' => config('care.payment_gateways'),
         ]);
     }
 
@@ -119,12 +134,14 @@ class BillController extends Controller
         $this->authorizeAbility($request, 'payments.manage');
         $this->authorizeBill($request, $bill);
 
+        $manualMethods = array_keys(collect(config('care.payment_methods', []))->except(['gateway'])->all());
+
         $this->bills->recordPayment(
             $bill,
             $this->ownerRef($request),
             $request->validate([
                 'amount_minor' => ['required', 'integer', 'min:1'],
-                'method' => ['required', 'string', 'in:'.implode(',', array_keys(config('care.payment_methods')))],
+                'method' => ['required', 'string', 'in:'.implode(',', $manualMethods)],
                 'reference' => ['nullable', 'string', 'max:100'],
                 'notes' => ['nullable', 'string', 'max:500'],
             ]),
@@ -134,6 +151,66 @@ class BillController extends Controller
         return back()->with('success', 'Payment recorded.');
     }
 
+    public function startGatewayPayment(Request $request, Bill $bill): RedirectResponse
+    {
+        $this->authorizeAbility($request, 'payments.manage');
+        $this->authorizeBill($request, $bill);
+
+        $validated = $request->validate([
+            'amount_minor' => ['nullable', 'integer', 'min:1'],
+        ]);
+
+        $amount = (int) ($validated['amount_minor'] ?? $bill->balance_minor);
+
+        try {
+            $result = $this->bills->startGatewayPayment(
+                $bill->loadMissing('patient'),
+                $this->organization($request),
+                $this->ownerRef($request),
+                $amount,
+                $request->user(),
+                $this->ownerRef($request),
+            );
+        } catch (RuntimeException|\InvalidArgumentException $e) {
+            return back()->with('error', $e->getMessage());
+        }
+
+        return redirect()->away($result['checkout_url']);
+    }
+
+    public function paymentCallback(Request $request): RedirectResponse|View
+    {
+        $reference = trim((string) (
+            $request->query('reference')
+            ?: $request->query('tx_ref')
+            ?: $request->query('clientReference')
+            ?: ''
+        ));
+
+        if ($reference === '') {
+            return view('care.bills.payment-return', [
+                'redirect' => route('care.bills.index'),
+            ]);
+        }
+
+        try {
+            $payment = $this->bills->completeGatewayPayment($reference);
+        } catch (\Throwable) {
+            session()->flash('error', 'Payment could not be verified. If the customer was charged, re-check the bill or contact support with reference '.$reference.'.');
+
+            return view('care.bills.payment-return', [
+                'redirect' => route('care.bills.index'),
+            ]);
+        }
+
+        $bill = $payment->bill;
+        session()->flash('success', 'Online payment recorded for '.$bill->invoice_number.'.');
+
+        return view('care.bills.payment-return', [
+            'redirect' => route('care.bills.show', $bill),
+        ]);
+    }
+
     public function void(Request $request, Bill $bill): RedirectResponse
     {
         $this->authorizeAbility($request, 'bills.manage');

app/Http/Controllers/Care/IntegrationsController.php

@@ -4,21 +4,29 @@ namespace App\Http\Controllers\Care;
 
 use App\Http\Controllers\Controller;
 use App\Http\Controllers\Care\Concerns\ScopesToAccount;
+use App\Models\PaymentGatewaySetting;
 use App\Services\Care\AuditLogger;
 use App\Services\Care\CarePermissions;
+use App\Services\Care\PlanService;
 use App\Services\Messaging\CustomerSmsClient;
 use App\Services\Messaging\MessagingCredentialsService;
+use App\Services\Payments\MerchantGatewayService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
+use Illuminate\Validation\Rule;
 use Illuminate\View\View;
 
 class IntegrationsController extends Controller
 {
     use ScopesToAccount;
 
-    public function edit(Request $request, MessagingCredentialsService $credentials): View
-    {
+    public function edit(
+        Request $request,
+        MessagingCredentialsService $credentials,
+        MerchantGatewayService $gateway,
+        PlanService $plans,
+    ): View {
         $this->authorizeAbility($request, 'settings.view');
         $organization = $this->organization($request);
         $canManage = app(CarePermissions::class)->can($this->member($request), 'settings.manage');
@@ -27,6 +35,9 @@ class IntegrationsController extends Controller
             'organization' => $organization,
             'canManage' => $canManage,
             'credential' => $credentials->forOrganization($organization),
+            'gateway' => $gateway->settingFor($organization),
+            'canUsePaymentGateway' => $plans->canUsePaymentGateway($organization),
+            'gatewayLabels' => config('care.payment_gateways'),
         ]);
     }
 
@@ -149,4 +160,93 @@ class IntegrationsController extends Controller
 
         return response()->json($result['data'] ?? []);
     }
+
+    public function saveGateway(Request $request, PlanService $plans): RedirectResponse
+    {
+        $this->authorizeAbility($request, 'settings.manage');
+        $organization = $this->organization($request);
+
+        if (! $plans->canUsePaymentGateway($organization)) {
+            return back()->with('error', 'Connecting your own payment gateway requires Care Pro or Enterprise.');
+        }
+
+        $data = $request->validate([
+            'gateway_provider' => ['required', 'string', Rule::in(PaymentGatewaySetting::providers())],
+            'gateway_public_key' => ['nullable', 'string', 'max:2000'],
+            'gateway_secret_key' => ['nullable', 'string', 'max:2000'],
+            'gateway_webhook_secret' => ['nullable', 'string', 'max:2000'],
+            'gateway_is_active' => ['nullable', 'boolean'],
+        ]);
+
+        $existing = PaymentGatewaySetting::query()
+            ->where('organization_id', $organization->id)
+            ->first();
+
+        $publicKey = trim((string) ($data['gateway_public_key'] ?? ''));
+        $secretKey = trim((string) ($data['gateway_secret_key'] ?? ''));
+        $webhookSecret = trim((string) ($data['gateway_webhook_secret'] ?? ''));
+
+        $attributes = [
+            'owner_ref' => $this->ownerRef($request),
+            'provider' => $data['gateway_provider'],
+            'is_active' => $request->boolean('gateway_is_active', true),
+        ];
+
+        // Blank fields keep previously stored encrypted credentials.
+        if ($publicKey !== '') {
+            $attributes['public_key'] = $publicKey;
+        }
+        if ($secretKey !== '') {
+            $attributes['secret_key'] = $secretKey;
+        }
+        if ($webhookSecret !== '') {
+            $attributes['webhook_secret'] = $webhookSecret;
+        }
+
+        if ($existing === null && $secretKey === '') {
+            return back()->withInput()->with('error', 'Secret / API key is required to connect a payment gateway.');
+        }
+
+        if ($data['gateway_provider'] === PaymentGatewaySetting::PROVIDER_HUBTEL && $publicKey === '' && ! $existing?->public_key) {
+            return back()->withInput()->with('error', 'Hubtel requires a merchant account number (public key field).');
+        }
+
+        PaymentGatewaySetting::query()->updateOrCreate(
+            ['organization_id' => $organization->id],
+            $attributes,
+        );
+
+        AuditLogger::record(
+            $this->ownerRef($request),
+            'integrations.gateway_connected',
+            $organization->id,
+            $this->ownerRef($request),
+            \App\Models\Organization::class,
+            $organization->id,
+            ['provider' => $data['gateway_provider']],
+        );
+
+        return back()->with('success', 'Payment gateway saved.');
+    }
+
+    public function disconnectGateway(Request $request, PlanService $plans): RedirectResponse
+    {
+        $this->authorizeAbility($request, 'settings.manage');
+        $organization = $this->organization($request);
+
+        PaymentGatewaySetting::query()
+            ->where('organization_id', $organization->id)
+            ->delete();
+
+        AuditLogger::record(
+            $this->ownerRef($request),
+            'integrations.gateway_disconnected',
+            $organization->id,
+            $this->ownerRef($request),
+            \App\Models\Organization::class,
+            $organization->id,
+        );
+
+        return back()->with('success', 'Payment gateway disconnected.');
+    }
 }