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

1. FHIR BHYT context — why bridge XML and FHIR

Healthcare facilities exchange BHYT adjudication and reimbursement output data with Vietnam Social Security (BHXH) under the current XML chain; volume varies by facility and settlement period. The effective lineage starts with Decision 130/QĐ-BYT (2023), amended by Decision 4750/QĐ-BYT (2023) and then Decision 3176/QĐ-BYT dated 29/10/2024. Decision 4210/QĐ-BYT is the historical source of the shorthand “XML 4210”.

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.

This XML schema is governed for BHYT output, so its scope and change rules follow the applicable decisions. Direct reuse for EMRs or the VNeID personal health record is limited by different use cases and semantics. Eligibility or card lookup is a separate integration contract and should not be inferred from either the output schema or FHIR REST.

FHIR R4 (4.0.1) provides financial Resources such as Coverage, Claim, ClaimResponse, ExplanationOfBenefit, Invoice, and PaymentReconciliation. They support a structured model but are not one-to-one equivalents of the BHYT schema and do not replace the official submission format. One architecture option is to use FHIR at the interoperability layer and generate XML through governed, tested mappings; another adapter pattern may be valid if it meets the same contract and traceability requirements.

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. VN Core v0.9.0 already includes R4-valid examples such as ExampleClaimBHYT, ExampleClaimResponseBHYT, ExampleExplanationOfBenefitBHYT, and ExamplePaymentReconciliationBHYT for implementation checks.

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

VN Core currently uses the trial-use VNCoreCoverageEligibilityRequest and VNCoreCoverageEligibilityResponse profiles to model an internal eligibility request and result. The package does not publish a Coverage/$verify-eligibility OperationDefinition, and Decree 164/2025 does not define that FHIR operation. A project that adds it must publish the OperationDefinition, advertise it in its CapabilityStatement, and map it to the actual BHXH portal contract. The Decision 3276 visit category belongs to Claim.subType, not Coverage.type.

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 — priority mapping tables

The section below covers core mappings for the three most common XML tables. VN Core v0.9.0 currently provides focused ConceptMaps such as vn-cm-bhyt-financial-field-to-adjudication and vn-cm-qd3176-cost-group-to-q697-cost-category; broader field-level conformance for the Decision 130/4750/3176 schema still needs pilot validation across HIS/EMR implementations before it becomes a conformance artifact.

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 0..* MS
* identifier ^slicing.discriminator.type = #value
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
* identifier contains BHYT 0..1 MS
* identifier[BHYT].system = "http://fhir.hl7.org.vn/core/sid/bhyt" (exactly)
* identifier[BHYT].value 1..1
* identifier[BHYT].value obeys vn-bhyt-format
* status 1..1 MS
* type 1..1 MS
* type.coding ^slicing.discriminator.type = #value
* type.coding ^slicing.discriminator.path = "system"
* type.coding ^slicing.rules = #open
* type.coding contains coverageCategory 1..1 MS
* type.coding[coverageCategory].system = "http://terminology.hl7.org/CodeSystem/insurance-coverage-type" (exactly)
* type.coding[coverageCategory].code = #medical (exactly)
* beneficiary 1..1 MS
* policyHolder 0..1
* payor 1..* MS
* period 0..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
    VNCoreExtBHYTCardType named bhytCardType 0..1 MS and
    VNCoreExtPrimaryCareFacility named primaryCareFacility 0..1 MS and
    VNCoreExtCoverageCumulativeCopay named cumulativeCopay 0..1 MS

VN Core uses three Coverage extensions: VNCoreExtBHYTCardType for the card/participant group, VNCoreExtPrimaryCareFacility for the initial registered facility (MA_DKBD), and VNCoreExtCoverageCumulativeCopay for the cumulative annual co-payment. The 27 visit categories in Decision 3276 are a different concept and bind to Claim.subType, not Coverage.type.

6. Claim profile for the payment request

VNCoreClaim constrains the fields a healthcare facility must submit and binds terminology at the correct semantic level. In v0.9.0, diagnosis.diagnosisCodeableConcept binds to the diagnosis terminology, while item.category binds to the 12 cost groups under Decision 697/QĐ-BYT. item.productOrService is required but is not bound to a synthetic union ValueSet, because it can carry service, drug, or device codes whose source catalogs have different governance lifecycles.

