Process Docs

Copy page

Biometrics Consent Process Guide

1. Overview: Biometrics as the Primary Consent Method

Biometrics is the primary method for verifying patient identity and obtaining consent before starting a visit, creating a preauth, or discharging a patient. Most facilities are required to use biometrics - the patient's fingerprint is captured and matched against their SHA-registered prints to provide consent.

OTP is a fallback method for patients who cannot use biometrics. To use OTP, a patient must first be whitelisted through a formal request process reviewed by SHA. See:

• OTP Whitelist Request - how to request OTP access for a patient
• Get OTP Whitelist Request - how to check whitelist status

The biometrics mechanism has two components that work together:

1. Hardware Server - A Windows application installed on the workstation that communicates directly with the biometric device and exposes a local API at http://localhost:18065.
2. Biometrics Authorization API - The POST /api/v1/claims/authorize endpoint creates an authorization and returns an iframe link for the capture and matching process.

---

2. Hardware Server Setup

The Hardware Server must be installed and running on the workstation where the biometric device is connected before any biometrics capture can take place.

2.1. What the Hardware Server Does

The Hardware Server is a local Windows service that bridges web-based systems like SHA with biometric hardware - fingerprint scanners and NFC card readers - over HTTP and WebSocket. It:

• Discovers connected fingerprint scanners (Digital Persona, SecuGen, BioMini, ZKTeco) and NFC readers (ACS ACR1251/1252)
• Exposes them through a REST API
• Pushes real-time device and reader events over WebSocket (/ws/devices)
• Handles authentication, encryption of biometric data, and syncs devices and credentials with the remote identity backend

2.2. Installation

1. Download the Hardware Server .exe installer (provided separately by SHA).
2. Install it on the Windows workstation that has the biometric device connected.
3. Launch the application - it starts a background service on localhost:18065 that continues running even if the application window is closed.
4. Login using your biometrics agent credentials.

2.3. Verify the Service is Running

Call the Hardware Server status endpoint:

Code
 
GET http://localhost:18065/status

Example response:

Code
 
{
  "workstationID": "WS-12345",
  "devices": [
    {
      "deviceId": "DEV-001",
      "status": "connected",
      "type": "fingerprint"
    }
  ]
}

Key fields:

• workstationID - Required field in POST /api/v1/claims/authorize
• devices - List of detected biometric devices; if empty or all disconnected, check the USB connection

2.4. Connecting the Device

• Plug the biometric fingerprint device into the workstation via USB.
• Recheck /status - the device should now appear in the devices array with a connected status.
• Run a test capture from the Hardware Server application interface to confirm the device can read fingerprints before going live.

2.5. Hardware Server Troubleshooting

Problem	Resolution
localhost:18065/status is unreachable	The background service is not running. Open the Hardware Server application and click "Restart Service", then retry /status.
Device not in devices list	Check USB connection. Plug in device while app is running and retry /status.
Test capture fails	Verify device is correctly connected; restart service and retry.

---

3. Biometrics Authorization Flow

Once the Hardware Server is set up and running, follow this flow to obtain biometrics consent.

3.1. Step 1 - Create an Authorization

Call POST /api/v1/claims/authorize with biometrics-specific fields:

• workstationID (from GET http://localhost:18065/status)
• Biometrics agent National ID
• Patient beneficiary CR ID
• Relevant claim and service identifiers

The system creates an authorization in PENDING status and returns an iframe link in the response.

3.2. Step 2 - Render the iframe

Embed the iframe URL in your application's UI. The iframe:

• Detects whether a biometric device is connected (via Hardware Server)
• Shows the patient's available registered fingerprints
• Displays a "Start" button to begin the capture process
• Expires in 10 minutes - the fingerprint capture must complete within this window

3.3. Step 3 - Fingerprint Capture and Matching

1. The operator or patient clicks the Start button on the iframe.
2. The biometric device lights up and is ready to capture.
3. The patient places their finger on the device.
4. The iframe captures the print and attempts to match it against the patient's registered prints.
5. The iframe displays real-time feedback on the capture and matching result.

On success: Authorization transitions from PENDING to AUTHORIZED (standard visit) or AUTHORIZED_PENDING_VISIT (elective preauth pre-visit).

On failure: The iframe shows the rejection and prompts a retry. Up to 3 retry attempts are allowed. If all 3 fail, the authorization transitions to REJECTED status. At this point you must create a new authorization and begin again from Step 1.

3.4. Step 4 - Use the Authorization

Once the authorization is in AUTHORIZED or AUTHORIZED_PENDING_VISIT status, it can be used:

Use case	Field to include
Create a standard visit (POST /api/v1/claims/visit)	auth_guid (the GUID from the authorization object) instead of otp
Create an elective preauth (POST /api/v1/preauths)	token from the authorization object as consent_token
Discharge a patient	auth_guid instead of otp in the discharge endpoint

---

4. Authorization Status Reference

Status	Meaning
PENDING	Authorization created; waiting for successful fingerprint match
AUTHORIZED	Fingerprint matched; ready for standard visit or discharge
AUTHORIZED_PENDING_VISIT	Fingerprint matched (elective); waiting for visit creation after preauth approval
REJECTED	All 3 retry attempts failed; create a new authorization to try again

---

5. Troubleshooting Authorization Issues

iframe Expired Before Matching

The iframe is only valid for 10 minutes. If it expires:

1. Cancel the stuck PENDING authorization using the cancel authorization endpoint.
2. Create a new authorization via POST /api/v1/claims/authorize.
3. Render the new iframe and retry the matching process.

Authorization Stuck at PENDING

If the authorization remains in PENDING after a seemingly successful match:

1. Check the current authorization status via the authorization details endpoint.
2. If still PENDING, cancel it using the cancel authorization endpoint.
3. Create a new authorization and retry.
4. If issues persist, verify Hardware Server is running (GET http://localhost:18065/status) and restart the service if needed.

All 3 Retries Failed (REJECTED status)

After 3 failed fingerprint matching attempts, the authorization transitions to REJECTED and is no longer usable. Create a new authorization and retry from Step 1.

If fingerprint matching repeatedly fails for a patient, consider submitting an OTP Whitelist Request for the patient. See OTP Whitelist Request.

Device Not Detected by iframe

• Verify Hardware Server is running (check GET http://localhost:18065/status).
• Confirm the device appears in the devices list with connected status.
• Run a test capture from the Hardware Server application.
• Restart the service if needed.

---

6. Related Resources

• OTP Whitelist Request
• Get OTP Whitelist Request
• Biometrics Scenarios - Scenario 1: SHIF IP Per Diem
• Biometrics Scenarios - Scenario 2: SHIF IP FFS Normal Preauth
• Biometrics Scenarios - Scenario 3: SHIF IP FFS Elective Preauth
• Biometrics Scenarios - Scenario 4: SHIF OP FFS Elective Preauth
• Start Visit Workflow Guide
• Elective Preauth Guide
• Consent Services API Reference