Markdown for AI agents
# Tài liệu tích hợp API — dùng cho trợ lý AI
Base URL: `https://www.doithevip.com`
## Xác thực
### Partner API
- Credentials: `partner_id` + `partner_key`
- ChargingWS sign (checksign=1): `md5(partner_key+code+serial)` hoặc full `md5(partner_key+code+command+partner_id+request_id+serial+telco)`
- Cardws sign: `md5(partner_key+partner_id+command+request_id)`
- Rechargews topup/getstatus/canceltopup: `md5(partner_key+partner_id+command+request_id)`
- Rechargews productlist/getbalance/feetopup: `md5(partner_key+partner_id+command)` (không request_id)
- Verifycard: `md5(partner_key+serial)`
- Rechargews: **POST only**
### Client API (`/api/client/*`)
- Auth: `api_key` + IP whitelist
- **Không** dùng `api_token`, **không** ký MD5, **không** dùng `partner_id`
- Tra cứu đơn theo `api_key` (user) + `request_id`
- Callback (tuỳ chọn): gửi kèm `callback` ở `/api/client/charging/post` và `/api/client/recharge/buy` để nhận kết quả async; không gửi thì poll status
- Envelope thường: `{status:number, message, data}` (một số softcard success trả raw object)
## Endpoints
### Partner / Giới thiệu Partner API
Partner API dùng partner_id + partner_key. Một số endpoint bắt buộc IP whitelist của merchant/admin. Base URL: domain website.
#### Gửi thẻ lên hệ thống
- Method: `POST`
- Path: `/chargingws/v2`
- Sign: `md5(partner_key+code+serial) hoặc md5(partner_key+code+command+partner_id+request_id+serial+telco) khi checksign=1`
Request:
```json
{
"telco": "VIETTEL",
"code": "123456789012",
"serial": "10001234567890",
"amount": "50000",
"request_id": "REQ-CHG-001",
"partner_id": "YOUR_PARTNER_ID",
"sign": "REPLACE_WITH_MD5",
"command": "charging"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/chargingws/v2' -H 'Content-Type: application/x-www-form-urlencoded' -d 'telco=VIETTEL&code=123456789012&serial=10001234567890&amount=50000&request_id=REQ-CHG-001&partner_id=YOUR_PARTNER_ID&sign=REPLACE_WITH_MD5&command=charging'
```
Response — 99 — PENDING:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"telco": "VIETTEL",
"serial": "10001234567890",
"code": "123456789012",
"declared_value": 50000,
"amount": 47500,
"value": null,
"status": 99,
"message": "PENDING",
"callback_sign": "..."
}
```
Response — 1 — VALID_CARD:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 1,
"message": "VALID_CARD",
"value": 50000,
"declared_value": 50000,
"amount": 47500
}
```
Response — 2 — CARD_WRONG_VALUE:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 2,
"message": "CARD_WRONG_VALUE",
"value": 20000,
"declared_value": 50000,
"amount": 19000
}
```
Response — 3 — INVALID_CARD:
```json
{
"request_id": "REQ-CHG-001",
"status": 3,
"message": "INVALID_CARD"
}
```
Response — 102 — Validate fail:
```json
{
"trans_id": 0,
"request_id": "REQ-CHG-001",
"status": 102,
"message": "INVALID_SIGNATURE"
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Kiểm tra trạng thái thẻ
- Method: `POST`
- Path: `/chargingws/v2`
- Sign: `Giống gửi thẻ (khi checksign=1)`
Request:
```json
{
"command": "check",
"telco": "VIETTEL",
"code": "123456789012",
"serial": "10001234567890",
"amount": "50000",
"request_id": "REQ-CHG-001",
"partner_id": "YOUR_PARTNER_ID",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/chargingws/v2' -d 'command=check&telco=VIETTEL&code=123456789012&serial=10001234567890&amount=50000&request_id=REQ-CHG-001&partner_id=YOUR_PARTNER_ID&sign=REPLACE_WITH_MD5'
```
Response — Thành công:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 1,
"message": "VALID_CARD",
"telco": "VIETTEL",
"declared_value": 50000,
"value": 50000,
"amount": 47500
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Lấy giá đổi thẻ (mảng)
- Method: `GET`
- Path: `/chargingws/v2/getfee`
- Sign: `Không bắt buộc sign`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID"
}
```
cURL:
```bash
curl -X GET 'https://www.doithevip.com/chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID'
```
Response — Thành công:
```json
[
{
"telco": "VIETTEL",
"value": 10000,
"fees": 20,
"penalty": 50
},
{
"telco": "VIETTEL",
"value": 50000,
"fees": 18,
"penalty": 50
},
{
"telco": "MOBIFONE",
"value": 10000,
"fees": 22,
"penalty": 50
}
]
```
#### Lấy giá đổi thẻ (group telco)
- Method: `GET`
- Path: `/chargingws/price`
- Sign: `Không bắt buộc sign`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID"
}
```
cURL:
```bash
curl -X GET 'https://www.doithevip.com/chargingws/price?partner_id=YOUR_PARTNER_ID'
```
Response — Thành công:
```json
{
"VIETTEL": [
{
"telco": "VIETTEL",
"value": 10000,
"fees": 20,
"penalty": 50
}
],
"MOBIFONE": [
{
"telco": "MOBIFONE",
"value": 10000,
"fees": 22,
"penalty": 50
}
]
}
```
#### Callback về bạn (POST JSON)
- Method: `GET`
- Path: `/your-callback-url`
- Sign: `md5(partner_key+code+serial) — nếu dùng charging.callback riêng: md5(partner_id+code+serial)`
Request:
```json
{
"status": 1,
"message": "VALID_CARD",
"request_id": "REQ-CHG-001",
"declared_value": 50000,
"value": 50000,
"card_value": 50000,
"amount": 47500,
"code": "123456789012",
"serial": "10001234567890",
"telco": "VIETTEL",
"trans_id": 1001,
"callback_sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/your-callback-url' -H 'Content-Type: application/json' -d '{...}'
```
Response — Phản hồi từ phía bạn:
```json
{
"status": "success"
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Callback về bạn (GET)
- Method: `GET`
- Path: `/your-callback-url`
- Sign: `md5(partner_key+code+serial)`
Request:
```json
{
"status": "1",
"request_id": "REQ-CHG-001",
"callback_sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X GET 'https://www.doithevip.com/your-callback-url?status=1&request_id=REQ-CHG-001&callback_sign=REPLACE_WITH_MD5&...'
```
Response — Phản hồi từ phía bạn:
```json
{
"status": "success"
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Kiểm tra seri
- Method: `POST`
- Path: `/api/verifycard`
- Sign: `md5(partner_key + serial)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"telco": "VIETTEL",
"serial": "10001234567890",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/verifycard' -H 'Content-Type: application/json' -d '{"partner_id":"YOUR_PARTNER_ID","telco":"VIETTEL","serial":"10001234567890","sign":"REPLACE_WITH_MD5"}'
```
Response — Thành công:
```json
{
"status": "success",
"data": {
"status": "checked",
"serial": "10001234567890",
"card_status": "available",
"value": 50000,
"date_used": null,
"acc_charged": null
}
}
```
Response — Sai chữ ký:
```json
{
"status": "invalid_sign",
"data": null
}
```
#### Mua thẻ cào
- Method: `POST`
- Path: `/api/cardws`
- Sign: `md5(partner_key + partner_id + command + request_id)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "buycard",
"request_id": "REQ-BUY-001",
"service_code": "VIETTEL",
"value": 10000,
"qty": 1,
"wallet_number": "YOUR_WALLET_NUM",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/cardws' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Thành công:
```json
{
"status": 1,
"message": "Mua thẻ thành công.",
"data": {
"cards": [
{
"name": "Viettel 10k",
"serial": "S1",
"code": "C1",
"expired": "2027-01-01"
}
],
"time": "2026-07-25 09:00:00",
"request_id": "REQ-BUY-001",
"order_code": "SC123"
}
}
```
Response — 130 — Lấy thẻ thất bại:
```json
{
"status": 130,
"message": "..."
}
```
Response — 116 — Sai chữ ký:
```json
{
"status": 116,
"message": "Sai chữ ký sign."
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Kiểm tra tồn kho
- Method: `POST`
- Path: `/api/cardws`
- Sign: `md5(partner_key + partner_id + command + request_id) — bắt buộc`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "checkavailable",
"service_code": "VIETTEL",
"value": 10000,
"qty": 1,
"wallet_number": "YOUR_WALLET_NUM",
"request_id": "",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/cardws' -H 'Content-Type: application/json' -d '{...}'
```
Response — Còn hàng:
```json
{
"stock_available": true,
"VT10": "Còn hàng"
}
```
Response — Hết hàng:
```json
{
"stock_available": false,
"VT10": "Hết hàng"
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Tải lại thẻ
- Method: `POST`
- Path: `/api/cardws`
- Sign: `md5(partner_key + partner_id + command + request_id)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "redownload",
"request_id": "REQ-BUY-001",
"wallet_number": "YOUR_WALLET_NUM",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/cardws' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Thành công:
```json
{
"status": 1,
"data": {
"cards": [
{
"name": "Viettel 10k",
"serial": "S1",
"code": "C1"
}
],
"request_id": "REQ-BUY-001",
"order_code": "SC123"
}
}
```
Response — 2 — Pending:
```json
{
"status": 2,
"message": "Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút."
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Lấy số dư
- Method: `POST`
- Path: `/api/cardws`
- Sign: `md5(partner_key + partner_id + command + request_id) — request_id có thể rỗng`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "getbalance",
"request_id": "",
"wallet_number": "YOUR_WALLET_NUM",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/cardws' -H 'Content-Type: application/json' -d '{...}'
```
Response — Thành công:
```json
{
"balance": 1500000,
"currency_code": "VND"
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Lấy danh sách thẻ
- Method: `GET`
- Path: `/api/cardws/products`
- Sign: `Không bắt buộc sign`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID"
}
```
cURL:
```bash
curl -X GET 'https://www.doithevip.com/api/cardws/products?partner_id=YOUR_PARTNER_ID'
```
Response — Thành công:
```json
[
{
"name": "Viettel",
"slug": "viettel",
"service_code": "VIETTEL",
"image": "/upload/product/viettel.png",
"imgurl": "https://example.com/upload/product/viettel.png",
"cardvalue": [
{
"id": 1,
"service_code": "VIETTEL",
"value": 10000,
"discount": 2.5,
"price": 9750
}
]
}
]
```
#### Tạo lệnh nạp
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command + request_id)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "topup",
"request_id": "REQ-TOP-001",
"service_code": "VIETTEL_TOPUP",
"amount": 50000,
"account_info": {
"phone": "0901234567"
},
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — success:
```json
{
"status": "success",
"data": {
"time": "2026-07-25 09:00:00",
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"pay_amount": 49000,
"discount": 2,
"service_code": "VIETTEL_TOPUP",
"amount": 50000,
"status": "pending"
}
}
```
#### Lấy trạng thái
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command + request_id)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "getstatus",
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — pending:
```json
{
"status": "success",
"data": {
"account": {
"phone": "0901234567"
},
"request_value": 50000,
"amount": 50000,
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"status": "pending"
}
}
```
Response — completed:
```json
{
"status": "success",
"data": {
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"status": "completed"
}
}
```
Response — order_not_found:
```json
{
"status": "order_not_found",
"message": "..."
}
```
#### Lấy danh sách sản phẩm
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command) — không ghép request_id`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "productlist",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — success:
```json
{
"status": "success",
"data": [
{
"name": "Viettel Topup",
"service_code": "VIETTEL_TOPUP",
"type": "topup",
"items": [
{
"name": "10.000đ",
"value": 10000,
"price": 9800,
"discount": 2
}
],
"options": []
}
]
}
```
#### Lấy số dư
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command) — không ghép request_id`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "getbalance",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — success:
```json
{
"status": "success",
"data": {
"balance": 1500000,
"currency": "VND"
}
}
```
#### Hủy lệnh nạp
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command + request_id)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "canceltopup",
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — success:
```json
{
"status": "success",
"data": {
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"status": "canceled"
}
}
```
#### Bảng phí topup
- Method: `POST`
- Path: `/api/rechargews`
- Sign: `md5(partner_key + partner_id + command)`
Request:
```json
{
"partner_id": "YOUR_PARTNER_ID",
"command": "feetopup",
"sign": "REPLACE_WITH_MD5"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/rechargews' -H 'Content-Type: application/json' -d '{...}'
```
Response — success:
```json
{
"status": "success",
"data": [
{
"key": "VIETTEL_TOPUP",
"value": 10000,
"price": 9800,
"discount": 2
}
]
}
```
### Client / Giới thiệu Client API
Client API dùng api_key của user (+ IP whitelist admin/user). Không có api_token, không ký MD5, không dùng partner_id. Có thể gửi kèm callback (URL) ở đổi thẻ / nạp topup để nhận kết quả. Envelope phổ biến: {status:number, message, data}.
#### Lấy thông tin tài khoản
- Method: `POST`
- Path: `/api/client/info`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/info' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "Success",
"data": {
"id": 10,
"username": "demo",
"email": "[email protected]",
"phone": "0901234567",
"group": 1
}
}
```
Response — 16 — IP denied:
```json
{
"status": 16,
"message": "ip_denied",
"data": []
}
```
Response — 15 — User not found:
```json
{
"status": 15,
"message": "user_not_found",
"data": []
}
```
#### Lấy số dư
- Method: `POST`
- Path: `/api/client/balance`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"currency_code": "VND"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/balance' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY","currency_code":"VND"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": {
"balance": 1500000,
"currency_code": "VND"
}
}
```
Response — 3 — Missing currency_code:
```json
{
"status": 3,
"message": "invalid_data",
"data": []
}
```
Response — 6 — Wallet not found:
```json
{
"status": 6,
"message": "Wallet not found",
"data": []
}
```
#### Danh sách ngân hàng rút
- Method: `POST`
- Path: `/api/client/withdraw_banks`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/withdraw_banks' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "Success",
"data": [
[
{
"id": 1,
"code": "Localbank_VCB",
"paygate": "Localbank",
"name": "Vietcombank"
}
]
]
}
```
Response — 18 — Not found:
```json
{
"status": 18,
"message": "Withdraw bank not found",
"data": []
}
```
#### Rút tiền ví
- Method: `POST`
- Path: `/api/client/withdraw`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"currency_code": "VND",
"bank_code": "Localbank_VCB",
"receive_account_number": "0123456789",
"receive_account_name": "NGUYEN VAN A",
"amount": 100000,
"description": "RUTAPI001"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/withdraw' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "Success",
"data": {
"type": "Withdraw",
"order_code": "W123",
"net_amount": 100000,
"fees": 1100,
"pay_amount": 101100,
"status": "pending"
}
}
```
Response — 3 — Invalid data:
```json
{
"status": 3,
"message": "Invalid data",
"data": []
}
```
Response — 7 — Balance insufficient:
```json
{
"status": 7,
"message": "Balance insufficient",
"data": []
}
```
Response — 5 — Bank not support:
```json
{
"status": 5,
"message": "Not support this bank",
"data": []
}
```
#### Lấy thông tin đơn hàng
- Method: `POST`
- Path: `/api/client/get_order`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"order_code": "W123"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/get_order' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "Success",
"data": {
"order_code": "W123",
"type": "Withdraw",
"status": "pending"
}
}
```
Response — 17 — Not found:
```json
{
"status": 17,
"message": "Order not found",
"data": []
}
```
#### Gửi thẻ
- Method: `POST`
- Path: `/api/client/charging/post`
- Sign: `Không dùng sign`
- Callback: gửi kèm `callback` (URL) nếu muốn nhận kết quả async; không gửi thì poll `/api/client/charging/status`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"telco": "VIETTEL",
"code": "123456789012",
"serial": "10001234567890",
"amount": "50000",
"request_id": "REQ-CHG-001",
"callback": "https://your-domain.com/callback/charging"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/charging/post' -H 'Content-Type: application/json' -d '{...}'
```
Response — PENDING:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 99,
"message": "PENDING",
"telco": "VIETTEL",
"declared_value": 50000
}
```
Response — VALID_CARD:
```json
{
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 1,
"message": "VALID_CARD",
"value": 50000
}
```
Response — 19 — Fail:
```json
{
"status": 19,
"message": "...",
"data": []
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Callback đổi thẻ (Client) — POST JSON về URL bạn gửi
- Method: `POST` (hệ thống gọi URL `callback` của bạn)
- Path: URL bạn khai báo ở field `callback`
- Sign: `callback_sign = md5(code + serial)` (Client API không dùng partner_id)
Payload hệ thống gửi:
```json
{
"status": 1,
"message": "CARD_CORRECT",
"request_id": "REQ-CHG-001",
"declared_value": 50000,
"value": 50000,
"card_value": 50000,
"amount": 47500,
"code": "123456789012",
"serial": "10001234567890",
"telco": "VIETTEL",
"trans_id": 1001,
"callback_sign": "REPLACE_WITH_MD5"
}
```
Ghi chú message callback: `CARD_CORRECT` / `WRONG_VALUE` / `CARD_INVALID` / `CARD_MAINTENANCE` / `CARD_PENDING`.
#### Trạng thái thẻ
- Method: `POST`
- Path: `/api/client/charging/status`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"request_id": "REQ-CHG-001"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/charging/status' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": {
"trans_id": 1001,
"request_id": "REQ-CHG-001",
"status": 1,
"message": "VALID_CARD"
}
}
```
Response — 20 — Not found:
```json
{
"status": 20,
"message": "card_not_existed",
"data": []
}
```
**Mã lỗi:**
- `1`: Thẻ thành công đúng mệnh giá
- `2`: Thẻ thành công sai mệnh giá
- `3`: Thẻ lỗi
- `4`: Hệ thống bảo trì
- `99`: Thẻ chờ xử lý
- `100`: Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về
#### Bảng phí đổi thẻ
- Method: `POST`
- Path: `/api/client/charging/fee`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/charging/fee' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": {
"VIETTEL": [
{
"telco": "VIETTEL",
"value": 10000,
"fees": 20,
"penalty": 50
}
]
}
}
```
#### Mua thẻ
- Method: `POST`
- Path: `/api/client/softcard/buy`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"qty": 1,
"value": 10000,
"service_code": "VIETTEL",
"request_id": "REQ-BUY-001"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/softcard/buy' -H 'Content-Type: application/json' -d '{...}'
```
Response — Success raw:
```json
{
"order_code": "SC123",
"time": "2026-07-27 10:00:00",
"cards": [
{
"name": "Viettel 10k",
"serial": "S1",
"code": "C1",
"expire": "2027-01-01"
}
]
}
```
Response — 23 — insufficient_balance:
```json
{
"status": 23,
"message": "insufficient_balance",
"data": []
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Tải lại / trạng thái đơn thẻ
- Method: `POST`
- Path: `/api/client/softcard/status`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"request_id": "REQ-BUY-001"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/softcard/status' -H 'Content-Type: application/json' -d '{...}'
```
Response — Completed raw:
```json
{
"order_code": "SC123",
"time": "2026-07-27 10:00:00",
"cards": [
{
"name": "Viettel 10k",
"serial": "S1",
"code": "C1"
}
]
}
```
Response — 28 — pending:
```json
{
"status": 28,
"message": "order_is_pending",
"data": []
}
```
**Bảng mã lỗi:**
- `1`: Mua thẻ thành công
- `2`: Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút
- `100`: Sản phẩm không tồn tại
- `101`: Ví điện tử không tồn tại
- `102`: Số dư ví không đủ
- `103`: Không có dữ liệu gửi lên
- `104`: Dữ liệu gửi lên không đúng
- `105`: Sản phẩm không đúng
- `106`: Loại thẻ đang ngừng cung cấp
- `107`: Lỗi mua hàng, bạn chưa bị trừ tiền
- `108`: Không tồn tại tài khoản merchant
- `109`: Mã yêu cầu request_id đã tồn tại
- `110`: Yêu cầu không hợp lệ
- `111`: Địa chỉ ví không tồn tại
- `112`: Địa chỉ ví không hoạt động
- `113`: Tài khoản bị khóa
- `114`: Merchant sai IP đăng ký
- `115`: Merchant không hoạt động
- `116`: Sai chữ ký
- `117`: Yêu cầu không đúng. Thiếu tham số command
- `118`: Sản phẩm này đã hết
- `119`: Địa chỉ IP không được quyền truy cập
- `120`: Lỗi Exception
- `121`: Thanh toán thất bại
- `122`: Không mua được hàng
- `123`: Giá sản phẩm không đúng
- `124`: Đơn hàng thất bại vì bị giới hạn
- `125`: Số lượng không hợp lệ
- `126`: Số lượng phải là số nguyên dương
- `127`: Tạo đơn hàng thất bại
- `128`: Mã yêu cầu đã tồn tại
- `129`: Đơn hàng không tồn tại
- `130`: Lỗi lấy thẻ
#### Kiểm tra tồn kho
- Method: `POST`
- Path: `/api/client/softcard/available`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"qty": 1,
"service_code": "VIETTEL",
"value": 10000
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/softcard/available' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": {
"stock_available": true,
"VT10": "Còn hàng"
}
}
```
#### Danh sách thẻ
- Method: `POST`
- Path: `/api/client/product`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"type": "softcard"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/product' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY","type":"softcard"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": [
{
"name": "Viettel",
"service_code": "VIETTEL",
"image": "https://example.com/a.png",
"items": [
{
"name": "10k",
"value": 10000,
"price": 9750,
"discount": 2.5,
"currency_code": "VND"
}
]
}
]
}
```
#### Nạp topup
- Method: `POST`
- Path: `/api/client/recharge/buy`
- Sign: `Không dùng sign`
- Callback: gửi kèm `callback` (URL) nếu muốn nhận kết quả async; không gửi thì poll `/api/client/recharge/status`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"amount": 50000,
"service_code": "VIETTEL_TOPUP",
"request_id": "REQ-TOP-001",
"account_info": {
"phone": "0901234567"
},
"callback": "https://your-domain.com/callback/recharge",
"qty": 1
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/recharge/buy' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": {
"time": "2026-07-27 10:00:00",
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"pay_amount": 49000,
"amount": 50000,
"status": "pending"
}
}
```
#### Callback nạp topup (Client) — POST JSON về URL bạn gửi
- Method: `POST` (hệ thống gọi URL `callback` của bạn)
- Path: URL bạn khai báo ở field `callback`
- Sign: Client API gửi trực tiếp URL `callback` — payload không kèm `callback_sign` (khác Partner API)
Payload hệ thống gửi:
```json
{
"time": "2026-07-27 10:05:00",
"account": {
"phone": "0901234567"
},
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"pay_amount": 49000,
"discount": 2,
"service_code": "VIETTEL_TOPUP",
"status": "completed",
"request_value": 50000,
"complete_value": 50000,
"remain_value": 0
}
```
#### Trạng thái topup
- Method: `POST`
- Path: `/api/client/recharge/status`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"request_id": "REQ-TOP-001",
"order_code": "RC123"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/recharge/status' -H 'Content-Type: application/json' -d '{...}'
```
Response — 1 — pending/completed:
```json
{
"status": 1,
"message": "success",
"data": {
"account": {
"phone": "0901234567"
},
"request_value": 50000,
"amount": 50000,
"request_id": "REQ-TOP-001",
"order_code": "RC123",
"status": "completed"
}
}
```
Response — 17 — Not found:
```json
{
"status": 17,
"message": "Order not found",
"data": []
}
```
#### Danh sách sản phẩm topup
- Method: `POST`
- Path: `/api/client/product`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"type": "recharge"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/product' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY","type":"recharge"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": [
{
"name": "Viettel Topup",
"service_code": "VIETTEL_TOPUP",
"type": "topup",
"items": [
{
"name": "10k",
"value": 10000,
"price": 9800,
"discount": 2
}
],
"options": []
}
]
}
```
#### Danh sách nhà mạng
- Method: `POST`
- Path: `/api/client/product`
- Sign: `Không dùng sign`
Request:
```json
{
"api_key": "YOUR_API_KEY",
"type": "charging"
}
```
cURL:
```bash
curl -X POST 'https://www.doithevip.com/api/client/product' -H 'Content-Type: application/json' -d '{"api_key":"YOUR_API_KEY","type":"charging"}'
```
Response — 1 — Success:
```json
{
"status": 1,
"message": "success",
"data": [
{
"name": "Viettel",
"key": "VIETTEL",
"value": [
10000,
20000,
50000
],
"icon": "https://example.com/vt.png"
}
]
}
```
## Mã trạng thái đổi thẻ (Charging)
| status | Ý nghĩa |
| --- | --- |
| 1 | Thẻ thành công đúng mệnh giá |
| 2 | Thẻ thành công sai mệnh giá |
| 3 | Thẻ lỗi |
| 4 | Hệ thống bảo trì |
| 99 | Thẻ chờ xử lý |
| 100 | Gửi thẻ thất bại - Có lý do đi kèm ở phần thông báo trả về |
## Bảng mã lỗi Mua thẻ (Cardws)
| status | Ý nghĩa |
| --- | --- |
| 1 | Mua thẻ thành công |
| 2 | Thanh toán thành công. Lấy thẻ thất bại, vui lòng redownload sau ít phút |
| 100 | Sản phẩm không tồn tại |
| 101 | Ví điện tử không tồn tại |
| 102 | Số dư ví không đủ |
| 103 | Không có dữ liệu gửi lên |
| 104 | Dữ liệu gửi lên không đúng |
| 105 | Sản phẩm không đúng |
| 106 | Loại thẻ đang ngừng cung cấp |
| 107 | Lỗi mua hàng, bạn chưa bị trừ tiền |
| 108 | Không tồn tại tài khoản merchant |
| 109 | Mã yêu cầu request_id đã tồn tại |
| 110 | Yêu cầu không hợp lệ |
| 111 | Địa chỉ ví không tồn tại |
| 112 | Địa chỉ ví không hoạt động |
| 113 | Tài khoản bị khóa |
| 114 | Merchant sai IP đăng ký |
| 115 | Merchant không hoạt động |
| 116 | Sai chữ ký |
| 117 | Yêu cầu không đúng. Thiếu tham số command |
| 118 | Sản phẩm này đã hết |
| 119 | Địa chỉ IP không được quyền truy cập |
| 120 | Lỗi Exception |
| 121 | Thanh toán thất bại |
| 122 | Không mua được hàng |
| 123 | Giá sản phẩm không đúng |
| 124 | Đơn hàng thất bại vì bị giới hạn |
| 125 | Số lượng không hợp lệ |
| 126 | Số lượng phải là số nguyên dương |
| 127 | Tạo đơn hàng thất bại |
| 128 | Mã yêu cầu đã tồn tại |
| 129 | Đơn hàng không tồn tại |
| 130 | Lỗi lấy thẻ |
## Client status codes (thường gặp)
| status | Ý nghĩa |
| --- | --- |
| 1 | Success |
| 3 | invalid_data |
| 4 | Invalid amount |
| 5 | Not support this bank |
| 6 | Wallet not found |
| 7 | Balance insufficient |
| 15 | user_not_found |
| 16 | ip_denied |
| 17 | Order not found |
| 18 | Withdraw bank not found |
## Gợi ý tích hợp
1. Partner: lấy `partner_id`/`partner_key`. Client: chỉ lấy `api_key` (không dùng `partner_id`).
2. Whitelist IP.
3. Ký đúng công thức Partner; Client không ký.
4. `request_id` idempotent theo user; Client có thể gửi `callback` (charging/recharge) hoặc poll status.