Tích hợp API apidoithe.com

1.Xác thực

Vào Tài khoản → Tích hợp API trên web để tự tạo Partner ID và Partner Key riêng cho từng loại API. Partner Key chỉ hiện đúng 1 lần lúc tạo — lưu lại cẩn thận.

Mỗi request gửi lên cần kèm chữ ký (sign) để xác thực, tính theo công thức:

sign = md5(partner_key + code + serial)

2.Gửi thẻ cào

curl -X POST https://apidoithe.com/api/partner/charging \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "83178270551",
    "telco": "VIETTEL",
    "denomination": 100000,
    "serial": "1234567890123",
    "code": "1111222233334444",
    "sign": "md5_cua_partner_key_code_serial"
  }'

Response (201):

{
  "status": 1,
  "message": "Đã nhận thẻ, đang xử lý.",
  "request_id": "TXAB12CD"
}

3.Tra cứu trạng thái

{
  "status": 1,
  "request_id": "TXAB12CD",
  "telco": "VIETTEL",
  "denomination": 100000,
  "net_amount": 87000,
  "transaction_status": "success"
}

4.Webhook — nhận kết quả tự động

Cấu hình sẵn Callback URL ngay trong mục Tích hợp API (hoặc gửi kèm callback_url mỗi request để ghi đè tạm thời) để hệ thống tự động POST kết quả về, không cần polling.

{
  "event": "card_exchange.updated",
  "transaction_id": "TXAB12CD",
  "status": "success",
  "net_amount": 87000
}

Yêu cầu với endpoint nhận webhook của bạn:

• Trả về HTTP 2xx để xác nhận đã nhận — nếu không, hệ thống tự thử lại tối đa 5 lần (5s → 15s → 60s → 5 phút → 15 phút).
• Xử lý idempotent — dùng transaction_id để chống xử lý trùng nếu có thử lại.
• Khuyến khích luôn gọi lại API tra cứu (mục 3) để xác nhận trước khi ghi nhận vào hệ thống của bạn.

5.Quy tắc xử lý sai mệnh giá

• Thẻ thật NHỎ hơn mệnh giá khai (VD: khai 500K, thẻ thật 50K) → tính theo giá trị thật (50K), phạt thêm % theo cấu hình hiện hành (mặc định 10%).
• Thẻ thật LỚN hơn mệnh giá khai (VD: khai 50K, thẻ thật 500K) → chỉ cộng đúng theo mệnh giá đã khai (50K), không phạt thêm.

6.Bảng phí hiện hành

Không cần đăng nhập, dữ liệu thật cập nhật theo thời gian thực.

{
  "insurance_enabled": true,
  "rates": {
    "VIETTEL": [
      { "denomination": 10000, "fee_no_insurance": 15, "fee_with_insurance": 15.5 }
    ]
  }
}

7.Mã lỗi thường gặp

8.Ví dụ tích hợp đầy đủ (PHP)

<?php
$partnerId = '83178270551';
$partnerKey = 'partner_key_cua_ban';
$code = '1111222233334444'; // mã PIN thẻ
$serial = '1234567890123';
$sign = md5($partnerKey . $code . $serial);

$ch = curl_init('https://apidoithe.com/api/partner/charging');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'partner_id' => $partnerId,
        'telco' => 'VIETTEL',
        'denomination' => 100000,
        'serial' => $serial,
        'code' => $code,
        'sign' => $sign,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
echo $response['request_id']; // TXAB12CD

9.Lưu ý

• Không giới hạn cứng số request/phút, nhưng có cơ chế chống spam — gặp 429 thì giãn tần suất lại.
• Không lưu trữ lại mã PIN thẻ sau khi xử lý xong.
• Mọi giao dịch có thể xem lại song song trên web tại https://apidoithe.com/#doi-the.
• Cần hỗ trợ tích hợp, liên hệ qua mục "🎧 Hỗ trợ" trong tài khoản hoặc thông tin ở chân trang web.