Cách Tích Hợp Kết Nối API Đổi Thẻ, Mua Thẻ, Nạp Game, v.v - NapThe1s.Com

1.API NapThe1s gồm những gì

Cả 3 API dùng chung cách xác thực: partner_id + chữ ký sign (md5 có ghép partner_key). Phương thức khuyến nghị là POST.

2.Đăng ký lấy partner_id, partner_key

1. Đăng ký / đăng nhập tài khoản tại NapThe1s.Com.
2. Vào Thêm API (hoặc link Kết nối API ở chân trang) và bấm Thêm mới.
3. Chọn Loại API: Đổi thẻ cào, Mua thẻ cào hoặc Nạp tiền topup.
4. Chọn quỹ / ví giao dịch dùng để nhận tiền hoặc thanh toán.
5. Chọn kiểu callback GET hoặc POST và nhập Callback Url trên web của bạn.
6. Nhập địa chỉ IP máy chủ của bạn (không bắt buộc, nhưng nên khai báo để an toàn hơn).
7. Bấm Thêm thông tin kết nối để nhận partner_id và partner_key.

Đăng ký kết nối API Xem tài liệu API đầy đủ

3.API đổi thẻ cào (Charging v2)

Công thức chữ ký sign

• charging: md5(partner_key . code . command . partner_id . request_id . serial . telco)
• check: md5(partner_key . command . partner_id . request_id)

Trạng thái thẻ trả về

Nên gọi getfee trước khi dựng form nạp thẻ để lấy đúng biểu phí và mệnh giá được hỗ trợ.

4.Code mẫu PHP gửi thẻ

<?php
$endpoint   = 'https://napthe1s.com/chargingws/v2';
$partnerId  = 'YOUR_PARTNER_ID';
$partnerKey = 'YOUR_PARTNER_KEY';

$payload = [
    'command'    => 'charging',
    'partner_id' => $partnerId,
    'request_id' => 'NAPTHE_' . time(),      // không được trùng
    'telco'      => 'VIETTEL',
    'amount'     => '100000',
    'serial'     => '10006139342354',
    'code'       => '114384960423544',
];
$payload['sign'] = md5($partnerKey . $payload['code'] . $payload['command']
    . $payload['partner_id'] . $payload['request_id'] . $payload['serial'] . $payload['telco']);

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

// status 99 = đang xử lý, 1 = thẻ đúng, 2 = sai mệnh giá, 3 = thẻ lỗi
print_r($result);

Code mẫu cho C#, Java, Node.js, Python có sẵn trong Tài liệu API.

5.API nạp topup, nạp game

1. Gọi productlist để lấy danh sách dịch vụ (nạp điện thoại, data, nạp game…), service_code và thông tin cần nhập.
2. Gọi topup với service_code, amount và account_info (ví dụ {"phone":"0987654321"} hoặc ID game tùy sản phẩm).
3. Lưu order_code trả về, dùng getstatus để tra cứu đến khi đơn completed.

6.API mua mã thẻ

Lệnh buycard cần service_code (ví dụ VIETTEL), value, qty và wallet_number (ví thanh toán của bạn). Mã thẻ trả về ngay trong data.cards; nếu mất kết quả, dùng redownload với cùng request_id để tải lại.

7.Callback và bảo mật

Với đổi thẻ, kết quả cuối cùng được gửi về Callback Url bạn đã khai báo. Luôn kiểm tra chữ ký trước khi cộng tiền cho khách:

<?php
// Kiểm tra chữ ký callback trước khi cộng tiền cho khách
$data = $_POST ?: $_GET;
$expected = md5($partnerKey . $data['code'] . $data['serial']);
if (!hash_equals($expected, $data['callback_sign'] ?? '')) {
    http_response_code(403);
    exit('invalid sign');
}
// Tìm đơn theo $data['request_id'], cập nhật theo $data['status'] và $data['amount']

• request_id phải là duy nhất cho mỗi giao dịch, lưu lại để đối soát và gọi check.
• Khai báo IP máy chủ khi đăng ký API; request từ IP lạ sẽ bị từ chối (lỗi 102).
• Chỉ gọi API từ máy chủ, không gọi trực tiếp từ trình duyệt để tránh lộ partner_key.
• Không nhận thẻ không rõ nguồn gốc; tài khoản gửi thẻ gian lận qua API sẽ bị khóa vĩnh viễn theo Điều khoản.

8.Câu hỏi thường gặp