Invoice XML Format

Overview

The legal e-invoice XML (TT78 / Decree 123/2020/ND-CP) is generated, signed and submitted entirely by VNPAY (viiAPI). BANA exchanges JSON only: @nx/invoice builds a JSON issuance request via _buildInvoiceRequest and never produces XML locally (no xml2js, no XML signing, no XSD validation in BANA).

The structure below is the GDT-defined schema the provider emits, kept here as reference for understanding the issued artifact - not something BANA generates.

What @nx/invoice Does

Step	Format	Owner
Issuance request	JSON	@nx/invoice builds via _buildInvoiceRequest, sends through @nx/iiapi
Legal XML generation	XML (TT78 / Decree 123)	VNPAY (provider)
XML signing + GDT submission	XML	VNPAY (provider)
Provider response	JSON	@nx/invoice persists (invoiceNumber, status)

XML Structure

XML Example

Provider-generated artifact (VNPAY); shown for reference. BANA neither builds nor signs this.

<?xml version="1.0" encoding="UTF-8"?>
<HDon>
  <DLHDon>
    <TTChung>
      <PBan>2.0.0</PBan>              <!-- XML Version -->
      <THDon>Hóa đơn GTGT</THDon>     <!-- Invoice Type Name -->
      <KHMSHDon>1</KHMSHDon>          <!-- Template Code -->
      <KHHDon>C25TAA</KHHDon>         <!-- Template Symbol -->
      <SHDon>00000001</SHDon>         <!-- Invoice Number (provider-allocated) -->
      <NLap>2025-01-20</NLap>         <!-- Issue Date -->
      <DVTTe>VND</DVTTe>              <!-- Currency -->
      <TGia>1</TGia>                  <!-- Exchange Rate -->
      <HTTToan>TM/CK</HTTToan>        <!-- Payment Method -->
    </TTChung>
    <NDHDon>
      <NBan>
        <Ten>Công ty TNHH ABC</Ten>
        <MST>0123456789</MST>
        <DChi>123 Nguyễn Huệ, Q1, TP.HCM</DChi>
      </NBan>
      <NMua>
        <Ten>Khách hàng XYZ</Ten>
        <MST>9876543210</MST>
        <DChi>456 Lê Lợi, Q1, TP.HCM</DChi>
      </NMua>
      <DSHHDVu>
        <HHDVu>
          <TChat>1</TChat>
          <STT>1</STT>
          <THHDVu>Sản phẩm A</THHDVu>
          <DVTinh>Cái</DVTinh>
          <SLuong>2</SLuong>
          <DGia>100000</DGia>
          <ThTien>200000</ThTien>
          <TSuat>10%</TSuat>
        </HHDVu>
      </DSHHDVu>
      <TToan>
        <TgTCThue>200000</TgTCThue>
        <TgTThue>20000</TgTThue>
        <TgTTTBSo>220000</TgTTTBSo>
        <TgTTTBChu>Hai trăm hai mươi nghìn đồng</TgTTTBChu>
      </TToan>
    </NDHDon>
  </DLHDon>
  <DSCKS>
    <NBan>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <!-- Seller's Digital Signature (provider-side) -->
      </Signature>
    </NBan>
  </DSCKS>
</HDon>

Field Reference

GDT-defined schema, generated provider-side. Reference only.

TTChung (General Information)

Element	Required	Description	Format
PBan	Yes	XML Version	"2.0.0"
THDon	Yes	Invoice Type Name	Text
KHMSHDon	Yes	Template Code	1-6
KHHDon	Yes	Template Symbol	Max 6 chars
SHDon	Yes	Invoice Number	8 digits
MHSo	Yes	Model Number	Pattern: ##GTKT#/###
NLap	Yes	Issue Date	YYYY-MM-DD
DVTTe	Yes	Currency	ISO 4217 (VND)
TGia	Yes	Exchange Rate	Decimal
HTTToan	Yes	Payment Method	TM/CK/TM-CK

NBan (Seller)

Element	Required	Description
Ten	Yes	Company Name
MST	Yes	Tax Code (10 or 13 digits)
DChi	Yes	Address
SDThoai	No	Phone Number
DCTDTu	No	Email
STKNHang	No	Bank Account
TNHang	No	Bank Name

NMua (Buyer)

Element	Required	Description
Ten	Yes	Customer Name
MST	B2B Only	Tax Code
DChi	No	Address
HVTNMHang	No	Contact Person

HHDVu (Line Item)

Element	Required	Description
TChat	Yes	Nature: 1=Goods, 2=Service
STT	Yes	Line Number
MHHDVu	No	Product Code
THHDVu	Yes	Product Name
DVTinh	Yes	Unit of Measure
SLuong	Yes	Quantity
DGia	Yes	Unit Price
TLCKhau	No	Discount Percent
STCKhau	No	Discount Amount
ThTien	Yes	Line Total (before VAT)
TSuat	Yes	VAT Rate

TToan (Totals)

Element	Required	Description
TgTCThue	Yes	Total before VAT
TgTThue	Yes	Total VAT
TgTTTBSo	Yes	Grand Total (number)
TgTTTBChu	Yes	Grand Total (words)

VAT Rates

Rate	Code	Description
0%	0%	Export, tax-free goods
5%	5%	Essential goods
8%	8%	Standard rate (temporary reduction)
10%	10%	Standard rate
KCT	KCT	Not subject to VAT
KKKNT	KKKNT	Non-taxable items

Related Pages

• Invoice Service
• Integration
• iiapi Integration
• Digital Signature
• Decisions