Profile: VNCoreClaim
Parent: Claim
Id: vn-core-claim
Title: "VN Core Claim — BHYT payment request"

* status 1..1 MS
* type 1..1 MS
* use 1..1 MS
* subType 0..1 MS
* subType from $vn-patient-visit-type-vs (extensible)
* patient 1..1 MS
* created 1..1 MS
* priority 1..1
* provider 1..1 MS
* insurance 1..* MS
* insurance.focal 1..1 MS
* insurance.coverage 1..1 MS
* diagnosis 1..* MS
* diagnosis.diagnosisCodeableConcept 0..1 MS
* diagnosis.diagnosisCodeableConcept from $vn-condition-code-vs (extensible)
* item 1..* MS
* item.sequence 1..1 MS
* item.category 0..1 MS
* item.category from $vn-cost-category-vs (extensible)
* item.productOrService 1..1 MS
* item.unitPrice 0..1
* item.quantity 0..1
* 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-claim-response

* status 1..1 MS
* type 1..1 MS
* use 1..1 MS
* patient 1..1 MS
* created 1..1 MS
* insurer 1..1 MS
* request 0..1 MS    // Reference to the original Claim when available
* outcome 1..1 MS
* item 0..* MS
* item.itemSequence 1..1 MS
* item.adjudication 1..* MS
* item.adjudication.category 1..1 MS
* item.adjudication.category from http://hl7.org/fhir/ValueSet/adjudication (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. Decision 697 cost statement in VNCoreClaim

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).

VN Core does not currently publish a separate Invoice profile for Decision 697. The 12 cost categories are modeled on VNCoreClaim.item: item.category binds to VNCostCategoryVS, while quantity, unitPrice, and net carry line-level amounts. Payer adjudication belongs in ClaimResponse/EOB, and claim-level cost totals use VNCoreExtClaimCostSummary.

Profile: VNCoreClaim
Parent: Claim
Id: vn-core-claim

* item 1..* MS
* item.category 0..1 MS
* item.category from VNCostCategoryVS (extensible)
* item.productOrService 1..1 MS
* item.quantity 0..1
* item.unitPrice 0..1
* item.net 0..1 MS

* extension contains
    VNCoreExtClaimCostSummary named costSummary 0..1 MS

9. Patient category codes per Decision 3276

Decision 3276/QĐ-BYT, issued on 17/10/2025, defines 27 visit-category codes grouped by the reason and routing of a BHYT encounter. VN Core publishes them as VNPatientVisitTypeCS (vn-patient-visit-type-cs) and VNPatientVisitTypeVS, with an extensible binding on Claim.subType. This visit-level code is distinct from Coverage.extension[bhytCardType], which carries the participant/card group such as DN, HC, HN, or TE.

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 governs electronic transactions in social insurance; the applicable BHXH portal documentation must define each endpoint, payload, and operational procedure. This page has no basis for claiming an official BHXH FHIR REST API. Using FHIR internally and translating to the current receiving format/channel is one architecture option. A future BHXH FHIR specification could still require changes to the domain model, terminology, workflow, and adapter; it is unsafe to promise an outbound-only change.

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?

This is an architecture option to evaluate, not a requirement of Circular 13/2025/TT-BYT. Where the internal model is already standardized on FHIR, a bridge may generate the current BHXH XML and reuse part of the dataset for VNeID flows. The mapping must still be versioned, tested for each XML table, carry provenance, and explicitly handle non-equivalent fields; FHIR-native storage alone does not demonstrate legal or BHXH workflow compliance.

Does Decision 697 fully replace Decision 6556/2018?

Yes. Decision 6556/QĐ-BYT (2018) has been fully superseded by Decision 697/QĐ-BYT. The parallel-run transition window (for software upgrades) closed on 01/07/2026 — only the Decision 697 template is used now; the old template is kept solely to cross-check records created before that date.

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 VNCoreExtPrimaryCareFacility (canonical http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-primary-care-facility) carrying a Reference to the Organization for the initial registered 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