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.
- Danh sách VA —
GET /api/virtual-accounts - Tạo VA —
POST /api/virtual-accounts - Sửa tên VA —
PATCH /api/virtual-accounts/{id} - Đóng / mở lại VA —
POST /api/virtual-accounts/{id}/close,POST /api/virtual-accounts/{id}/open - Đóng VA hàng loạt —
POST /api/virtual-accounts/bulk-close - Xoá VA —
DELETE /api/virtual-accounts/{id}
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ặccreated_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": [...] } } |