Bỏ qua tới nội dung
Tài liệu Lấy API Token
Trong trang này

Tài khoản ảo (VA)

Tài khoản ảo (VA) gắn với một tài khoản ngân hàng của bạn. Khách hàng chuyển khoản vào số VA, giao dịch sẽ được ghi nhận vào tài khoản ngân hàng gốc và gửi tới webhook kèm virtual_number.

Tất cả đều yêu cầu Authorization: Bearer {token} (xem Xác thực). Lấy bank_account_id từ API Tài khoản ngân hàng.

#Danh sách VA

GET /api/virtual-accounts

Trả về VA thuộc các tài khoản ngân hàng của chủ token, mới tạo trước, có phân trang.

#Tham số truy vấn

Tất cả đều tùy chọn.

Tham số Kiểu Mặc định Mô tả
bank_account_id string (UUID) — Chỉ lấy VA của một tài khoản ngân hàng. UUID không thuộc về bạn → danh sách rỗng
status int — 1 = hoạt động, 0 = tạm dừng
q string — Tìm kiếm (LIKE) theo số VA hoặc tên VA
per_page int (1–100) 20 Số bản ghi mỗi trang
page int 1 Trang hiện tại

#Ví dụ request

curl -G "https://qh2pay.com/api/virtual-accounts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "bank_account_id=ca0a96f9-7ac2-4470-be2f-89f854a27cef" \
  --data-urlencode "status=1"

#Response 200 OK

{
    "data": [
        {
            "id": 1024,
            "bank_account_id": "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
            "account_number": "V3QHTKH001",
            "va_number": "KH001",
            "account_name": "NGUYEN VAN A",
            "status": 1,
            "created_at": "2026-11-03 10:15:00"
        }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": null },
    "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}

Ý nghĩa các field xem ở Response của Tạo VA.

#Tạo VA

POST /api/virtual-accounts
  • Chỉ tạo được VA cho tài khoản ngân hàng thuộc về chủ token và đã được cấu hình tiền tố VA.

#Tham số (body JSON)

Tham số Kiểu Bắt buộc Mô tả
bank_account_id string (UUID) Có ID tài khoản ngân hàng, lấy từ field id của API Tài khoản ngân hàng
va_number string Không Phần đuôi số VA, 1–7 ký tự A-Z, 0-9 (chữ thường tự đổi sang in hoa). Bỏ trống → hệ thống tự sinh 5 ký tự ngẫu nhiên
account_name string Không Tên hiển thị của VA, tối đa 50 ký tự. Tự bỏ dấu và in hoa (Nguyễn Văn A → NGUYEN VAN A). Bỏ trống → lấy theo tên chủ tài khoản ngân hàng

Số VA đầy đủ = tiền tố VA của tài khoản ngân hàng + va_number. Ví dụ tiền tố V3QHT, va_number = KH001 → số VA V3QHTKH001. Số VA là duy nhất trong toàn hệ thống.

#Ví dụ request

curl -X POST "https://qh2pay.com/api/virtual-accounts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_account_id": "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
    "va_number": "KH001",
    "account_name": "Nguyễn Văn A"
  }'
const res = await fetch("https://qh2pay.com/api/virtual-accounts", {
    method: "POST",
    headers: {
        Authorization: `Bearer ${API_TOKEN}`,
        Accept: "application/json",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        bank_account_id: "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
        va_number: "KH001",
        account_name: "Nguyễn Văn A",
    }),
});
const json = await res.json();

#Response 201 Created

{
    "data": {
        "id": 1024,
        "bank_account_id": "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
        "account_number": "V3QHTKH001",
        "va_number": "KH001",
        "account_name": "NGUYEN VAN A",
        "status": 1,
        "created_at": "2026-11-03 10:15:00"
    }
}

Mô tả field

Field Kiểu Mô tả
id int ID của VA trong hệ thống QHTech
bank_account_id string (UUID) Tài khoản ngân hàng gốc
account_number string Số VA đầy đủ — dùng để khách hàng chuyển khoản
va_number string Phần đuôi số VA (không gồm tiền tố)
account_name string Tên hiển thị của VA
status int 1 = hoạt động, 0 = tạm dừng. VA mới tạo luôn ở trạng thái hoạt động
created_at string Thời điểm tạo (Y-m-d H:i:s)

#Lỗi

Tình huống HTTP Body
Thiếu / sai token 401 { "message": "API Token không hợp lệ." }
bank_account_id không tồn tại hoặc không thuộc về bạn 422 { "message": "Tài khoản ngân hàng không tồn tại hoặc không thuộc về bạn.", "errors": { "bank_account_id": [...] } }
va_number / account_name sai định dạng 422 { "message": "...", "errors": { "va_number": [...] } }
Số VA đã tồn tại 422 { "message": "Số VA đã tồn tại.", "errors": { "va_number": ["Số VA đã tồn tại."] } }
Tài khoản ngân hàng chưa có tiền tố VA 422 { "message": "Tài khoản ngân hàng này chưa được cấu hình tiền tố VA, không thể tạo VA." }

#Sửa tên VA

PATCH /api/virtual-accounts/{id}

Chỉ sửa được tên của VA. Số VA không thay đổi được — muốn đổi số, hãy tạo VA mới và xoá VA cũ.

#Tham số (body JSON)

Tham số Kiểu Bắt buộc Mô tả
account_name string Có Tên mới, tối đa 50 ký tự. Tự bỏ dấu và in hoa (Trần Thị Bé → TRAN THI BE)

#Ví dụ request

