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 gửi kết quả về, không cần polling. Phương thức callback được cấu hình là GET hoặc POST trong phần Tích hợp API.

Với GET, dữ liệu kết quả được gửi dưới dạng query parameters. Với POST, dữ liệu được gửi trong request body.

{
  "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 mệnh giá thật (50K), sau đó phạt 50% → thực nhận 25K.
• Thẻ thật LỚN hơn mệnh giá khai (VD: khai 50K, thẻ thật 500K) → tính theo mệnh giá đã khai (50K), sau đó phạt 50% → thực nhận 25K.

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.