Skip to main content

​
Overview

The Payments module manages financial transactions in Nguhöe EHR. Payments are typically linked to consultations but can also be created independently. The module supports multiple payment methods and status tracking.
Payment management is restricted to Admin and Receptionist roles. These users handle billing and financial record-keeping.

​
Payment Data Model

​
Core Fields

FieldTypeDescription
patient_idforeign keyReference to patient
consultation_idforeign key (nullable)Optional link to consultation
amountdecimal(10,2)Payment amount
payment_methodstringMethod of payment
statusstringPayment status
notestextAdditional payment notes

​
Payment Methods

Cash payment - most common for clinic visits

​
Payment Statuses

​
Creating Payments

​
During Consultation

Payments are typically created automatically when a consultation includes payment information: 
// During consultation creation (ConsultationController.php:66-67)
'payment_amount' => 'nullable|numeric|min:0',
'payment_method' => 'nullable|string|in:cash,card,transfer',
The CreateConsultationAction handles automatic payment creation:
  • Creates payment record linked to consultation
  • Sets status to ‘paid’ by default
  • Links to patient and consultation

​
Independent Payment Creation

Receptionists and admins can create payments independently through the payments interface: Route: payments.store → PaymentController@store
Action: CreatePaymentAction
Endpoint: POST /payments 
// Payment validation (PaymentController.php:38-45)
$validated = $request->validate([
    'patient_id' => 'required|exists:patients,id',
    'consultation_id' => 'nullable|exists:consultations,id',
    'amount' => 'required|numeric|min:0',
    'payment_method' => 'required|string|in:cash,card,transfer',
    'status' => 'required|string|in:paid,pending,cancelled',
    'notes' => 'nullable|string',
]);

$action->execute($validated);
Payments don’t require a consultation link - useful for deposits, general charges, or administrative fees.

​
Viewing and Filtering Payments

​
Payments List

Access the complete payment history with search and filtering: Route: payments.index → PaymentController@index
Endpoint: GET /payments 
// Load payments with relationships (PaymentController.php:18)
$query = Payment::with(['patient', 'consultation'])->latest();

// Search by patient name (PaymentController.php:20-25)
if ($request->has('search')) {
    $search = $request->get('search');
    $query->whereHas('patient', function ($q) use ($search) {
        $q->where('full_name', 'like', "%{$search}%");
    });
}
The payments list displays:
  • Patient name (searchable)
  • Consultation reference (if linked)
  • Amount
  • Payment method
  • Status
  • Date
  • Notes
Search payments by patient name to quickly find specific transactions: 
// Example: Search for payments from "Juan Perez"
GET /payments?search=Juan%20Perez

​
Billing Workflows

​
Standard Consultation Payment

1

Doctor Creates Consultation

Doctor completes clinical documentation
2

Add Payment Info

Doctor or system adds payment amount and method
3

Auto-Create Payment

Payment is automatically created and linked
4

Receipt Generation

System can generate payment receipt

​
Walk-in Payment

1

Receptionist Opens Payments

Access payments module
2

Create New Payment

Click create payment
3

Select Patient

Choose patient from list
4

Enter Details

Add amount, method, and notes
5

Submit

Create payment record

​
Pending Payment Follow-up

1

Create as Pending

Mark payment status as ‘pending’
2

Patient Pays Later

Patient returns to complete payment
3

Update Status

Change status from ‘pending’ to ‘paid’
4

Add Payment Method

Record how payment was received

​
Payment Notes

The notes field supports additional context: 
'notes' => 'Pago parcial - saldo pendiente $200',
'notes' => 'Incluye estudios de laboratorio',
'notes' => 'Descuento por tercera edad aplicado',
'notes' => 'Transferencia ref: 123456789',
Use notes for:
  • Payment references
  • Partial payment tracking
  • Discounts or adjustments
  • Special arrangements
  • Receipt numbers

​
Relationships

// Payment.php relationships

// Belongs to Patient
public function patient(): BelongsTo
{
    return $this->belongsTo(Patient::class);
}

// Belongs to Consultation (optional)
public function consultation(): BelongsTo
{
    return $this->belongsTo(Consultation::class);
}
The consultation relationship uses nullable constraint, allowing payments without consultation links (database/migrations/*_payments_table.php:17).

​
Access Control

  • View all payments
  • Create new payments
  • Update payment status
  • Search and filter payments
  • Full financial access
  • View all payments
  • Create new payments
  • Update payment status
  • Search and filter payments
  • Primary role for payment management
  • Can add payment info during consultation creation
  • Cannot access payments module directly
No access to payment management (view-only access may be implemented)

​
Database Schema

CREATE TABLE payments (
    id BIGINT PRIMARY KEY,
    patient_id BIGINT NOT NULL REFERENCES patients(id) ON DELETE CASCADE,
    consultation_id BIGINT REFERENCES consultations(id) ON DELETE SET NULL,
    amount DECIMAL(10,2) NOT NULL,
    payment_method VARCHAR(255) NOT NULL,
    status VARCHAR(255) DEFAULT 'paid',
    notes TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP
);
When a consultation is deleted, the payment remains but the consultation_id is set to NULL (ON DELETE SET NULL).

​
Common Scenarios

​
Standard Consultation Fee

[
    'patient_id' => 123,
    'consultation_id' => 456,
    'amount' => 500.00,
    'payment_method' => 'cash',
    'status' => 'paid',
    'notes' => 'Consulta general',
]

​
Partial Payment

[
    'patient_id' => 123,
    'consultation_id' => 456,
    'amount' => 300.00,
    'payment_method' => 'cash',
    'status' => 'paid',
    'notes' => 'Pago parcial - saldo pendiente $200',
]

​
Administrative Fee

[
    'patient_id' => 123,
    'consultation_id' => null,
    'amount' => 50.00,
    'payment_method' => 'card',
    'status' => 'paid',
    'notes' => 'Costo de expedición de récipe duplicado',
]

​
Pending Payment

[
    'patient_id' => 123,
    'consultation_id' => 456,
    'amount' => 800.00,
    'payment_method' => 'transfer',
    'status' => 'pending',
    'notes' => 'Esperando confirmación de transferencia bancaria',
]

​
Reporting and Analytics

Payment data supports financial reporting:
  • Daily/weekly/monthly revenue
  • Payment method distribution
  • Pending payments tracking
  • Patient payment history
  • Consultation revenue analysis
The reports module uses payment data for financial dashboards and analytics (routes/web.php:54).

​
Best Practices

Link to Consultations

Always link payments to consultations when applicable for tracking

Accurate Status

Update payment status promptly when pending payments are received

Clear Notes

Add meaningful notes for reference and audit purposes

Consistent Methods

Use standardized payment method codes for reporting
Payments use soft deletes to maintain financial audit trails. Never permanently delete payment records.

Build docs developers (and LLMs) love

Get started for freeTalk to us