curl -X PATCH "https://qh2pay.com/api/virtual-accounts/1024" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "account_name": "Trần Thị Bé" }'

#Response 200 OK

Trả về VA sau khi sửa, cùng cấu trúc với Response của Tạo VA:

{
    "data": {
        "id": 1024,
        "bank_account_id": "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
        "account_number": "V3QHTKH001",
        "va_number": "KH001",
        "account_name": "TRAN THI BE",
        "status": 1,
        "created_at": "2026-11-03 10:15:00"
    }
}

#Đóng / mở lại VA

POST /api/virtual-accounts/{id}/close
POST /api/virtual-accounts/{id}/open
  • Đóng (close): chuyển VA sang trạng thái tạm dừng (status = 0). Ngân hàng tra cứu số VA đã đóng sẽ nhận kết quả mã khách hàng không tồn tại, nên khách hàng không chuyển khoản vào được.
  • Mở lại (open): chuyển VA về trạng thái hoạt động (status = 1).
  • Không cần body. Gọi lại khi VA đã ở đúng trạng thái vẫn trả 200.

#Ví dụ request

curl -X POST "https://qh2pay.com/api/virtual-accounts/1024/close" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

#Response 200 OK

Trả về VA sau khi đổi trạng thái, cùng cấu trúc với Response của Tạo VA, trong đó status là trạng thái mới.

#Đóng VA hàng loạt

POST /api/virtual-accounts/bulk-close

Đóng nhiều VA cùng lúc (chuyển sang status = 0, giống Đóng VA). Chọn một trong hai cách:

  • Theo danh sách: truyền account_numbers — tối đa 500 số VA mỗi lần.
  • Theo ngày tạo: truyền created_date (một ngày) hoặc created_from + created_to (tối đa 31 ngày). Ngày tính theo giờ Việt Nam, lấy trọn ngày (00:00:00 – 23:59:59).

Chỉ đóng VA thuộc tài khoản ngân hàng của chủ token. VA đã đóng sẵn được bỏ qua (đếm trong already_closed).

Nên gọi trước với "dry_run": true để xem danh sách VA sẽ bị đóng, rồi mới gọi thật.

#Tham số (body JSON)

Tham số Kiểu Bắt buộc Mô tả
account_numbers array of string * Danh sách số VA đầy đủ (VD V3QHTKH001), không phân biệt hoa thường. Tối đa 500
created_date date (Y-m-d) * Đóng các VA tạo trong ngày này
created_from date (Y-m-d) * Ngày bắt đầu (bao gồm). Đi kèm created_to
created_to date (Y-m-d) * Ngày kết thúc (bao gồm). Không quá 31 ngày kể từ created_from
bank_account_id string (UUID) Không Chỉ đóng VA của một tài khoản ngân hàng
dry_run boolean Không true = chỉ xem trước, không đóng VA nào. Mặc định false

* Bắt buộc một trong hai cách: account_numbers, hoặc created_date, hoặc created_from + created_to.

#Ví dụ request

Đóng theo danh sách:

curl -X POST "https://qh2pay.com/api/virtual-accounts/bulk-close" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ "account_numbers": ["V3QHTKH001", "V3QHTKH002"] }'

Xem trước các VA tạo ngày 05/11/2026 của một tài khoản ngân hàng:

curl -X POST "https://qh2pay.com/api/virtual-accounts/bulk-close" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
        "created_date": "2026-11-05",
        "bank_account_id": "ca0a96f9-7ac2-4470-be2f-89f854a27cef",
        "dry_run": true
    }'

#Response 200 OK

{
    "message": "Đã đóng 1 VA.",
    "data": {
        "dry_run": false,
        "closed": 1,
        "already_closed": 0,
        "closed_account_numbers": ["V3QHTKH001"],
        "not_found": ["V3QHTKH002"]
    }
}
Field Kiểu Mô tả
dry_run boolean true nếu chỉ là xem trước
closed int Số VA đã đóng (hoặc sẽ đóng nếu dry_run)
already_closed int Số VA khớp điều kiện nhưng đã đóng từ trước
closed_account_numbers array of string Danh sách số VA đã đóng (hoặc sẽ đóng)
not_found array of string Chỉ khi đóng theo danh sách: số VA không tồn tại hoặc không thuộc về bạn

#Lỗi

Tình huống HTTP
Thiếu / sai token 401
Không truyền cách nào, hoặc truyền cả hai cách 422
Ngày sai định dạng, created_to trước created_from, quá 31 ngày 422
Quá 500 số VA 422
Gọi quá 30 lần / phút 429

#Xoá VA

DELETE /api/virtual-accounts/{id}

Xoá hẳn VA, không khôi phục được. Giao dịch cũ của VA vẫn được giữ trong lịch sử giao dịch (field virtual_number). Nếu chỉ muốn tạm ngưng nhận tiền, hãy dùng Đóng VA.

#Ví dụ request

curl -X DELETE "https://qh2pay.com/api/virtual-accounts/1024" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

#Response 200 OK

{
    "message": "Xoá VA thành công.",
    "data": { "id": 1024 }
}

#Lỗi chung khi sửa / đóng / xoá

Tình huống HTTP Body
Thiếu / sai token 401 { "message": "API Token không hợp lệ." }
id không tồn tại hoặc VA không thuộc về bạn 404 { "message": "VA không tồn tại hoặc không thuộc về bạn." }
account_name thiếu hoặc sai định dạng (khi sửa) 422 { "message": "...", "errors": { "account_name": [...] } }