1. API Đổi thẻ cào

• 1.1. Lấy bảng giá thẻ
• 1.2. Nạp thẻ (charging)
• 1.3. Kiểm tra trạng thái thẻ (check)
• 1.4. Callback kết quả nạp thẻ

2. API Rút tiền

• 2.1. Lấy số dư
• 2.2. Lấy tỷ giá USDT & số tiền tối thiểu
• 2.3. Danh sách chain rút USDT
• 2.4. Tạo đơn rút VND
• 2.5. Tạo đơn rút USDT
• 2.6. Tra cứu trạng thái đơn rút

3. API Nạp tiền

• 3.1. Tạo đơn nạp tiền (chuyển khoản)

4. API Mua thẻ cào

• 4.1. Mua thẻ cào

GET https://thecaosieutoc.vn/chargingws/v2/getfee

Trả về danh sách loại thẻ, mệnh giá và chiết khấu (phí) tương ứng.

Query ví dụ:

partner_id=your_partner_id

Response ví dụ:

[
  { "telco": "VIETTEL", "value": 10000, "fees": 20.5, "penalty": 50 },
  { "telco": "VIETTEL", "value": 20000, "fees": 19, "penalty": 50 },
  { "telco": "MOBIFONE", "value": 10000, "fees": 21, "penalty": 50 }
]

POST https://thecaosieutoc.vn/chargingws/v2

Gửi thẻ cào lên hệ thống xử lý. Kết quả có thể trả ngay hoặc gửi qua callback URL (cấu hình tại Merchant).

Body ví dụ:

{
  "command": "charging",
  "partner_id": "your_partner_id",
  "sign": "abc123...",
  "telco": "VIETTEL",
  "code": "1000123456789",
  "serial": "123456789012",
  "amount": 10000,
  "request_id": "your_unique_request_id"
}

Response ví dụ (nhận thẻ, đang xử lý):

{
  "status": 99,
  "message": "PENDING",
  "request_id": "your_unique_request_id",
  "command": "charging"
}

Response ví dụ (lỗi):

{
  "status": 100,
  "message": "Thiếu tham số: partner_id, sign, telco, code, serial, amount"
}

sign = md5(partner_key + code + serial). request_id tùy chọn, dùng để đối chiếu khi nhận callback.

POST https://thecaosieutoc.vn/chargingws/v2

Tra cứu kết quả thẻ đã gửi (theo code + serial + telco). Body giống charging, đổi command thành check.

Body ví dụ:

{
  "command": "check",
  "partner_id": "your_partner_id",
  "sign": "abc123...",
  "telco": "VIETTEL",
  "code": "1000123456789",
  "serial": "123456789012",
  "amount": 10000,
  "request_id": "your_unique_request_id"
}

Response ví dụ (đã xử lý xong, đúng mệnh giá):

{
  "trans_id": 12345,
  "request_id": "your_unique_request_id",
  "status": 1,
  "message": "OK",
  "telco": "VIETTEL",
  "code": "1000123456789",
  "serial": "123456789012",
  "declared_value": 10000,
  "value": 10000,
  "amount": 7950
}

status: 1 = đúng mệnh giá, 2 = sai mệnh giá, 3 = thẻ lỗi, 99 = đang xử lý. amount = số tiền merchant nhận (sau trừ phí).

Hệ thống gọi tới URL callback của Merchant (cấu hình trong quản lý Merchant) khi có kết quả thẻ. Method: GET hoặc POST tùy cấu hình.

Body / Query ví dụ (POST):

{
  "command": "charging",
  "status": 1,
  "message": "OK",
  "request_id": "your_unique_request_id",
  "declared_value": 10000,
  "value": 10000,
  "amount": 7950,
  "code": "1000123456789",
  "serial": "123456789012",
  "telco": "VIETTEL",
  "trans_id": "12345",
  "callback_sign": "xyz789..."
}

Giải thích:

• status: 1 = đúng mệnh giá, 2 = sai mệnh giá, 3 = thẻ lỗi
• amount: Số tiền (VND) merchant nhận sau trừ phí
• callback_sign: md5(partner_key + code + serial) — dùng để xác thực request từ hệ thống

