FHIR and BHYT: mapping the BHYT XML (Decision 130/4750/3176) to Coverage, Claim, EOB

1. FHIR BHYT context — why bridge XML and FHIR

Every healthcare facility in Vietnam submits millions of BHYT (Vietnam's mandatory social health insurance, covering roughly 90% of the population) reimbursement records each year to Vietnam Social Security (BHXH) in XML format. That format is no longer based on the old Decision 4210/QĐ-BYT. The currently effective chain is Decision 130/QĐ-BYT (2023), amended by Decision 4750/QĐ-BYT (2023), and further amended by Decision 3176/QĐ-BYT issued on 29/10/2024.

Many technical specs and engineering teams still call this XML file "XML 4210" after the original Decision 4210. The shorthand is not culturally wrong, but anytime you write a spec or a legal citation, every reference must point back to the proper Decision 130 / 4750 / 3176 chain. This matters because BHXH performs adjudication based on the schema and the patient category codes defined in the newer decisions, not Decision 4210.

The current XML format has three limitations against a modern health data strategy. First, the schema is designed solely for the BHYT adjudication flow and cannot be reused for the electronic medical record (Circular 13/2025/TT-BYT) or the personal health record on VNeID (Vietnam's national digital identification app). Second, the schema is fixed: any extension requires amending a regulatory document. Third, there is no structured REST interface for real-time card lookup — eligibility checks today still flow through the BHXH portal via a dedicated web service.

FHIR R4 (4.0.1) addresses all three limitations by providing a ready-made resource model for the health-finance domain: Coverage, Claim, ClaimResponse, ExplanationOfBenefit, Invoice, and PaymentReconciliation. That said, BHXH does not yet accept FHIR Bundles as an official input format. The viable deployment pattern today is to operate FHIR-natively inside the hospital information system and emit XML output for BHXH through a dedicated bridge layer — which is exactly the topic of this article.

2. BHYT regulatory framework 2023–2026

The table below summarizes the documents hospitals and FHIR teams should read when designing the bridge layer. Every reference code matches the VNLegalDocumentRefCS CodeSystem in the VN Core IG.

3. Four core FHIR BHYT use cases

A BHYT XML-to-FHIR bridge layer serves four business flows. Each flow maps to a FHIR resource or operation, even though BHXH does not yet officially accept FHIR. The pseudocode snippets below describe internal REST API design intent — not full FHIR instances. A complete, R4-valid Claim sample with every required field (status, type, use, created, priority, insurance.sequence, insurance.focal) will be published alongside the VN Core IG.

3.1. BHYT card lookup — Coverage

When a patient registers for care, the hospital must verify the BHYT card is still valid, identify the patient category, and find the original enrollment facility. In the FHIR-native internal model, the hospital reads Coverage by identifier:

GET /Coverage?identifier=http://fhir.hl7.org.vn/core/sid/bhyt|DN4123456789012
Accept: application/fhir+json

Or wrap the lookup in a custom Coverage/$verify-eligibility operation so the adapter can translate it into a real API call to the BHXH portal (per Decree 164/2025). The returned Coverage carries the card identifier, type (the patient category code per Decision 3276), period (validity), beneficiary (Patient), and the VN extension for five-year continuous enrollment.

3.2. Submitting a payment request — Claim

When the encounter ends, the hospital submits a payment request. Inside the EMR this is a Claim:

POST /Claim
Content-Type: application/fhir+json

# Pseudocode shape — a valid R4 Claim still requires
# status, type, use, created, priority, insurance.sequence, insurance.focal.
# See the canonical sample in the VN Core IG.

The bridge layer then renders this Claim into an XML file conforming to the Decision 130/4750/3176 schema and uploads it to the BHXH portal. Keeping the Claim FHIR-native internally lets the hospital share a single dataset across the EMR (Circular 13/2025/TT-BYT), internal accounting, and the personal health record on VNeID if that becomes a future requirement.

3.3. Receiving the BHXH response — ClaimResponse / EOB

BHXH adjudicates and returns the result: approved, rejected, or requires supplementation. The adapter converts that XML notification into an internal ClaimResponse. Each original item in the Claim has a corresponding entry under ClaimResponse.item.adjudication, recording T_BNTT (the patient out-of-pocket amount) and T_BHTT (the BHYT-paid amount). For retrospective reporting or for pushing data to VNeID, ExplanationOfBenefit (EOB) is the better-fit resource because it consolidates the full benefit context plus the adjudication outcome.

3.4. Periodic settlement — PaymentReconciliation

Each quarter, the hospital and the BHXH agency sign off on a settlement. The PaymentReconciliation resource aggregates many ClaimResponses and records the final payment. This is also where Form 06/BH per Circular 12/2026/TT-BTC maps into FHIR.

4. BHYT XML to FHIR — detailed mapping tables

The section below covers core mappings for the three most common XML tables. The complete ConceptMap for the full Decision 130/4750/3176 schema will be published with the VN Core IG as the artifact vn-conceptmap-bhyt-xml-to-fhir.

4.1. XML4210_TONGHOP table to Bundle, Patient, Coverage, Encounter, Claim

4.2. XML4210_CHITIET table to Claim.item

4.3. XML4210_THUOC table to MedicationRequest and Claim.item

5. Coverage profile for the BHYT card

Coverage in FHIR models the scope and benefits of an insurance arrangement. This article uses Coverage to represent a specific patient's BHYT card at a point in time. VN Core proposes the VNCoreCoverage profile with the constraints below.

Profile: VNCoreCoverage
Parent: Coverage
Id: vn-core-coverage
Title: "VN Core Coverage — BHYT card"
Description: "Coverage profile for a Vietnamese social health insurance (BHYT) card."

* identifier 1..1 MS
* identifier.system = "http://fhir.hl7.org.vn/core/sid/bhyt"
* identifier.value 1..1 MS
* status 1..1 MS
* type from VNBHYTSubjectVS (extensible)   // Decision 3276/QĐ-BYT 2025 — 27 patient category codes
* beneficiary 1..1 MS
* policyHolder 0..1
* payor 1..* MS
* period 1..1 MS

// MA_DKBD (initial enrollment facility code) MUST NOT be bound to Coverage.network.
// Per the FHIR R4 spec, Coverage.network is reserved for an insurer-defined
// network identifier — not a Vietnamese initial-enrollment healthcare facility code.
* extension contains
    VNExtBhytEnrollmentLocation named enrollmentLocation 0..1 MS and
    VNExtBhytFiveYearContinuous named fiveYearContinuous 0..1 and
    VNExtBhytBenefitLevel named benefitLevel 0..1

The vn-ext-bhyt-enrollment-location extension carries a Reference to the Organization (the initial enrollment facility). This avoids violating Coverage.network semantics — an issue Codex review flagged: the element does not represent Vietnam's MA_DKBD enrollment code.

6. Claim profile for the payment request

VNCoreClaim constrains the fields the hospital must submit and binds the right ValueSets for diagnosis and productOrService. Note that FSH does not support from A or B or C syntax — you must compose a unified ValueSet first, then bind it to Claim.item.productOrService.

// Step 1: compose a unified ValueSet for productOrService on Claim.item
ValueSet: VNClaimItemServiceVS
Id: vn-claim-item-service-vs
Title: "VN Claim Item Service ValueSet"
Description: "Unifies DVKT, the drug list, and ICD-9-CM for binding to Claim.item.productOrService."
* include codes from valueset VNDVKTVS
* include codes from valueset VNDrugVS
* include codes from valueset VNICD9CMVS

// Step 2: define the profile
Profile: VNCoreClaim
Parent: Claim
Id: vn-core-claim
Title: "VN Core Claim — BHYT payment request"

* status 1..1 MS
* type 1..1 MS
* use = #claim
* patient 1..1 MS
* created 1..1 MS
* priority 1..1 MS
* provider 1..1 MS
* insurance 1..* MS
* insurance.sequence 1..1 MS
* insurance.focal 1..1 MS
* insurance.coverage 1..1 MS
* diagnosis 1..* MS
* diagnosis.diagnosisCodeableConcept from VNICD10VS (extensible)
* item 1..* MS
* item.sequence 1..1 MS
* item.productOrService from VNClaimItemServiceVS (extensible)
* item.unitPrice 0..1 MS
* item.quantity 0..1 MS
* item.net 0..1 MS

Setting insurance 1..* supports the multi-BHYT scenario under Decree 188/2025: a patient may hold several BHYT cards simultaneously, with each card represented as one entry in Claim.insurance and focal marking the primary card used for this encounter.

7. ClaimResponse and ExplanationOfBenefit

Adjudication — BHXH's decision on how much it will cover, how much the patient pays out of pocket, and which line items are denied — belongs to the payer side. In FHIR R4, Claim.item has no adjudication sub-element; every adjudicated value lives on ClaimResponse.item.adjudication. The bridge layer must receive the XML notification from BHXH, parse the T_BNTT, T_BHTT, T_NGUONKHAC, and T_NSNN fields, and assemble a structured ClaimResponse:

Profile: VNCoreClaimResponse
Parent: ClaimResponse
Id: vn-core-claimresponse

* status 1..1 MS
* type 1..1 MS
* use = #claim
* patient 1..1 MS
* request 1..1 MS    // Reference to the original Claim
* outcome 1..1 MS
* item 0..* MS
* item.itemSequence 1..1 MS
* item.adjudication 1..* MS
* item.adjudication.category from VNAdjudicationCategoryVS (extensible)
* item.adjudication.amount 0..1 MS

ExplanationOfBenefit (EOB) is the higher-level resource: it consolidates Claim and ClaimResponse plus Coverage and Patient context. When the hospital needs to push BHYT payment history to the personal health record on VNeID, or when a vendor builds a patient-facing dashboard, EOB is the recommended format.

8. Invoice for the Decision 697 billing summary

Decision 697/QĐ-BYT was issued on 19/03/2026 and took effect the same day. The deadline for hospitals to upgrade software and fully transition to the new template is 01/07/2026 — after that date the old template under Decision 6556/QĐ-BYT (2018) is no longer accepted. The Decision 697 billing summary defines 12 cost categories and 13 columns and supports the case where one patient has multiple BHYT cards co-paying (multi-BHYT under Decree 188/2025).

The right FHIR resource to model this billing summary is Invoice. The lineItem structure in Invoice maps to each row across the 12 categories: lineItem.chargeItemCodeableConcept binds to the Decision 697 cost-category CodeSystem, and lineItem.priceComponent separates the BHYT-paid portion, the patient out-of-pocket portion, the co-payment, the state-budget portion, and other sources.

Profile: VNCoreInvoiceBHYT
Parent: Invoice
Id: vn-core-invoice-bhyt
Title: "VN Core Invoice — BHYT billing summary per Decision 697"

* status 1..1 MS
* type 1..1 MS
* type.coding.system = "http://fhir.hl7.org.vn/core/CodeSystem/vn-bhyt-invoice-type-cs"
* type.coding.code = #billing-summary-bhyt
* subject 1..1 MS    // Reference to Patient
* recipient 1..1 MS  // Reference to Organization (the BHXH agency)
* date 1..1 MS
* lineItem 1..* MS
* lineItem.chargeItemCodeableConcept 1..1 MS
* lineItem.chargeItemCodeableConcept from VNQD697ChargeCategoryVS (required)
* lineItem.priceComponent 1..* MS
* lineItem.priceComponent.type 1..1 MS
* lineItem.priceComponent.amount 1..1 MS
* totalNet 1..1 MS
* totalGross 1..1 MS

9. Patient category codes per Decision 3276

Decision 3276/QĐ-BYT, issued on 17/10/2025, defines the patient-category code list for BHYT visits — 27 codes in total (for example, HC for civil-service personnel, DT for groups funded by the central budget, HS for students, NN for the elderly). VN Core encodes this list as the CodeSystem vn-bhyt-subject-cs and the ValueSet vn-bhyt-subject-vs, which bind to Coverage.type. Every code carries its full legal citation in the CodeSystem, per OmiGroup's internal rules on legal citation.

10. Payment ceilings under Decree 188/2025

Decree 188/2025/NĐ-CP was issued on 01/07/2025 and generally took effect on 15/08/2025; some articles applied from 01/07/2025. The decree sets a BHYT payment ceiling per encounter equivalent to 45 months of the base salary, but the ceiling applies only to specific cost groups and high-end technical services per the detailed regulations — it is not a universal cap on every Claim.total value.

11. BHXH electronic APIs under Decree 164/2025

Decree 164/2025/NĐ-CP, dated 29/06/2025, opens up API-based electronic transactions with the BHXH portal for three flows: real-time BHYT card lookup, reimbursement submission, and adjudication-result reconciliation. That said, BHXH has not yet published an official FHIR REST API specification as of Q2 2026. The architecture pattern recommended for hospitals and vendors is to operate FHIR-natively internally, with an adapter that converts to the XML format and web service BHXH defines on the way out. When BHXH publishes a FHIR spec, the adapter changes only its outbound implementation — the core architecture stays intact.

12. Frequently asked questions

Has BHXH started accepting FHIR Bundles?

Not yet, as of Q2 2026. BHXH still requires XML submissions per the schema in Decision 130, as amended by Decision 4750 and Decision 3176. The "XML 4210" shorthand from the original Decision 4210 has been superseded.

Should we build FHIR-first and convert to XML for BHXH submission?

Yes — that is the recommended pattern. Keeping the EMR and electronic medical records FHIR-native helps the hospital comply with Circular 13/2025/TT-BYT for EMRs while reusing the same dataset for the personal health record on VNeID. The bridge layer takes on the responsibility of converting to XML for BHXH per the current standard.

Does Decision 697 fully replace Decision 6556/2018?

Yes. Decision 6556/QĐ-BYT (2018) has been superseded by Decision 697/QĐ-BYT. During the transition period through 01/07/2026, hospitals may run both in parallel to allow time for software upgrades, but after that date everyone must move fully to the new template.

How is multi-BHYT under Decree 188/2025 implemented in FHIR?

Claim.insurance is an array. Each BHYT card the patient holds becomes an entry with a distinct insurance.sequence and an insurance.coverage pointing to the corresponding Coverage. Exactly one entry is marked insurance.focal=true for the specific encounter. Adjudication on the ClaimResponse keeps the sequence reference so it stays clear which portion belongs to which card.

Where should MA_DKBD map on Coverage?

Use the VN extension vn-ext-bhyt-enrollment-location carrying a Reference to the Organization (the initial enrollment facility). Do not use Coverage.network — per the FHIR R4 specification, that element represents an insurer-defined network identifier, not Vietnam's initial-enrollment facility code.

13. Legal and FHIR specification references

• Decision 130/QĐ-BYT (2023) — Output data standard for BHYT cost management. VN Core code: QD-130-2023. See legal-corpus.md.
• Decision 4750/QĐ-BYT (2023) — Amends Decision 130. Code: QD-4750-2023.
• Decision 3176/QĐ-BYT (29/10/2024) — Amends Decision 4750/Decision 130; current outpatient/inpatient standard. Code: QD-3176-2024.
• Decision 697/QĐ-BYT (19/03/2026) — Billing summary template. Code: QD-697-2026.
• Decision 3276/QĐ-BYT (17/10/2025) — Patient category code list for BHYT visits. Code: QD-3276-2025.
• Decision 4210/QĐ-BYT — Output data standard for BHXH (legacy). Code: QD-4210-BYT.
• Amended Health Insurance Law: Law 51/2024/QH15 (code: L-51-2024, effective 01/07/2025). Note: L-91-2025 is the Personal Data Protection Law, not the BHYT amendment.
• Decree 188/2025/NĐ-CP — Implements the Health Insurance Law (issued 01/07/2025, effective 15/08/2025).
• Decree 164/2025/NĐ-CP — Electronic transactions in BHXH (29/06/2025).
• Decree 233/2025/NĐ-CP — BHYT fund financial mechanism.
• Circular 12/2026/TT-BTC — Procedures and templates for BHYT adjudication and final settlement (10/02/2026).
• FHIR R4 Claim — hl7.org/fhir/R4/claim.html.
• FHIR R4 ClaimResponse — hl7.org/fhir/R4/claimresponse.html.
• FHIR R4 Coverage — hl7.org/fhir/R4/coverage.html.
• FHIR R4 ExplanationOfBenefit — hl7.org/fhir/R4/explanationofbenefit.html.
• FHIR R4 Invoice — hl7.org/fhir/R4/invoice.html.
• FHIR Shorthand reference — FSH spec.

14. Further reading