CitaBox handles the full billing lifecycle for every consultation: generating an invoice, recording the payment method, and submitting the electronic bill to Costa Rica’s Ministerio de Hacienda. Each invoice is linked to a patient and optionally to a specific appointment, which lets the receptionist close out the day’s completed consultations in a single workflow from their dashboard.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/FerchoSG/healthcare-web/llms.txt
Use this file to discover all available pages before exploring further.
Invoice fields
| Field | Type | Description |
|---|---|---|
patient_id | string (UUID) | The patient being billed. |
appointment_id | string (UUID) | The appointment this invoice covers. Optional but recommended for traceability. |
total_amount | number | Total amount charged, in Costa Rican colones (CRC). Derived from the service price when available. |
service_description | string | Free-text description of the service rendered. Defaults to the appointment reason or service name. |
payment_status | PAID / UNPAID / PARTIAL | Current payment state of the invoice. |
payment_method | SINPE_MOVIL / TARJETA / EFECTIVO / TRANSFERENCIA | How the patient paid. |
payment_reference | string | Transaction reference number (e.g., SINPE confirmation code). |
paid_amount | number | Actual amount received. Used when payment_status is PARTIAL. |
paid_at | ISO timestamp | Date and time payment was recorded. Set automatically when saving with a non-UNPAID status. |
notes | string | Internal notes for the billing record. |
Hacienda integration fields
CitaBox submits invoices to the Ministerio de Hacienda electronic billing system. The following fields are managed by the system after submission:| Field | Description |
|---|---|
hacienda_consecutive | Sequential invoice number assigned by Hacienda upon acceptance. |
numeric_key | 50-digit unique key (clave numérica) generated per invoice. |
hacienda_status | Current state with Hacienda: DRAFT, ACCEPTED, or REJECTED. |
pdf_url | URL to the official PDF version of the accepted electronic invoice. |
xml_url | URL to the XML document submitted to and accepted by Hacienda. |
Billing workflow after a consultation
Confirm the consultation is completed
In the receptionist dashboard, check the “Pendientes de cierre” panel. It lists all appointments with status
COMPLETED that do not yet have a fully paid invoice.Open the checkout dialog
Click “Registrar cobro” next to the patient’s appointment. If an invoice already exists (e.g., marked as
UNPAID earlier), the button shows “Editar cobro” and pre-populates the form with the existing values.Select payment status and method
Choose the
payment_status (Pagado, Parcial, or Pendiente) and the payment_method. If the patient paid in full, select Pagado. For partial payments, select Parcial and enter the paid_amount.Enter the payment reference
For SINPE Móvil and transfers, paste the transaction confirmation number in the reference field. For card payments, enter the terminal voucher number.
Payment methods
SINPE Móvil
SINPE Móvil
Costa Rica’s instant mobile payment network operated by BCCR. The patient sends the payment to the clinic’s registered SINPE number. The receptionist enters the SINPE confirmation number as the
payment_reference. This is the most common payment method for in-clinic consultations.TARJETA — Card
TARJETA — Card
Credit or debit card payment processed through a point-of-sale terminal. Enter the terminal voucher or approval code as the
payment_reference.EFECTIVO — Cash
EFECTIVO — Cash
Cash payment. No external reference is required, though a
payment_reference can be used for internal receipt tracking. The paid_amount field is particularly useful here to record the exact amount tendered.TRANSFERENCIA — Bank transfer
TRANSFERENCIA — Bank transfer
Direct bank transfer (SINPE Nacional or international wire). Enter the IBAN or transfer confirmation number as the
payment_reference. Transfers may take time to confirm so the invoice can be saved as PARTIAL or UNPAID until the credit appears.Listing and filtering invoices
All invoices are fetched fromGET /billing/invoices. The receptionist dashboard loads them on startup alongside the day’s appointments to populate the pending-closure panel. The full invoice list (including historical invoices) is accessible from the billing section of the admin area.
Each invoice in the list includes the linked patient summary and, when present, the associated appointment’s start time and status — making it straightforward to reconcile billing against the day’s schedule.