GET https://thecaosieutoc.vn/api/withdraw/balance

Trả về số dư ví VND của tài khoản.

Body / Query ví dụ:

token=your_withdraw_token

Response ví dụ (thành công):

{
  "status": 1,
  "balance": 1500000,
  "username": "user123"
}

Response ví dụ (lỗi):

{
  "status": 100,
  "message": "Token không hợp lệ"
}

GET https://thecaosieutoc.vn/api/withdraw/rate

Tỷ giá 1 USDT (VND) và số tiền VND tối thiểu khi rút USDT.

Body / Query ví dụ:

token=your_withdraw_token

Response ví dụ:

{
  "status": 1,
  "usdt_rate": 25500,
  "min_vnd": 100000
}

GET https://thecaosieutoc.vn/api/withdraw/chains

Các mạng (chain) đang hỗ trợ rút USDT.

Body / Query ví dụ:

token=your_withdraw_token

Response ví dụ:

{
  "status": 1,
  "chains": [
    { "code": "TRC20", "name": "TRON (TRC20)" },
    { "code": "ERC20", "name": "Ethereum (ERC20)" }
  ]
}

POST https://thecaosieutoc.vn/api/withdraw/vnd

Tạo yêu cầu rút tiền về tài khoản ngân hàng. Đơn chờ admin duyệt.

Body ví dụ:

{
  "token": "your_withdraw_token",
  "amount": 500000,
  "bank_code": "VCB",
  "account_num": "1234567890",
  "account_name": "NGUYEN VAN A",
  "callback_url": "https://your-site.com/callback"
}

Response ví dụ (thành công):

{
  "status": 1,
  "order_code": "WD123ABC",
  "amount": 500000,
  "message": "Tạo đơn thành công"
}

Response ví dụ (lỗi):

{
  "status": 101,
  "message": "Số dư không đủ"
}

Mã lỗi: 100 = token/sai tham số, 101 = số dư không đủ, 102 = số tiền < tối thiểu, 103 = thông tin ngân hàng không hợp lệ.

POST https://thecaosieutoc.vn/api/withdraw/usdt

Tạo yêu cầu rút USDT về địa chỉ ví. amount là số tiền VND; hệ thống quy đổi sang USDT theo tỷ giá.

Body ví dụ:

{
  "token": "your_withdraw_token",
  "amount": 2550000,
  "usdt_address": "TXYZabc123...",
  "usdt_network": "TRC20",
  "callback_url": "https://your-site.com/callback"
}

Response ví dụ (thành công):

{
  "status": 1,
  "order_code": "WD456XYZ",
  "amount": 2550000,
  "usdt_amount": 100,
  "message": "Tạo đơn thành công"
}

GET https://thecaosieutoc.vn/api/withdraw/status

Kiểm tra trạng thái đơn rút theo order_code.

Body / Query ví dụ:

token=your_withdraw_token&order_code=WD123ABC

Response ví dụ:

{
  "status": 0,
  "order_code": "WD123ABC",
  "type": "vnd",
  "amount": 500000,
  "usdt_amount": null,
  "usdt_network": null,
  "order_status": 0,
  "order_status_text": "Đang xử lý",
  "created_at": "09/02/2025 14:30"
}

Trạng thái đơn rút (order_status):

• 0 — Đang xử lý: Đơn chờ admin duyệt.
• 1 — Hoàn tất: Đơn đã được duyệt và chuyển tiền.
• 2 — Thất bại: Đơn bị từ chối (tiền đã hoàn lại ví nếu đã trừ).

POST https://thecaosieutoc.vn/api/deposit/order

Tạo đơn nạp tiền; trả về thông tin ngân hàng nhận, số tiền, nội dung chuyển khoản và URL mã QR. Khách chuyển khoản đúng số tiền và nội dung (transfer_content); hệ thống tự đối soát và cộng tiền (cron).

Body ví dụ (JSON):

{
  "token": "your_withdraw_token",
  "amount": 100000,
  "callback_url": "https://your-site.com/deposit-callback"
}

Tham số:

