Hướng Dẫn Tích Hợp Thanh Toán Bằng Thẻ Cào API Đổi Thẻ Cào Cho Khách Thanh Toán Bằng Nạp Thẻ Cào Vào Website Với NapTaiKhoan.com

Ngày đăng: 2026-08-12 17:42:21 Đã xem: 1355552
Hướng Dẫn Tích Hợp API Đổi Thẻ Cào Vào Website | NapTaiKhoan.com
⚡ TÀI LIỆU API ĐỔI THẺ CÀO

Hướng Dẫn Tích Hợp Thanh Toán Bằng Thẻ Cào API Đổi Thẻ Cào Cho Khách Thanh Toán Bằng Nạp Thẻ Cào Vào Website Với NapTaiKhoan.com

Hướng dẫn lập trình viên tích hợp API đổi thẻ cào vào website: gửi thẻ, tạo chữ ký SIGN, kiểm tra trạng thái, nhận Callback, xử lý sai mệnh giá và chống cộng tiền trùng.

📘 Hướng dẫn từ A–Z 💳 Đổi thẻ cào tự động ⚙️ Ví dụ PHP CURL 🔐 SIGN & Callback
API này dùng để làm gì? Website của bạn nhận telco, code, serialamount từ khách, gửi sang NapTaiKhoan.com để xử lý thẻ. Khi có kết quả, NapTaiKhoan.com Callback về website để bạn tự động cộng số dư, xác nhận đơn hàng hoặc xử lý giao dịch theo trạng thái thực tế.

API đổi thẻ cào hoạt động như thế nào?

Thay vì quản trị viên kiểm tra từng thẻ thủ công, website có thể kết nối trực tiếp với NapTaiKhoan.com và tự động hóa toàn bộ luồng xử lý.

1Khách nhập thẻ
2Website gửi API
3Thẻ được xử lý
4Callback kết quả
5Hoàn tất giao dịch

Mỗi giao dịch nên có một request_id duy nhất. Hệ thống NapTaiKhoan.com có cơ chế idempotency: cùng request_id của cùng đại lý sẽ trả lại giao dịch cũ thay vì tạo và gửi thẻ lần hai.

1. Tạo API đổi thẻ cào

Sau khi tạo API module Charging / Đổi thẻ cào, bạn sẽ có partner_id, partner_key và Callback URL.

Partner ID — mã định danh API.
Partner Key — khóa bí mật tạo SIGN.
Callback URL — URL nhận kết quả thẻ.
Callback Method — POST hoặc GET.
🔐 Không để Partner Key ở frontend Partner Key chỉ nên được sử dụng phía server. Không nhúng khóa vào JavaScript, HTML công khai hoặc gửi xuống trình duyệt của khách hàng.

2. Endpoint API đổi thẻ

Endpoint API đổi thẻ cào dành cho đối tác:

POST https://naptaikhoan.com/chargingws/v2

Khuyến nghị gửi request bằng POST + JSON. Toàn bộ ví dụ trong tài liệu này sử dụng endpoint /chargingws/v2.

3. Gửi thẻ bằng command = charging

Tham sốBắt buộcMô tả
commandDùng giá trị charging.
partner_idPartner ID của API.
request_idMã giao dịch duy nhất phía website bạn.
telcoMã loại thẻ đang được hệ thống hỗ trợ.
codeMã PIN thẻ.
serialSerial thẻ.
amountMệnh giá khách khai báo.
signChữ ký xác thực request.

Công thức SIGN chuẩn

MD5(partner_key + partner_id + command + request_id)

Ví dụ JSON gửi thẻ

JSON
{
  "command": "charging",
  "partner_id": "YOUR_PARTNER_ID",
  "request_id": "ORDER_100001",
  "telco": "VIETTEL",
  "code": "123456789012345",
  "serial": "10000012345678",
  "amount": 100000,
  "sign": "YOUR_SIGN"
}

Ví dụ PHP CURL hoàn chỉnh

PHP
<?php

$partnerId  = 'YOUR_PARTNER_ID';
$partnerKey = 'YOUR_PARTNER_KEY';

$requestId = 'ORDER_' . time();
$command   = 'charging';

$data = [
    'command'    => $command,
    'partner_id' => $partnerId,
    'request_id' => $requestId,
    'telco'      => 'VIETTEL',
    'code'       => '123456789012345',
    'serial'     => '10000012345678',
    'amount'     => 100000
];

$data['sign'] = md5(
    $partnerKey .
    $partnerId .
    $command .
    $requestId
);

$ch = curl_init('https://naptaikhoan.com/chargingws/v2');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data, JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json'
    ],
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT        => 30
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);

$result = json_decode($response, true);

print_r($result);

4. Kết quả khi gửi thẻ

Ví dụ khi thẻ đã được tiếp nhận và đang xử lý:

