Tài liệu API
Hướng dẫn gọi API ViePay: endpoint, header và tham số.
Base URL
https://vieconnections.site
Endpoints v1:
- POST
/api/v1/cash-in— Tạo giao dịch nạp - GET
/api/v1/cash-in/status— Kiểm tra trạng thái nạp - POST
/api/v1/cash-out— Tạo giao dịch rút - GET
/api/v1/cash-out/status— Kiểm tra trạng thái rút
Thông tin API Key
Dùng APIKEY và Checksum (HMAC-MD5) trong header mọi request.
—
—
POST https://vieconnections.site/api/v1/cash-in — Tạo giao dịch nạp
Nạp tiền qua ngân hàng (QR). Cần APIKEY + Checksum.
Params (Body)
Headers: Content-Type: application/json, APIKEY, Checksum (HMAC-MD5 chuỗi body ký theo thứ tự amount, ref_id, callback, hex)
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
type | string | ✓ | bank hoặc momo |
amount | number | ✓ | Số tiền VNĐ |
ref_id | string | ✓ | Mã đơn duy nhất |
bank_type | string | bank | Mã ngân hàng (VD: VCB) – chỉ dùng khi type = bank |
callback | string | ✓ | URL nhận thông báo |
Body example:
{
"type": "bank",
"amount": 10000,
"ref_id": "ORDER_001",
"bank_type": "VCB",
"callback": "https://example.com/callback"
}
Response example:
{
"success": true,
"system_ref_id": "xxx",
"qr_link": "https://...",
"fee_amount": 2000,
"amount_after_fee": 98000
}
POST https://vieconnections.site/api/v1/cash-out — Tạo giao dịch rút
Rút theo số dư. Cần APIKEY + Checksum.
Params (Body)
Headers: Content-Type: application/json, APIKEY, Checksum (HMAC-MD5 toàn bộ body, hex)
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
ref_id | string | ✓ | Mã đơn duy nhất |
amount | number | ✓ | Số tiền VNĐ |
type | string | ✓ | bank | momo |
message | string | ✓ | Nội dung chuyển khoản |
callback | string | ✓ | URL nhận thông báo |
bank_type | string | bank | Mã ngân hàng (VD: VCB) |
stk | string | bank | Số tài khoản |
name | string | bank/momo | Tên chủ tài khoản |
receiver | string | momo | SĐT ví Momo |
Body example (type=bank):
{
"ref_id": "W001",
"amount": 10000,
"type": "bank",
"message": "Rut tien",
"callback": "https://example.com/callback",
"bank_type": "VCB",
"stk": "1234567890",
"name": "NGUYEN VAN A"
}
Response example:
{
"success": true,
"ref_id": "W001",
"amount": 10000,
"status": "PENDING"
}
GET /api/deposit/banks — Danh sách ngân hàng
Lấy danh sách bank hỗ trợ nạp tiền. Cần APIKEY.
Checksum calculator
Tạo HMAC-MD5 checksum từ chuỗi và Private Key.
GET /api/v1/cash-in/status & GET /api/v1/cash-out/status
Tra cứu trạng thái giao dịch theo ref_id. Bắt buộc gửi APIKEY trong header.
1. GET /api/v1/cash-in/status
Headers: APIKEY: YOUR_API_KEY
Query Params
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
ref_id |
string | ✓ | Mã đơn nạp (trùng với ref_id khi gọi /api/v1/cash-in) |
Ví dụ request:
GET https://vieconnections.site/api/v1/cash-in/status?ref_id=ORDER_001 APIKEY: <YOUR_API_KEY>
Ví dụ response (thành công):
{
"success": true,
"ref_id": "ORDER_001",
"amount": 10000,
"fee_amount": 3200,
"status": "SUCCESS",
"created_at": "2026-03-02T10:15:30.000Z",
"updated_at": "2026-03-02T10:17:05.000Z"
}
Ví dụ response (không tìm thấy):
{
"success": false,
"error": "Transaction not found"
}
2. GET /api/v1/cash-out/status
Headers: APIKEY: YOUR_API_KEY
Query Params
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
ref_id |
string | ✓ | Mã đơn rút (trùng với ref_id khi gọi /api/v1/cash-out) |
Ví dụ request:
GET https://vieconnections.site/api/v1/cash-out/status?ref_id=W001 APIKEY: <YOUR_API_KEY>
Ví dụ response (thành công):
{
"success": true,
"ref_id": "W001",
"amount": 10000,
"status": "SUCCESS",
"type": "bank",
"created_at": "2026-03-02T11:00:00.000Z",
"updated_at": "2026-03-02T11:05:10.000Z"
}
Ví dụ response (thất bại, có lý do):
{
"success": true,
"ref_id": "W002",
"amount": 50000,
"status": "FAILED",
"type": "bank",
"created_at": "2026-03-02T11:10:00.000Z",
"updated_at": "2026-03-02T11:10:30.000Z",
"err_msg": "Số tiền không hợp lệ"
}
Bank type List
Danh sách bank_type hỗ trợ nạp tiền qua v1 (tương đương bank code).
| Code (bank_type) | Bank Name |
|---|---|
ABB | ABBANK |
ACB | ACB |
AGR | Agribank |
BAB | Bac A Bank |
VCCB | BanVietBank |
BVB | Bao Viet Bank |
BIDV | BIDV |
CAKE | Cake by VPBank |
DAB | Dong A Bank |
EIB | Eximbank |
HDB | HD Bank |
KLB | KienLong Bank |
LPB | LienVietPostBank |
MSB | Maritime Bank |
MBB | MB Bank |
NAB | Nam A Bank |
OCB | Orient Commercial Bank |
PGB | PG Bank |
PVC | PVComBank |
STB | Sacombank |
SCB | Sai Gon Commercial Bank |
SGB | Saigonbank |
SEAB | SeaBank |
SHB | SHB bank |
SHBVN | Shinhan bank Việt Nam |
TCB | Techcombank |
TPB | TienPhong Bank |
VIB | VIB |
VBB | VietBank |
VCB | Vietcombank |
VTB | Vietinbank |
VPB | VP Bank |