Tài khoản ảo (Virtual Account) là gì? Ứng dụng trong VA Billing, học phí, viện phí và retail

[Đơn hàng #1001] → [VA: VA100001] → [Khách chuyển 500,000đ] → [IPN: PAID ✓]
[Đơn hàng #1002] → [VA: VA100002] → [Khách chuyển 320,000đ] → [IPN: PAID ✓]

Học sinh Nguyễn Văn A
  └─ VA: VA200050 (cố định cả năm học)
       ├─ Tháng 9:   chuyển 2,500,000đ  →  IPN: Sep fee PAID ✓
       └─ Tháng 10:  chuyển 2,500,000đ  →  IPN: Oct fee PAID ✓

1. Nhập học
   └─ POST /openapi/v1/va/va-account/create
        { bank_code: "970403", account_name: "NGUYEN VAN A - LOP 10A1" }
        → VA mới: VA300125
 
2. Gửi VA cho phụ huynh
   └─ In trên phiếu thu, gửi qua app/email
 
3. Phụ huynh chuyển khoản vào VA300125 (hàng tháng)
   └─ Hệ thống tự nhận diện: học sinh A, 2,500,000đ
 
4. IPN Callback tự động
   └─ { order_id: "SCHOOL-A-SEP2026", amount: 2500000 }
      → Cập nhật trạng thái học phí trong phần mềm quản lý

Bệnh nhân vào viện → Tạo VA cho đợt điều trị
  └─ VA: VA400200  "NGUYEN THI B - DOT DIEU TRI 15052026"
       │
       ├─ Lần 1: Viện phí khám ban đầu        500,000đ
       ├─ Lần 2: Tiền thuốc ngày 1          1,200,000đ
       ├─ Lần 3: Phí phẫu thuật            15,000,000đ
       └─ Lần 4: Tiền phòng 3 ngày          1,500,000đ
            │
            └─ Mỗi IPN: loại viện phí + mã đợt điều trị
               → HIS tự cập nhật từng khoản phí

# Tiếp nhận bệnh nhân
POST /openapi/v1/va/va-account/create
  bank_code: "970415"  (Vietinbank)
  account_name: "{patient.name} - {admission.code}"
→ Lưu va_number vào bản ghi đợt điều trị
 
# IPN Handler
function handleIPN(encryptedData):
    txn = AES_decrypt(encryptedData)
    admission = db.find(txn.order_id)
    admission.addPayment(amount=txn.amount, ref=txn.retrieval_ref_no)
    return 200 OK

Quầy thu ngân #1  →  VA cố định #1  →  QR động theo order_id
Quầy thu ngân #2  →  VA cố định #2  →  QR động theo order_id

# POS tạo QR khi khách checkout
POST /openapi/v1/qr/create
  order_id: "STORE01-CASH01-{invoice.id}"
  va: store.va_number
  bincode: "970454"
  service_code: "bidv-qr"
  amount: invoice.total
→ Hiển thị QR trên màn hình khách
 
# Sau khi nhận IPN → POS tự đóng đơn

Doanh nghiệp ABC
  └─ VA: VA500010 (hợp đồng năm 2026)
       ├─ Tháng 5/2026:  1,200,000đ → Gia hạn tháng 6 ✓
       ├─ Tháng 6/2026:  1,200,000đ → Gia hạn tháng 7 ✓
       └─ ...

# 1. Login
POST /openapi/v1/auth/login
  { partner_code: "YOUR_PARTNER_CODE", ... }
→ access_token
 
# 2. Tạo VA
POST /openapi/v1/va/va-account/create
  { bank_code: "970454", account_name: "NGUYEN VAN A LOP 10A1" }

// Response
{ "va_number": "VA100023312", "bank_code": "970454",
  "account_name": "NGUYEN VAN A LOP 10A1", "status": "active" }

POST /openapi/v1/qr/create
  { order_id: "SCHOOL-NGUYENVANA-SEP2026", va: "VA100023312",
    bincode: "970454", service_code: "bidv-qr", amount: 2500000 }

function handleIPN(encryptedData):
    txn = AES_decrypt(encryptedData)
 
    # Kiểm tra đã xử lý chưa (idempotency)
    if cache.exists("ipn:" + txn.request_id):
        return 200 OK  # Trả 200 để TConnect không retry
 
    cache.set("ipn:" + txn.request_id, ttl=24h)
    processPayment(txn)
    return 200 OK

if txn.amount < expected_amount:
    admission.addPartialPayment(txn.amount)
    # Gửi thông báo yêu cầu nộp bổ sung
elif txn.amount > expected_amount:
    admission.addOverpayment(txn.amount - expected_amount)
    # Cờ để xử lý hoàn tiền thừa
else:
    admission.markFullyPaid()