JSON RESPONSE
{
  "trans_id": 15230,
  "request_id": "ORDER_100001",
  "amount": 0,
  "value": 0,
  "declared_value": 100000,
  "telco": "VIETTEL",
  "status": 99,
  "message": "Thẻ Đã Được Tiếp Nhận Và Đang Xử Lý"
}
TrườngÝ nghĩa
trans_idMã giao dịch trên NapTaiKhoan.com.
request_idMã giao dịch do website bạn gửi lên.
declared_valueMệnh giá khách khai báo.
valueMệnh giá thực tế sau khi xử lý.
amountSố tiền thực nhận của giao dịch.
telcoLoại thẻ.
statusMã trạng thái xử lý.
messageMô tả trạng thái.
⚠️ Không cộng tiền khi status = 99 99 chỉ có nghĩa thẻ đang xử lý. Hãy chờ Callback hoặc kiểm tra lại bằng command=check.

5. Bảng trạng thái API đổi thẻ

StatusÝ nghĩaCách xử lý đề xuất
1Thẻ đúngHoàn tất giao dịch theo amount thực nhận.
2Sai mệnh giáDùng valueamount thực tế để xử lý.
3Thẻ saiĐánh dấu giao dịch thất bại, không cộng tiền.
4Bảo trìKhông gửi dồn; thông báo hoặc thử lại sau.
5Chưa tiếp nhậnKiểm tra lại giao dịch trước khi quyết định gửi yêu cầu mới.
99Đang xử lýChờ Callback hoặc dùng command=check.
100Lỗi APIKiểm tra tham số, API key, chữ ký hoặc command.

6. Kiểm tra trạng thái bằng command = check

Khi cần đối soát một giao dịch đã gửi, sử dụng lại endpoint /chargingws/v2 với command=check.

JSON
{
  "command": "check",
  "partner_id": "YOUR_PARTNER_ID",
  "request_id": "ORDER_100001",
  "sign": "YOUR_SIGN"
}

Chữ ký vẫn dùng công thức:

MD5(partner_key + partner_id + command + request_id)

Ví dụ PHP kiểm tra trạng thái

PHP
<?php

$partnerId  = 'YOUR_PARTNER_ID';
$partnerKey = 'YOUR_PARTNER_KEY';
$requestId  = 'ORDER_100001';
$command    = 'check';

$data = [
    'command'    => $command,
    'partner_id' => $partnerId,
    'request_id' => $requestId,
    'sign'       => md5(
        $partnerKey .
        $partnerId .
        $command .
        $requestId
    )
];

$ch = curl_init('https://naptaikhoan.com/chargingws/v2');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_TIMEOUT        => 30
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

print_r($result);
✓ Không gửi lại thẻ chỉ vì chưa nhận Callback Nếu đơn đang 99, hãy dùng check. Điều này giảm nguy cơ xử lý trùng và giúp đối soát đúng theo request_id.

7. Callback — nhận kết quả thẻ tự động

Khi đơn API có kết quả, NapTaiKhoan.com gửi dữ liệu về Callback URL bạn đã cấu hình. Hệ thống hỗ trợ Callback kiểu POST hoặc GET; với POST có thể dùng JSON.

Dữ liệu Callback

JSON CALLBACK
{
  "status": 1,
  "message": "Nap The Thanh Cong",
  "request_id": "ORDER_100001",
  "declared_value": 100000,
  "value": 100000,
  "card_value": 100000,
  "amount": 85000,
  "code": "123456789012345",
  "serial": "10000012345678",
  "telco": "VIETTEL",
  "trans_id": 15230,
  "callback_sign": "YOUR_CALLBACK_SIGN"
}

Con số 85000 chỉ là ví dụ minh họa. Khi triển khai thật, luôn sử dụng amount mà Callback/API trả về cho chính giao dịch đó.

Công thức xác thực Callback

MD5(partner_key + code + serial)
⛔ Không tin Callback nếu chưa xác thực Trước khi cộng tiền, phải kiểm tra callback_sign, request_id và trạng thái hiện tại của đơn trong database.

Ví dụ PHP nhận Callback an toàn

PHP
<?php

$partnerKey = 'YOUR_PARTNER_KEY';

// Ví dụ này dùng Callback POST JSON.
$data = json_decode(file_get_contents('php://input'), true);

if (!is_array($data)) {
    http_response_code(400);
    exit('INVALID DATA');
}

$required = [
    'status',
    'request_id',
    'code',
    'serial',
    'callback_sign'
];

foreach ($required as $field) {
    if (!array_key_exists($field, $data)) {
        http_response_code(400);
        exit('MISSING FIELD');
    }
}

$expectedSign = md5(
    $partnerKey .
    (string)$data['code'] .
    (string)$data['serial']
);

if (!hash_equals(
    strtolower($expectedSign),
    strtolower((string)$data['callback_sign'])
)) {
    http_response_code(403);
    exit('INVALID SIGN');
}

