Inward Online Payment API - hmislk/hmis GitHub Wiki

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.

Authentication

All endpoints require an API key passed in the Finance HTTP header.

Finance: <your-api-key>

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:

{"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):

{
  "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):

{"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):

{
  "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):

{"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):

{"error": "0", "error_description": "Valid"}

Response (not valid):

{"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):

{
  "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:

{
  "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):

{
  "bill": {
    "bill_no": "INWPAY-2024-0001",
    "bht_no": "BHT-2024-001",
    "amount": 15000.0,
    "reference_no": "TXN20240101001"
  },
  "error": "0",
  "error_description": ""
}

Error responses:

{"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.