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.
telco, code, serial và
amount 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ý.
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.
2. Endpoint API đổi thẻ
Endpoint API đổi thẻ cào dành cho đối tác:
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ộc | Mô tả |
|---|---|---|
command | Có | Dùng giá trị charging. |
partner_id | Có | Partner ID của API. |
request_id | Có | Mã giao dịch duy nhất phía website bạn. |
telco | Có | Mã loại thẻ đang được hệ thống hỗ trợ. |
code | Có | Mã PIN thẻ. |
serial | Có | Serial thẻ. |
amount | Có | Mệnh giá khách khai báo. |
sign | Có | Chữ ký xác thực request. |
Công thức SIGN chuẩn
Ví dụ JSON gửi thẻ
{
"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
$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ý:
{
"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_id | Mã giao dịch trên NapTaiKhoan.com. |
request_id | Mã giao dịch do website bạn gửi lên. |
declared_value | Mệnh giá khách khai báo. |
value | Mệnh giá thực tế sau khi xử lý. |
amount | Số tiền thực nhận của giao dịch. |
telco | Loại thẻ. |
status | Mã trạng thái xử lý. |
message | Mô tả trạng thái. |
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ĩa | Cách xử lý đề xuất |
|---|---|---|
| 1 | Thẻ đúng | Hoàn tất giao dịch theo amount thực nhận. |
| 2 | Sai mệnh giá | Dùng value và amount thực tế để xử lý. |
| 3 | Thẻ sai | Đánh dấu giao dịch thất bại, không cộng tiền. |
| 4 | Bảo trì | Không gửi dồn; thông báo hoặc thử lại sau. |
| 5 | Chưa tiếp nhận | Kiể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. |
| 100 | Lỗi API | Kiể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.
{
"command": "check",
"partner_id": "YOUR_PARTNER_ID",
"request_id": "ORDER_100001",
"sign": "YOUR_SIGN"
}
Chữ ký vẫn dùng công thức:
Ví dụ PHP kiểm tra trạng thái
<?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);
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
{
"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
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
$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:
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.
9. Checklist tích hợp API đổi thẻ an toàn
request_id duy nhất.status=99.callback_sign.Luồng xử lý khuyến nghị
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_id và sign.
“Dữ liệu thẻ không đủ”
Kiểm tra telco, code, serial và amount.
“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?
Khi API trả status 99 có được cộng tiền không?
command=check.
Nếu khách khai báo sai mệnh giá thì sao?
value và
amount 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?
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?
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 →