$requestId = (string)$data['request_id'];
$status    = (int)$data['status'];
$amount    = (float)($data['amount'] ?? 0);
$value     = (float)($data['value'] ?? 0);

/*
 * BƯỚC BẮT BUỘC Ở WEBSITE CỦA BẠN:
 *
 * 1. Tìm đơn bằng $requestId.
 * 2. Kiểm tra đơn thuộc đúng khách / giao dịch.
 * 3. Nếu đơn đã hoàn tất thì KHÔNG cộng tiền lần hai.
 * 4. status = 1: xử lý thành công theo $amount.
 * 5. status = 2: xử lý sai mệnh giá theo $value và $amount.
 * 6. status = 3: đánh dấu thẻ sai.
 * 7. Chỉ commit số dư và trạng thái trong một transaction DB.
 */

echo 'SUCCESS';

8. Lấy bảng chiết khấu thẻ qua API

Nếu cần hiển thị mức phí/chiết khấu hiện tại cho khách, hệ thống có endpoint:

GET https://naptaikhoan.com/chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID

Kết quả trả danh sách các loại thẻ đang bật, mệnh giá và trường fees theo nhóm chiết khấu của tài khoản API.

Chiết khấu có thể thay đổi Không nên hard-code bảng phí cố định trong mã nguồn website. Nếu bạn hiển thị phí cho khách, nên đồng bộ định kỳ hoặc tải lại từ API.

9. Checklist tích hợp API đổi thẻ an toàn

Partner Key chỉ lưu ở server.
Mỗi giao dịch có request_id duy nhất.
Lưu đơn trước khi gọi API.
Không cộng tiền khi status=99.
Xác thực callback_sign.
Chống cộng tiền 2 lần.
Sai mệnh giá dùng giá trị thực tế.
Không ghi Partner Key vào log công khai.

Luồng xử lý khuyến nghị

Tạo request_id → Lưu đơn PENDING → Gửi API → Nhận status 99 → Chờ Callback → Xác thực SIGN → Khóa đơn → Cập nhật số dư → Hoàn tất

10. Các lỗi API thường gặp

“Dữ liệu không đủ, vui lòng đọc kỹ tài liệu api”

Kiểm tra command, partner_id, request_idsign.

“Dữ liệu thẻ không đủ”

Kiểm tra telco, code, serialamount.

“Api key không hợp lệ”

Partner ID không tồn tại hoặc API không thuộc module Charging.

“Api key chưa được bật”

API đã tạo nhưng chưa ở trạng thái hoạt động.

“Chữ ký không hợp lệ”

Với tích hợp mới, hãy tạo SIGN đúng thứ tự: partner_key + partner_id + command + request_id.

“CARD_NOT_EXISTED”

Không tìm thấy giao dịch thuộc request_id đó trong tài khoản API.

Câu hỏi thường gặp về API đổi thẻ cào

Có thể dùng API để khách đổi thẻ hoàn toàn tự động không?
Có. Website gửi thẻ lên API, lưu trạng thái chờ và nhận kết quả cuối qua Callback. Sau khi xác thực Callback, website có thể tự động cập nhật số dư hoặc đơn hàng.
Khi API trả status 99 có được cộng tiền không?
Không. Status 99 là thẻ đang xử lý. Hãy chờ Callback hoặc kiểm tra lại bằng command=check.
Nếu khách khai báo sai mệnh giá thì sao?
Khi trạng thái là 2, hãy căn cứ vào valueamount thực tế do hệ thống trả về, không chỉ dùng declared_value.
Callback có thể bị gửi lại nhiều lần không?
Website nhận Callback nên luôn thiết kế theo hướng idempotent: trước khi cộng tiền phải kiểm tra đơn đã hoàn tất hay chưa. Một request_id chỉ được ghi nhận tài chính một lần.
Có nên gửi lại thẻ khi Callback chậm không?
Không nên. Hãy dùng command=check để kiểm tra giao dịch hiện tại trước, tránh tạo luồng xử lý trùng.

Tích hợp API đổi thẻ cào với NapTaiKhoan.com

Một tích hợp tốt không chỉ gửi được thẻ mà còn phải xử lý đúng trạng thái, xác thực Callback, chống trùng giao dịch và sử dụng số tiền thực nhận của từng đơn.

Với endpoint /chargingws/v2, website có thể triển khai đầy đủ luồng gửi thẻ → kiểm tra → Callback → đối soát trên một API thống nhất.

Bắt đầu tích hợp API đổi thẻ cào

Đăng nhập NapTaiKhoan.com, tạo API module Đổi thẻ cào, cấu hình Callback và sử dụng tài liệu trên để kết nối website của bạn.

Truy cập NapTaiKhoan.com →
Hỗ Trợ
Zalo