Tài liệu API

API Collection

Base URL https://www.doithevip.com
Tải .md Tải Postman
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.
Hỗ Trợ
Zalo Telegram Fanpage DoiTheVip
Hỗ Trợ DoiTheVip.Com ×