• token (bắt buộc): Token API (cùng token Rút tiền).
• amount (bắt buộc): Số tiền VND cần nạp (trong khoảng deposit_min – deposit_max).
• callback_url (tùy chọn): URL hệ thống sẽ POST tới khi đơn kết thúc (duyệt / từ chối / hủy).

Response thành công:

{
  "status": 1,
  "order_code": "ABC12XYZ3456",
  "amount": 100000,
  "expires_at": "2025-02-25T15:30:00+07:00",
  "expires_in": 1800,
  "bank_name": "Vietcombank",
  "account_number": "1234567890",
  "account_holder": "CONG TY ABC",
  "transfer_content": "ABC12XYZ3456",
  "qr_url": "https://img.vietqr.io/image/VCB-1234567890-qr_only.png?amount=100000&addInfo=..."
}

Response lỗi (vd token sai, quá 1 đơn/phút, chức năng đóng):

{
  "status": 0,
  "message": "Token không hợp lệ"
}

Callback khi đơn kết thúc:

Nếu truyền callback_url, hệ thống sẽ POST tới URL đó khi đơn chuyển sang trạng thái kết thúc. Method: POST, Content-Type: application/json. Gửi tối đa 3 lần; coi thành công khi client trả HTTP 200 hoặc body {"success": true}. Không có API GET tra trạng thái — client dựa vào callback.

Body callback (JSON) — ví dụ đơn đã duyệt (status = 1):

{
  "order_code": "ABC12XYZ3456",
  "amount": 100000,
  "status": 1,
  "token": "your_api_token",
  "approved_at": "2025-02-25T14:30:00+07:00"
}

Body callback — ví dụ đơn từ chối (status = 2) hoặc hủy (status = 3):

{
  "order_code": "ABC12XYZ3456",
  "amount": 100000,
  "status": 2,
  "token": "your_api_token"
}

Giải thích trường callback:

• order_code: Mã đơn nạp (string).
• amount: Số tiền VND (integer).
• status: Trạng thái đơn — 1 = Đã duyệt (đã cộng tiền), 2 = Từ chối (vd hết hạn), 3 = Đã hủy.
• token: API token của user (để client đối chiếu xác thực).
• approved_at: Chỉ có khi status = 1, thời điểm duyệt đơn (ISO 8601).

Ví dụ curl: curl -X POST https://thecaosieutoc.vn/api/deposit/order -H "Content-Type: application/json" -d '{"token":"YOUR_TOKEN","amount":100000}'

POST https://thecaosieutoc.vn/api/card/buy

Gửi request trong body (JSON) gồm token, type_card (mã loại thẻ, ví dụ VIETTEL), amount (mệnh giá thẻ, VND), quantity (số lượng). Response: status = 0 (lỗi) hoặc 1 (thành công), kèm message; khi status = 1 trả thêm cards là mảng các thẻ, mỗi thẻ có type, amount, code, serial.

Body ví dụ (JSON):

{
  "token": "your_api_token",
  "type_card": "VIETTEL",
  "amount": 10000,
  "quantity": 2
}

Tham số:

• token (bắt buộc): Token API (cùng token Rút tiền / Nạp tiền).
• type_card (bắt buộc): Mã loại thẻ (trường code trong hệ thống, ví dụ VIETTEL, MOBIFONE).
• amount (bắt buộc): Mệnh giá thẻ (VND, integer).
• quantity (bắt buộc): Số lượng thẻ (1–50).

Response thành công (status = 1):

{
  "status": 1,
  "message": "Mua thẻ thành công. Mã đơn: CXXXXXXXXXX",
  "order_code": "CXXXXXXXXXX",
  "cards": [
    { "type": "Viettel", "amount": 10000, "code": "1000123456789", "serial": "123456789012" },
    { "type": "Viettel", "amount": 10000, "code": "1000987654321", "serial": "987654321098" }
  ]
}

Response lỗi (status = 0):

{
  "status": 0,
  "message": "Token không hợp lệ"
}

Giải thích trường khi status = 1:

• order_code: Mã đơn mua thẻ.
• cards: Mảng các thẻ đã mua. Mỗi phần tử: type (tên loại thẻ), amount (mệnh giá VND), code (mã thẻ), serial (serial thẻ).