Tài liệu API

1. Tổng quan tích hợp

2. Điều kiện trước khi gọi API

• Bạn cần có partner_id và partner_key từ Merchant trước khi gọi API.
• Kết nối phải đang hoạt động (không bị quản trị viên khoá) và ví đủ số dư cho đơn topup.
• IP gửi request phải nằm trong whitelist được phép.
• Với lệnh topup, request_id phải là duy nhất để tránh tạo trùng giao dịch.
• Nên gọi productlist trước để biết đúng service_code và cấu trúc account_info cần truyền.

3. Công thức tạo sign

md5(partner_key . partner_id . command . request_id)

md5(partner_key . partner_id . command)

md5(partner_key . partner_id . command)

4. Chi tiết từng lệnh

{
    "command": "topup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "service_code": "VINA-DATA",
    "amount": 100000,
    "account_info": {
        "phone": "0987654321"
    },
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "time": "2026-04-03 14:30:00",
        "request_id": "TOPUP_20260403_001",
        "account": {
            "phone": "0987654321"
        },
        "order_code": "RE240403001",
        "pay_amount": 95000,
        "discount": 5,
        "service_code": "VINA-DATA",
        "amount": 100000,
        "status": "pending"
    }
}

{
    "command": "getstatus",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "order_code": "RE240403001",
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "account": {
            "phone": "0987654321"
        },
        "request_value": 100000,
        "amount": 100000,
        "request_id": "TOPUP_20260403_001",
        "order_code": "RE240403001",
        "status": "completed"
    }
}

{
    "command": "getbalance",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "balance": 1200000,
        "currency": "VND"
    }
}

{
    "command": "productlist",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "status": "success",
    "message": "Thành công",
    "data": [
        {
            "name": "Nạp data VinaPhone",
            "service_code": "VINA-DATA",
            "items": [
                {
                    "name": "Gói 100.000đ",
                    "value": 100000,
                    "price": 95000,
                    "discount": 5
                }
            ],
            "options": [
                {
                    "key": "phone",
                    "name": "Số điện thoại",
                    "type": "text"
                }
            ]
        }
    ]
}

{
    "command": "canceltopup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "order_code": "RE240403001",
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "status": "cancel_not_supported",
    "message": "Đơn đã gửi sang nhà cung cấp nên không huỷ được. Đơn thất bại sẽ tự hoàn tiền về ví.",
    "data": {
        "request_id": "TOPUP_20260403_001",
        "order_code": "RE240403001",
        "status": "pending"
    }
}

{
    "command": "feetopup",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "status": "success",
    "message": "Thành công",
    "data": [
        {
            "key": "VINA-DATA",
            "value": 100000,
            "price": 95000,
            "discount": 5
        }
    ]
}

5. Ghi chú về phản hồi

• Recharge API trả về khung JSON gồm status, message và data.
• Trường status là chuỗi, riêng lỗi sai IP trả số 114.
• data.status của đơn: pending đang xử lý, completed thành công, failed thất bại (đã hoàn tiền về ví).
• Nên xử lý luồng nghiệp vụ theo status, không chỉ dựa vào message.

6. Trạng thái thường gặp

Lưu ý tích hợp

• Nên gọi productlist trước khi topup để xác định đúng service_code, mệnh giá và option đầu vào.
• Sau khi tạo đơn topup, status trong data thường là pending vì hệ thống còn gọi sang nhà cung cấp.
• Dịch vụ khách tự nhập số tiền có trường amount_rule (min, max, step) trong productlist; amount gửi lên phải nằm trong hạn mức đó.
• account_info chỉ nhận đúng các key trong options của productlist; thiếu key bắt buộc trả account_info_not_correct.

API liên quan

1. Tổng quan tích hợp

2. Điều kiện trước khi gọi API

• Merchant phải được cấp quyền dùng module Softcard và đang hoạt động.
• sign luôn bắt buộc và phải khớp công thức của từng lệnh.
• Nếu kết nối có khai IP whitelist thì request phải gửi từ đúng IP đó.
• Với buycard và redownload, request_id phải là mã riêng để tránh trùng đơn.
• wallet_number là số ví hiển thị ở trang Kết nối API (dạng VND000000012), phải đúng ví của kết nối.

3. Công thức tạo sign

md5(partner_key . partner_id . command . request_id)

md5(partner_key . partner_id . command)

4. Chi tiết từng lệnh

{
    "command": "buycard",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "CARD_20260403_001",
    "service_code": "VIETTEL",
    "value": 100000,
    "qty": 2,
    "wallet_number": "VND000000012",
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

{
    "status": 1,
    "message": "Mua thẻ thành công",
    "data": {
        "cards": [
            {
                "name": "Thẻ Viettel 100.000",
                "serial": "10006139342354",
                "code": "114384960423544",
                "expired": "2027-12-31"
            }
        ],
        "request_id": "CARD_20260403_001",
        "order_code": "SC240403001"
    }
}

{
    "command": "redownload",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "CARD_20260403_001",
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

{
    "status": 1,
    "message": "Mua thẻ thành công",
    "data": {
        "cards": [
            {
                "name": "Thẻ Viettel 100.000",
                "serial": "10006139342354",
                "code": "114384960423544",
                "expired": "2027-12-31"
            }
        ],
        "request_id": "CARD_20260403_001",
        "order_code": "SC240403001"
    }
}

{
    "command": "checkavailable",
    "partner_id": "YOUR_PARTNER_ID",
    "service_code": "VIETTEL",
    "value": 100000,
    "qty": 5,
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "stock_available": true,
    "VIETTEL-100000": "Còn hàng"
}

{
    "command": "getbalance",
    "partner_id": "YOUR_PARTNER_ID",
    "wallet_number": "VND000000012",
    "sign": "md5(partner_key . partner_id . command)"
}

{
    "balance": 2500000,
    "currency_code": "VND"
}

5. API danh sách sản phẩm

Dùng endpoint sau để lấy danh sách sản phẩm và mệnh giá hỗ trợ:

https://hoangvistore.com/api/cardws/products?partner_id=YOUR_PARTNER_ID

[
    {
        "name": "Viettel",
        "slug": "viettel",
        "service_code": "VIETTEL",
        "image": "/uploads/softcard/viettel.png",
        "cardvalue": [
            {
                "service_code": "VIETTEL",
                "value": 100000,
                "price": 97000,
                "id": 10
            }
        ]
    }
]

6. Ghi chú về phản hồi

• buycard và redownload trả về JSON theo khung status, message, data.
• checkavailable trả về JSON trực tiếp gồm stock_available và thông tin tồn kho.
• getbalance trả về JSON trực tiếp gồm balance và currency_code.
• API /api/cardws/products trả về mảng sản phẩm JSON trực tiếp.

7. Bảng mã trạng thái

Lưu ý tích hợp

• Nên gọi API products trước để lấy đúng service_code và mệnh giá hợp lệ.
• buycard sẽ trừ tiền ví Merchant rồi cố gắng lấy card ngay từ hệ thống hoặc nhà cung cấp.
• redownload chỉ nên dùng khi request_id cũ đã mua thành công.
• checkavailable thường được dùng để kiểm tra tồn kho trước khi cho phép đặt mua số lượng lớn.

API liên quan