# Inward Online Payment API ## Overview The Inward Online Payment API (`/api/apiInward`) enables external patient-facing websites or mobile applications to: - List inpatient admissions with outstanding balances - Look up admissions by patient or guardian phone number - Validate an admission before payment - Record online payments against inpatient bills The website is responsible for OTP verification externally. Once a phone number is verified, it can be passed to this API to retrieve matching admissions. > **Looking for a general admission search instead?** This API's `/admissions` endpoints only return admissions with outstanding balances (a payment-collection worklist). For general search — currently admitted patients, or a patient's full admission history by phone/MRN/BHT/name/NIC — see the [Inward Admission Search API](Inward-Admission-Search-API). --- ## Authentication All endpoints require an API key passed in the `Finance` HTTP header. ``` Finance: ``` API keys are managed in the HMIS Admin panel under **API Key Management**. Keys must be: - Active (not retired) - Activated - Not expired If authentication fails, all endpoints return: ```json {"error": "1", "error_description": "Unauthorized"} ``` --- ## Endpoints ### 1. List Admissions with Outstanding Balance ``` GET /api/apiInward/admissions ``` Returns up to 20 admissions that are either: - Not yet finalized/discharged (still admitted), OR - Finalized and discharged but with a remaining balance due **Headers:** | Header | Required | Description | |--------|----------|-------------| | Finance | Yes | API key | **Response (success):** ```json { "admission": [ { "patient_encounter_id": 12345, "bht_no": "BHT-2024-001", "patient_mrn": "P001234", "patient_name": "John Smith", "patient_home_phone": "0112345678", "patient_mobile": "0771234567", "patient_nic": "123456789V", "net_total": 50000.0, "paid_amount": 20000.0, "balance": 30000.0 } ], "error": "0", "error_description": "" } ``` **Response (no data):** ```json {"admission": "", "error": "1", "error_description": "No Data."} ``` --- ### 2. Find Admissions by Phone Number ``` GET /api/apiInward/admissions/byPhone/{phone} ``` Searches for admissions where the phone number matches **any** of: - Patient mobile number - Patient home phone number - Guardian mobile number - Guardian home phone number Use this after OTP verification to retrieve admissions for the verified phone. **Path Parameters:** | Parameter | Description | |-----------|-------------| | phone | Verified phone number (e.g., `0771234567`) | **Headers:** | Header | Required | Description | |--------|----------|-------------| | Finance | Yes | API key | **Response (success):** ```json { "admission": [ { "patient_encounter_id": 12345, "bht_no": "BHT-2024-001", "patient_mrn": "P001234", "patient_name": "John Smith", "net_total": 50000.0, "paid_amount": 20000.0, "balance": 30000.0 } ], "error": "0", "error_description": "" } ``` **Response (no match):** ```json {"admission": "", "error": "1", "error_description": "No Data."} ``` --- ### 3. Validate Admission ``` GET /api/apiInward/validateAdmission/{bht_no}/{phone} ``` Checks whether a BHT number is valid for payment **and** that the given phone number is associated with the patient or guardian. Used to confirm the patient before showing the payment screen. **Path Parameters:** | Parameter | Description | |-----------|-------------| | bht_no | BHT (Bed Head Ticket) number | | phone | Patient or guardian phone number | **Headers:** | Header | Required | Description | |--------|----------|-------------| | Finance | Yes | API key | **Response (valid):** ```json {"error": "0", "error_description": "Valid"} ``` **Response (not valid):** ```json {"error": "1", "error_description": "Not Valid"} ``` --- ### 4. List Banks ``` GET /api/apiInward/banks ``` Returns all active bank institutions registered in HMIS. Used to populate the bank selector on the payment form. **Headers:** | Header | Required | Description | |--------|----------|-------------| | Finance | Yes | API key | **Response (success):** ```json { "bank": [ {"bank_id": 119179, "bank_name": "Commercial Bank"}, {"bank_id": 62127, "bank_name": "Bank Of Ceylon"} ], "error": "0", "error_description": "" } ``` --- ### 5. Submit Payment (POST) ``` POST /api/apiInward/payment Content-Type: application/json ``` Records an online payment against a patient admission. Creates both the inward payment bill **and** a payment table record. **Headers:** | Header | Required | Description | |--------|----------|-------------| | Finance | Yes | API key | | Content-Type | Yes | `application/json` | **Request Body:** ```json { "bht_no": "BHT-2024-001", "bank_id": 119179, "reference_no": "TXN20240101001", "amount": 15000.0, "payment_date": "2024-01-01 10:30:00" } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | bht_no | string | Yes | Patient BHT number | | bank_id | long | Yes | Bank institution ID (from `/banks`) | | reference_no | string | Yes | Online transaction reference number | | amount | double | Yes | Payment amount (must be > 0) | | payment_date | string | No | Date in `yyyy-MM-dd HH:mm:ss` format; defaults to current time | **Response (success):** ```json { "bill": { "bill_no": "INWPAY-2024-0001", "bht_no": "BHT-2024-001", "amount": 15000.0, "reference_no": "TXN20240101001" }, "error": "0", "error_description": "" } ``` **Error responses:** ```json {"bill": "", "error": "1", "error_description": "Admission not found."} {"bill": "", "error": "1", "error_description": "Bank not found."} {"bill": "", "error": "1", "error_description": "Amount must be greater than zero."} {"bill": "", "error": "1", "error_description": "Payment Not Done."} ``` --- ### 6. Legacy GET Payment (Deprecated) ``` GET /api/apiInward/payment/{bht_no}/{bank_id}/{credit_card_ref}/{amount} ``` **Kept for backward compatibility only.** Use the POST endpoint for new integrations. This endpoint does **not** record to the payment table. --- ## Error Codes | `error` value | Meaning | |---------------|---------| | `"0"` | Success | | `"1"` | Error (see `error_description`) | Common `error_description` values: - `"Unauthorized"` — missing or invalid API key - `"No Data."` — query returned no results - `"Admission not found."` — BHT number not found - `"Bank not found."` — bank_id not found - `"Amount must be greater than zero."` — invalid amount - `"Payment Not Done."` — bill creation failed - `"Invalid Argument."` — unexpected exception (check server logs) --- ## Integration Notes ### Recommended Workflow 1. Patient visits the hospital website and enters their phone number. 2. Website sends OTP to the phone and verifies it. 3. After verification, call `GET /admissions/byPhone/{phone}` to list the patient's admissions. 4. Patient selects the admission and amount to pay. 5. Call `GET /validateAdmission/{bht_no}/{phone}` to confirm the admission is valid before proceeding. 6. Call `GET /banks` to populate the bank dropdown. 7. Patient completes online payment on the bank gateway. 8. After successful gateway response, call `POST /payment` with the transaction details. ### Phone Number Matching The `byPhone` and `validateAdmission` endpoints match against four phone fields: - `patient.person.mobile` - `patient.person.phone` (home) - `guardian.mobile` - `guardian.phone` This ensures guardians paying on behalf of patients can also look up the admission. ### Payment Recording The `POST /payment` endpoint correctly records payment to both: - The `bill` table (inward payment bill, type `InwardPaymentBill`) - The `payment` table (via `PaymentService.createPayment` with `OnlineSettlement` method) This allows reconciliation in the HMIS cashier and financial reports.