🎯 Tài liệu tích hợp API đổi thẻ cào

Hướng dẫn đầy đủ để tích hợp API vào website, bot, app mobile hoặc server backend

🚀 1. Bắt đầu nhanh

1.1. Đăng ký & lấy thông tin API

Đăng ký tài khoản tại https://app.opencard.vn
Vào mục Kết nối API → Tạo mới
Nhận:
- Partner ID
- Partner Key

⚠️ Lưu 2 thông tin này để sử dụng cho việc ký request và xác minh webhook.

⚙️ 2. Gửi yêu cầu đổi thẻ

Bạn gửi thẻ bằng cách gọi đến:

http

POST https://api.opencard.vn/chargingws/v0

2.1. Tham số gửi lên

Tên	Bắt buộc	Mô tả
`partner_id`	✔	ID API của bạn
`telco`	✔	Nhà mạng (VIETTEL, MOBIFONE...)
`amount`	✔	Mệnh giá khai báo
`serial`	✔	Số serial thẻ
`code`	✔	Mã thẻ
`command`	✔	Luôn là 'charging'
`sign`	✔	Chữ ký bảo mật

2.2. Tạo chữ ký sign

Chữ ký được tạo theo công thức:

text

sign = md5(PARTNER_KEY + code + partner_id + serial + telco + command)

Code PHP đầy đủ:

php

$data = [
    'partner_id' => 'YOUR_PARTNER_ID',
    'telco' => 'VIETTEL',
    'amount' => 10000,
    'serial' => '12345678901234',
    'code' => '123456789012345',
    'command' => 'charging'
];

// Tạo chữ ký
$signData = [
    'code' => $data['code'],
    'partner_id' => $data['partner_id'],
    'serial' => $data['serial'],
    'telco' => $data['telco'],
    'command' => $data['command']
];

ksort($signData);
$signString = 'YOUR_PARTNER_KEY';
foreach ($signData as $v) $signString .= $v;

$data['sign'] = md5($signString);

// Gửi request
$ch = curl_init('https://api.opencard.vn/chargingws/v0');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

📌 3. Phản hồi trả về khi gửi thẻ

Ví dụ gửi thẻ thành công:

json

{
    "status": 99,
    "message": "Gửi thẻ thành công, chờ xử lý",
    "request_id": "385672323"
}

Trường	Ý nghĩa
`status = 99`	Hệ thống đã nhận thẻ và đang xử lý
`request_id`	Mã giao dịch duy nhất – dùng để đối chiếu webhook
`message`	Nội dung mô tả

🔔 4. Hệ thống gửi webhook trả kết quả

Sau khi thẻ được xử lý (từ vài giây → vài phút), hệ thống sẽ tự động gửi webhook về URL mà bạn cấu hình.

4.1. Ví dụ dữ liệu webhook

json

{
  "request_id": "385672323",
  "trans_id": "10895648",
  "telco": "VIETTEL",
  "declared_value": 10000,
  "status": 3,
  "message": "CARD_INVALID",
  "amount": 0,
  "actual_amount": 8600,
  "notified_at": "2025-11-16 06:02:35",
  "sign": "23461a3ef41db1c06d60090508c18d5e"
}

4.2. Xác minh chữ ký webhook

Chữ ký được tạo theo:

text

sign = md5(PARTNER_KEY + request_id + status + amount + trans_id)

4.3. Code PHP xử lý webhook

php

// Nhận dữ liệu JSON
$data = json_decode(file_get_contents('php://input'), true);

// Tạo lại chữ ký
$signBase = [
    'request_id' => $data['request_id'],
    'status' => (string)$data['status'],
    'amount' => (string)$data['amount'],
    'trans_id' => (string)$data['trans_id']
];

ksort($signBase);
$raw = 'YOUR_PARTNER_KEY';
foreach ($signBase as $v) $raw .= (string)$v;

$expectedSign = md5($raw);

// Kiểm tra chữ ký
if ($expectedSign === $data['sign']) {
    // ===== XỬ LÝ KẾT QUẢ NẠP =====
    // $data['status']:
    //   1 = Thành công
    //   2 = Sai mệnh giá (nhận 50%)
    //   3 = Thẻ lỗi / Sai mã
    //   4 = Bảo trì
    
    // $data['actual_amount'] = số tiền thực nhận
    
    // TODO: cập nhật đơn hàng trong database
    
    http_response_code(200);
    echo json_encode(['success' => true]);
}

🧾 5. Quy định loại thẻ hỗ trợ

Nhà mạng	Mã thẻ	Serial
VIETTEL	15 số	14 số
MOBIFONE	12 số	15 số
VINAPHONE	14 số	14 số
ZING	9 ký tự	12 ký tự
VCOIN	12 ký tự	12 ký tự
GARENA	12 ký tự	12 ký tự

🟦 6. Trạng thái giao dịch

Mã	Ý nghĩa
`99`	Đang xử lý
`1`	Thành công
`2`	Sai mệnh giá (trừ 50%)
`3`	Thẻ sai / thẻ lỗi
`4`	Hệ thống bảo trì

📌 7. Quy trình hoạt động hoàn chỉnh

Bạn gửi request → hệ thống trả status = 99
Hệ thống xử lý:
- Nếu đúng → gửi webhook status = 1
- Nếu sai mệnh giá → status = 2
- Nếu sai mã / thẻ lỗi → status = 3
Bạn nhận webhook → xác minh chữ ký → cập nhật đơn hàng
Giao dịch hoàn tất

Sẵn sàng tích hợp?

Đăng ký tài khoản ngay để nhận API key và bắt đầu tích hợp

Đăng ký ngay