Connect online payments without mistaking a callback for settlement
For CIO/CTO / digital programme owner · Plan implementation
TL;DR — what you’ll learn
- Track online and UPI/card payments across four explicit states—
Initiated,Authorised / Captured,Failed / AbandonedandSettled in Bank—rather than treating a browser redirect as proof of settlement. - Enforce idempotency keys and cryptographic signature verification on every payment-gateway webhook so retried callbacks never generate duplicate HIS receipts.
- Hold amount mismatches, late webhooks on expired booking slots and customer-disputed double debits in a finance-reviewed exception queue.
- Route all refund executions through finance controller approval linked to the original gateway payment ID and bank settlement batch.
Illustrative hospital administrative and operations coordination desk; not a client facility.
Across 500 online OPD tele-booking and inpatient advance-deposit payment attempts in synthetic batch PGW-REC-2026-10 (₹14.60 lakh initiated value), a hospital reconciles its booking portal, HIS billing ledger, payment-gateway dashboard and bank settlement statement: 430 payments (₹12.40 lakh) complete cleanly from signed gateway capture through HIS receipt generation and T+1 bank settlement; 38 booking sessions (₹0.95 lakh) are abandoned or fail at the customer’s bank OTP/UPI screen with ₹0 captured; 16 network-timeout retries send 32 webhook callbacks for the same 16 single captures (₹0.64 lakh), which idempotency controls must deduplicate so the HIS does not issue two advance receipts per patient; 9 late-arriving capture callbacks (₹0.27 lakh) arrive 22 minutes after the patient’s 15-minute slot-hold timer expired; and 7 patients (₹0.34 lakh) experience a double debit where one attempt booked the slot and the second captured attempt requires a finance-verified refund. If the portal marks a bill "Paid" on an unsigned browser redirect—or lacks idempotency on webhook retries—the hospital faces duplicate receipts, unbooked paid patients and unverified refunds.
For hospital CIOs, finance controllers, revenue-cycle leads and patient-portal product owners, the core question is which payment states and reconciliation controls a hospital must store before confirming a receipt or preparing a refund.
Separate initiated, authorised/captured, failed and settled states per provider
A payment gateway integration crosses three distinct systems of record: the hospital’s *booking and billing system* (which owns the order/appointment ID, expected payable amount and patient receipt), the *payment gateway / aggregator* (which owns the payment attempt ID, cryptographic webhook signature, capture status and settlement batch ID), and the *hospital’s bank account* (which records the actual net settled credit after gateway fees and GST, plus any chargebacks or refund debits). Confusing an unverified client-side browser return URL with a server-verified gateway capture—or confusing gateway capture with bank settlement—causes persistent ledger variances.
The Bahmni billing and accounting and Bahmni feature list provide first-party reference examples separating clinical/appointment events from billing and accounting ledgers (context only; merchant-acquiring contracts, gateway webhook signature specifications, GST on gateway fees and refund approval matrices must be verified by the hospital’s finance controller, payment integration architect and security lead).
In the illustrative 500-attempt PGW-REC-2026-10 online payment reconciliation (₹14.60 lakh initiated across OPD bookings and IPD deposits), gateway callbacks, HIS receipts and bank settlement batches are reconciled:
Scroll horizontally to see all columns.
Payment lifecycle cohort (PGW-REC-2026-10) | Payment attempts | Initiated amount (₹ lakh) | Captured & bank-settled amount (₹ lakh) | HIS receipt & finance reconciliation outcome |
|---|---|---|---|---|
| Clean captured & T+1 settled payments | 430 | 12.40 | 12.40 | 430 HIS receipts issued; bridged to bank batch (gross = net + fee/GST) |
| Abandoned / bank-declined attempts | 38 | 0.95 | 0.00 | Marked Failed/Abandoned; zero HIS receipts issued |
| Webhook retry duplicates (32 callbacks for 16 captures) | 16 | 0.64 | 0.64 | Idempotency key blocked 16 replay callbacks; exactly 16 receipts issued |
Late capture after slot-hold expiry (PGW-LATE-01..09) | 9 | 0.27 | 0.27 | Quarantined in priority rebooking / refund queue; never silently dropped |
Customer double-debit attempts (PGW-DBL-01..07) | 7 | 0.34 | 0.34 | Primary attempt receipted; duplicate capture routed to finance refund approval |
| Total initiated attempts (`PGW-REC-2026-10`) | 500 | 14.60 | 13.65 | 446 active receipts (`₹13.04L`) + 16 refund/rebook holds (`₹0.61L`) + 38 failed |
All 500 payment attempts (430 + 38 + 16 + 9 + 7 = 500) and ₹14.60 lakh initiated (12.40 + 0.95 + 0.64 + 0.27 + 0.34 = 14.60) reconcile completely: ₹13.65 lakh is captured and settled by the gateway (12.40 + 0.64 + 0.27 + 0.34 = 13.65), producing 446 valid HIS receipts (430 + 16 = 446 totalling ₹13.04 lakh) while isolating the 9 late-slot captures (₹0.27 lakh) and 7 duplicate captures (₹0.34 lakh) totaling ₹0.61 lakh (16 cases) for explicit rebooking or finance-approved refund.
Compare callback and reconciliation evidence
Three technical rules prevent 99% of hospital payment-gateway bugs: (1) verify the cryptographic HMAC/signature on the server-to-server webhook or server-side status-query API before creating a receipt; (2) enforce a unique database constraint on (gateway_payment_id, event_type) so 32 webhook deliveries for 16 payments (₹0.64 lakh) can only ever create 16 HIS receipts; and (3) check that captured_amount_paise === expected_order_amount_paise and that the underlying appointment or bill is still open before auto-confirming.
Connect online payment integration with Design appointment reminders around confirmation and cancellation, Manage telehealth booking and document routing with a clear clinical boundary, Refund the right transaction with the right approval and Reconcile cash, UPI and card collections at day close so outpatient appointment scheduling, telehealth bookings, inpatient refund approvals and daily cash-to-bank reconciliations share the same transaction identifiers.
Worked workflow
Original illustrative workflow. Follow the labelled transitions, including the exception paths.
- A · StepCreate HIS payment order with unique order_id, expected amount, encounter/booking reference and expiry window
- B · StepReceive server-to-server gateway callback or status poll and verify cryptographic signature and idempotency key
- C · StepValidate captured amount against order_id, check booking/bill state and reconcile against T+1 settlement report
- D · DecisionSignature valid, idempotency unique, amount/slot active and gateway capture matched to settlement batch?
- E · StepSuppress duplicate webhook replay and route late-slot capture (PGW-LATE) or double debit (PGW-DBL) to exception queue
- F · StepRecord patient-services slot reassignment or finance-controller approval of linked gateway refund
- G · StepIssue single immutable HIS receipt linked to gateway_payment_id and post T+1 bank settlement + fee/GST split
- H · StepArchive daily three-way bridge (HIS receipts vs gateway settlement vs bank statement) for finance audit
Scroll horizontally to see all columns.
| From | Condition | Next |
|---|---|---|
| A: Create HIS payment order with unique order_id, expected amount, encounter/booking reference and expiry window | Continue | B: Receive server-to-server gateway callback or status poll and verify cryptographic signature and idempotency key |
| B: Receive server-to-server gateway callback or status poll and verify cryptographic signature and idempotency key | Continue | C: Validate captured amount against order_id, check booking/bill state and reconcile against T+1 settlement report |
| C: Validate captured amount against order_id, check booking/bill state and reconcile against T+1 settlement report | Continue | D: Signature valid, idempotency unique, amount/slot active and gateway capture matched to settlement batch? |
| D: Signature valid, idempotency unique, amount/slot active and gateway capture matched to settlement batch? | No | E: Suppress duplicate webhook replay and route late-slot capture (PGW-LATE) or double debit (PGW-DBL) to exception queue |
| E: Suppress duplicate webhook replay and route late-slot capture (PGW-LATE) or double debit (PGW-DBL) to exception queue | Continue | F: Record patient-services slot reassignment or finance-controller approval of linked gateway refund |
| F: Record patient-services slot reassignment or finance-controller approval of linked gateway refund | Continue | C: Validate captured amount against order_id, check booking/bill state and reconcile against T+1 settlement report |
| D: Signature valid, idempotency unique, amount/slot active and gateway capture matched to settlement batch? | Yes | G: Issue single immutable HIS receipt linked to gateway_payment_id and post T+1 bank settlement + fee/GST split |
| G: Issue single immutable HIS receipt linked to gateway_payment_id and post T+1 bank settlement + fee/GST split | Continue | H: Archive daily three-way bridge (HIS receipts vs gateway settlement vs bank statement) for finance audit |
Test retries, abandoned bookings and mismatched amounts
Payment integrations fail in production when a mobile user switches from clinic Wi-Fi to 4G mid-UPI payment (triggering webhook retries or late callbacks after the 15-minute slot timer expired: PGW-LATE-01..09), when an impatient user clicks "Pay Now" twice in two browser tabs (PGW-DBL-01..07), or when finance cannot reconcile why ₹13.65 lakh of gateway captures resulted in ₹13.48 lakh credited to the bank (because gateway MDR fees and GST were netted off without a fee-split ledger entry).
In the PGW-REC-2026-10 workflow above, decision gate D blocks duplicate webhook replays and holds any late-slot or double-debit capture in E. Only after patient services confirms a slot re-allocation or the finance controller approves a linked refund at F does the record return to C and close cleanly at G/H.
Route refunds to authorised review.
Pilot the payment integration using a 500-attempt synthetic and sandbox harness (PGW-REC-2026-10) before enabling live online collections. Inject simulated duplicate webhooks (32 callbacks for 16 payments), forged unsigned callbacks, amount mismatches, late post-expiry captures (PGW-LATE-01..09) and double debits (PGW-DBL-01..07) to prove that every rupee reconciles across HIS, gateway and bank.
Software enforces cryptographic webhook verification, idempotency constraints, state transitions and three-way settlement bridges; refund approvals, fee-accounting policies and dispute write-offs remain with the hospital’s finance controller.
Next actions
- Audit your current portal/HIS payment integration against the
PGW-REC-2026-10failure set: unsigned browser redirects, duplicate webhook retries (16cases) and late post-expiry captures (9cases). - Enforce database-level idempotency on
gateway_payment_idand build an automated daily bridge reconciling HIS receipts, gateway settlement files (including MDR fees/GST) and bank credits. - Route all late-slot captures (
PGW-LATE-01..09) and double debits (PGW-DBL-01..07) into a dedicated finance and booking recovery queue with original transaction links.
Discuss this workflow
Request a workflow assessment focused on this question: Which payment states should a clinic or hospital store before confirming payment or preparing a refund?
Describe the operation using business information only. Please leave out patient details.
Applying this guide
The scenarios and numbers are illustrative. Confirm these provider-specific inputs before implementation:
- Finance controller and revenue-cycle / billing head: Reconciled `PGW-REC-2026-10` bridge (`₹14.60 lakh` initiated -> `₹13.65 lakh` captured -> `₹13.04 lakh` receipted + `₹0.61 lakh` refund/rebook holds) and refund approval matrix.
- Payment integration architect and CISO / application security lead: Verified cryptographic webhook signature check, replay idempotency (`32` callbacks -> `16` receipts) and rejection of unsigned redirects.
- Outpatient / patient-portal operations owner: SLA workflow for handling late post-expiry captures (`PGW-LATE-01..09`) via priority slot rebooking or finance-approved refund.
References
- Bahmni billing and accounting — Illustrates separation between clinical events, billing and ERP/Odoo accounting; not tax or accounting-policy authority.
- Bahmni feature list — Module boundary reference across registration, clinical services, lab, stock and billing; verify actual deployed version.
Topics: hospital payment gateway integration · clinic payment gateway · hospital online payment integration · payment callback reconciliation
