Tài liệu API eOTP

Bắt đầu nhanh

1. Tạo tài khoản và dự án

   Đăng ký tại trang đăng ký (xác minh số điện thoại bằng một mã OTP), rồi nộp dự án: chọn loại (Android, iOS hoặc website), điền tên, đường dẫn cửa hàng hoặc tên miền và mô tả ngắn cách bạn dùng OTP. Hệ thống tự rà soát, thường trong vòng 2 phút; dự án đạt ở trạng thái approved, gói FREE (100 OTP/tháng miễn phí).

2. Xác minh để lên DEVELOPER

   Website dùng Popup xác thực (cách mặc định) hoặc nút hiện sẵn (tuỳ chọn); app gọi SDK kiểm giấy phép (xem Kích hoạt DEVELOPER). Đủ bằng chứng, dự án tự lên DEVELOPER (100,000 OTP/tháng). Bước này không bắt buộc để thử API.

3. Lấy API key và Secret key

   Trong trang dự án, mở tab Tích hợp. API key (eo_live_…) luôn hiện; Secret key (eo_sec_…) chỉ hiện một lần khi tạo. Lưu cả 2 vào biến môi trường trên máy chủ: EASYOTP_API_KEY, EASYOTP_API_SECRET.

Thử ngay từ dòng lệnh: gửi mã, rồi kiểm mã bạn nhận được trên điện thoại.

# Gửi mã tới số Việt Nam
curl -X POST https://eotp.com.vn/api/v1/otp/send \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0912345678","country_code":"84"}'
# → {"ok":true,"request_id":"3f9a1c0e8b7d4a26b5e0c9d18f2a7b64", ...}

# Kiểm mã người dùng nhập
curl -X POST https://eotp.com.vn/api/v1/otp/verify \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"3f9a1c0e8b7d4a26b5e0c9d18f2a7b64","code":"123456"}'
# → {"ok":true,"verified":true}

Xác thực

Mỗi yêu cầu tới otp/send, otp/status, otp/verify và project gửi kèm 2 khoá của dự án:

• API key, dạng eo_live_ + 16 ký tự: định danh dự án, luôn xem lại được ở tab Tích hợp. Gửi trong header X-Api-Key.
• Secret key, dạng eo_sec_ + 32 ký tự: chỉ hiện một lần khi tạo, eOTP chỉ lưu bản băm. Gửi trong header X-Api-Secret.

X-Api-Key: eo_live_xxxxxxxxxxxxxxxx
X-Api-Secret: eo_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Hoặc gộp vào một header: Authorization: Bearer <api_key>:<secret>.

Lộ Secret key? Vào tab Tích hợp và tạo secret mới. Secret cũ mất hiệu lực ngay lập tức. API key cũng tạo lại được ở cùng chỗ (nút Tạo API key mới): khoá cũ bị từ chối ngay, và vì đường dẫn /embed/<api_key> đi theo khoá nên bạn cập nhật header X-Api-Key, mã iframe nếu dùng nút hiện sẵn và SDK kiểm giấy phép trong app; Popup xác thực không cần sửa trang. Secret key giữ nguyên.

Quy ước chung

• URL gốc: https://eotp.com.vn/api/v1. Chỉ nhận HTTPS.
• Body gửi lên là JSON (Content-Type: application/json), UTF-8. Phản hồi luôn là JSON.
• Mọi phản hồi có trường ok. Thành công: "ok": true, HTTP 200. Lỗi: "ok": false, mã lỗi máy đọc trong error và lời nhắn trong message, kèm trường phụ tuỳ lỗi.
• Xử lý theo error, không dựa vào message vì lời nhắn có thể thay đổi.
• Số tiền là số nguyên ở đơn vị nhỏ nhất của ví: VND tính bằng đồng, USD tính bằng cent. Trường currency cho biết loại tiền.
• Mốc thời gian là Unix (giây, UTC). Tháng và ngày của hạn mức tính theo giờ UTC.
• Header X-Request-Id: nếu bạn gửi (tối đa 64 ký tự chữ, số, . _ : -), hệ thống trả lại đúng giá trị đó; nếu không, hệ thống tự tạo. Ghi giá trị này vào log để đối chiếu khi cần hỗ trợ.

{
  "ok": false,
  "error": "invalid_phone",
  "message": "Số điện thoại chưa đúng.",
  "reason": "too_short"
}

Gửi mã OTP

Tạo một mã OTP mới và gửi tới số điện thoại. Hệ thống tự sinh mã; bạn không cần và không bao giờ thấy mã.

Tham số (body JSON)

curl -X POST https://eotp.com.vn/api/v1/otp/send \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+84912345678","channel":"zalo_then_sms","callback_url":"https://api.shop.vn/eotp/callback"}'

Phản hồi thành công (200)

Có 2 dạng, tuỳ chế độ vận hành của hệ thống. Code của bạn nên xử lý được cả hai: chỉ cần ok và request_id là đủ để đi tiếp tới verify.

• Hàng đợi ("status": "queued"): eOTP nhận yêu cầu, giữ tiền và trả lời ngay; bộ gửi nền chuyển tin trong khoảng eta_ms mili giây. Mã đã được tạo nên người dùng có thể nhập và bạn gọi verify bình thường. Muốn biết tin đã tới đâu, gọi otp/status.
• Đồng bộ (không có status): eOTP gửi xong mới trả lời, kèm sent_channels.

{
  "ok": true,
  "request_id": "3f9a1c0e8b7d4a26b5e0c9d18f2a7b64",
  "status": "queued",
  "eta_ms": 400,
  "expires_in": 300,
  "cost": 0,
  "currency": "VND",
  "code_type": "digits",
  "phone_e164": "+84912345678"
}

{
  "ok": true,
  "request_id": "3f9a1c0e8b7d4a26b5e0c9d18f2a7b64",
  "channel": "zalo_then_sms",
  "sent_channels": ["zalo"],
  "expires_in": 300,
  "cost_vnd": 0,
  "currency": "VND",
  "cost": 0,
  "phone_e164": "+84912345678"
}

Lỗi riêng của endpoint này

Trạng thái gửi

Tra trạng thái gửi của một yêu cầu do chính dự án của khoá tạo. Dùng khi send trả "status": "queued" và bạn muốn báo người dùng "mã đã gửi" hoặc gợi ý đổi kênh khi gửi lỗi. Không cần đợi sent mới gọi verify.

curl "https://eotp.com.vn/api/v1/otp/status?request_id=3f9a1c0e8b7d4a26b5e0c9d18f2a7b64" \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET"

{
  "ok": true,
  "request_id": "3f9a1c0e8b7d4a26b5e0c9d18f2a7b64",
  "status": "sent",
  "channel": "sms",
  "sent_at": 1794268800,
  "error": null,
  "attempts": 1
}

attempts là số lần bộ gửi đã thử. request_id sai dạng, không tồn tại hoặc của dự án khác trả 404 not_found. Nên tra cách nhau ít nhất 1 giây, dừng khi gặp sent, failed hoặc expired.

Kiểm mã OTP

Kiểm mã người dùng nhập với request_id nhận từ send. Mỗi mã chỉ dùng được một lần. Chỉ kiểm được yêu cầu do chính dự án của khoá tạo; request_id của dự án khác trả not_found.

Tham số (body JSON)

curl -X POST https://eotp.com.vn/api/v1/otp/verify \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"3f9a1c0e8b7d4a26b5e0c9d18f2a7b64","code":"123456"}'

{
  "ok": true,
  "verified": true
}

Lỗi riêng của endpoint này

{
  "ok": false,
  "error": "wrong_code",
  "message": "Mã chưa đúng. Bạn còn 4 lần thử.",
  "attempts_left": 4
}

Callback về máy chủ của bạn

Truyền callback_url khi gọi otp/send để eOTP tự báo kết quả gửi, thay vì tra otp/status nhiều lần. Khi yêu cầu chốt sent hoặc failed, eOTP gửi một lời gọi POST tới URL đó. Không truyền callback_url thì không có callback; tra otp/status vẫn dùng được như cũ.

Hoàn tiền, huỷ SMS dự phòng khi Zalo tới máy và báo cáo nhà mạng vẫn do eOTP tự xử lý; callback chỉ để bạn biết kết quả.

Yêu cầu eOTP gửi tới bạn

POST /eotp/callback HTTP/1.1
Host: api.shop.vn
Content-Type: application/json
User-Agent: eOTP-Callback/1.0 (+https://eotp.com.vn)
X-Eotp-Request-Id: 3f9a1c0e8b7d4a26b5e0c9d18f2a7b64
X-Eotp-Timestamp: 1794268800
X-Eotp-Signature: sha256=097235b3686b78ffc336fcb92452539ce8b3f434c063044289e416fbff8c0cc7

{"request_id":"3f9a1c0e8b7d4a26b5e0c9d18f2a7b64","status":"sent","channel":"sms","sent_at":1794268800,"error":null,"phone_e164":"+84912345678"}

Xác minh chữ ký

Lấy Callback secret ở trang dự án ▸ tab Tích hợp. Ghép giá trị header X-Eotp-Timestamp, một dấu chấm và thân thô đúng từng byte (đọc trước khi parse JSON) thành timestamp + "." + body, tính HMAC-SHA256 bằng Callback secret, rồi so sha256= + kết quả với header X-Eotp-Signature bằng hàm so sánh hằng thời gian. Không khớp thì trả 401 và bỏ qua.

Chống phát lại: từ chối lời gọi khi X-Eotp-Timestamp thiếu, không phải số, hoặc lệch giờ máy chủ của bạn quá 300 giây (|now − timestamp| > 300). Đồng bộ giờ máy chủ bằng NTP để không từ chối nhầm.

const crypto = require('crypto');
app.post('/eotp/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Eotp-Timestamp') || '';
  if (!/^\d+$/.test(ts) || Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) return res.sendStatus(401);
  const sig = 'sha256=' + crypto.createHmac('sha256', process.env.EOTP_CALLBACK_SECRET).update(ts + '.').update(req.body).digest('hex');
  const got = Buffer.from(req.get('X-Eotp-Signature') || '');
  if (got.length !== sig.length || !crypto.timingSafeEqual(got, Buffer.from(sig))) return res.sendStatus(401);
  const data = JSON.parse(req.body); /* data.request_id, data.status */ res.sendStatus(200);
});

$raw = file_get_contents('php://input'); // thân thô, trước khi parse
$ts  = $_SERVER['HTTP_X_EOTP_TIMESTAMP'] ?? '';
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; }
$sig = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, getenv('EOTP_CALLBACK_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_EOTP_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$data = json_decode($raw, true); // $data['request_id'], $data['status']
http_response_code(200);

import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)

@app.post('/eotp/callback')
def eotp_callback():
    raw = request.get_data()  # thân thô, trước khi parse
    ts = request.headers.get('X-Eotp-Timestamp', '')
    if not (ts.isascii() and ts.isdigit()) or abs(time.time() - int(ts)) > 300: abort(401)
    sig = 'sha256=' + hmac.new(os.environ['EOTP_CALLBACK_SECRET'].encode(), ts.encode() + b'.' + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, request.headers.get('X-Eotp-Signature', '')): abort(401)
    data = request.get_json()  # data['request_id'], data['status']
    return '', 200

Phản hồi và gửi lại

Trả bất kỳ mã 2xx trong 5 giây là eOTP coi như bạn đã nhận. Mã khác, quá 5 giây hoặc không kết nối được thì eOTP gửi lại theo lịch dưới. eOTP không theo chuyển hướng (3xx tính là lỗi).

Popup xác thực

Cách tích hợp mặc định cho dự án website. Trang của bạn không hiện gì sẵn: người dùng nhập số điện thoại vào form của bạn như bình thường, sau đó bạn gọi popup eOTP. Popup hiện đè lên trang, người dùng nhập mã ngay trong popup; gửi lại mã, đếm ngược, báo mã sai và hết hạn do eOTP lo. Máy chủ của bạn chỉ cần gọi 2 endpoint.

1. Máy chủ tạo phiên

   Khi người dùng gửi số, máy chủ của bạn gọi POST /popup/session bằng API key + Secret key. eOTP gửi mã tới số đó và trả về session.

2. Trang web mở popup

   Trang nạp https://eotp.com.vn/sdk/eotp-1.js rồi gọi eOTP.open({ session, … }). Người dùng nhập đúng mã thì onVerified nhận result.

3. Máy chủ xác nhận kết quả

   Trang gửi result lên máy chủ của bạn; máy chủ gọi POST /popup/result để biết chắc số điện thoại đã xác minh rồi mới đăng nhập hoặc ghi nhận đơn.

Muốn đặt nút "Xác thực eOTP" hiện sẵn trên trang, người dùng bấm nút là mở đúng popup này, xem Bấm nút mở popup. Chọn cách tích hợp ở trang dự án ▸ tab API key & tích hợp; popup chỉ dùng cho dự án loại website.

Bước 1. Tạo phiên popup

Gọi từ máy chủ, kèm header X-Api-Key và X-Api-Secret như otp/send. Mỗi lời gọi gửi một mã mới tới số điện thoại và tính như một lần gửi (hạn mức, ví).

{
  "ok": true,
  "session": "eops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "popup_url": "https://eotp.com.vn/popup/eops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "request_id": "3f9a1c0e8b7d4a26b5e0c9d18f2a7b64",
  "expires_in": 300,
  "phone_masked": "0912 *** 678",
  "channel": "zalo_then_sms",
  "max_resend": 3
}

Lỗi giống otp/send (invalid_phone, quota_exceeded, insufficient_balance…) và các lỗi xác thực. Lỗi có retry_in thì thử lại sau đúng khoảng đó. Thêm một lỗi riêng:

curl -X POST https://eotp.com.vn/api/v1/popup/session \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0912345678","country_code":"84","lang":"vi"}'

const EOTP = 'https://eotp.com.vn/api/v1';
const eotp = (path, body) => fetch(EOTP + path, {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.EASYOTP_API_KEY, 'X-Api-Secret': process.env.EASYOTP_API_SECRET, 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
}).then((r) => r.json());

// Bước 1: trang gửi số lên, máy chủ trả session cho trang
app.post('/otp/start', express.json(), async (req, res) => {
  const r = await eotp('/popup/session', { phone: req.body.phone, lang: 'vi' });
  if (!r.ok) return res.status(400).json({ error: r.error });
  res.json({ session: r.session });
});

// Bước 3: trang gửi result lên, máy chủ hỏi lại eOTP
app.post('/otp/done', express.json(), async (req, res) => {
  const r = await eotp('/popup/result', { result: req.body.result });
  if (!r.ok || !r.verified) return res.status(401).json({ error: 'not_verified' });
  req.session.phone = r.phone_e164; // số đã xác minh
  res.json({ ok: true });
});

function eotp(string $path, array $body): array {
    $ch = curl_init('https://eotp.com.vn/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('EASYOTP_API_KEY'), 'X-Api-Secret: ' . getenv('EASYOTP_API_SECRET'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $out = json_decode((string) curl_exec($ch), true);
    return is_array($out) ? $out : ['ok' => false];
}

// Bước 1
$r = eotp('/popup/session', ['phone' => $_POST['phone'], 'lang' => 'vi']);
echo json_encode($r['ok'] ? ['session' => $r['session']] : ['error' => $r['error'] ?? 'error']);

// Bước 3
$r = eotp('/popup/result', ['result' => $_POST['result']]);
if (!empty($r['ok']) && !empty($r['verified'])) { $_SESSION['phone'] = $r['phone_e164']; }

Bước 2. Mở popup trên trang

Nạp SDK một lần trên trang có form nhập số, rồi gọi eOTP.open khi máy chủ trả về session. SDK không cần thư viện ngoài và không chứa khoá nào.

<script src="https://eotp.com.vn/sdk/eotp-1.js"></script>
<script>
async function verifyPhone(phone) {
  const { session } = await fetch('/otp/start', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ phone }) }).then((r) => r.json());
  eOTP.open({
    session,
    lang: 'vi',
    onVerified: async ({ result }) => {
      await fetch('/otp/done', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ result }) });
    },
    onClose: (reason) => { if (reason === 'change_phone') document.querySelector('#phone').focus(); },
    onError: (error) => console.warn('eOTP', error),
  });
}
</script>

eOTP.close() đóng popup đang mở. Gọi eOTP.open khi popup đang mở thì lời gọi sau bị bỏ qua. Khi popup đóng, trang của bạn cuộn được trở lại và con trỏ quay về phần tử đang chọn trước đó.

Bước 3. Xác nhận kết quả ở máy chủ

Gửi result nhận từ onVerified, kèm API key + Secret key. result chỉ dùng được với đúng dự án đã tạo phiên và còn hiệu lực trong thời gian ngắn; gọi lại trong thời gian đó vẫn trả cùng kết quả.

curl -X POST https://eotp.com.vn/api/v1/popup/result \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"result":"eopr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

{
  "ok": true,
  "verified": true,
  "phone_e164": "+84912345678",
  "request_id": "3f9a1c0e8b7d4a26b5e0c9d18f2a7b64",
  "verified_at": 1794268800
}

Hành vi của popup

• Popup hiện số đã che và kênh gửi. Người dùng nhập mã; mã sai thì popup báo và cho biết còn bao nhiêu lần thử, mã hết hạn thì popup chuyển sang nút gửi mã mới.
• Gửi lại mã: người dùng bấm gửi lại ngay trong popup, tối đa theo Số lần gửi lại trong popup của dự án (đặt ở trang dự án ▸ Cài đặt gửi, từ 0 đến 5). Mỗi lần gửi lại là một lần gửi thật: tính vào hạn mức và trừ ví như otp/send. Gửi lại quá nhanh thì popup đếm ngược và mở nút khi được gửi.
• Đổi số điện thoại: đóng popup, onClose nhận change_phone để bạn cho người dùng nhập lại số rồi tạo phiên mới. Phiên cũ không dùng tiếp được.
• Báo cáo lạm dụng: popup có ô để người dùng báo trang đang dùng eOTP để lừa đảo. Báo cáo gửi về đội ngũ eOTP xem xét; popup vẫn mở và người dùng vẫn nhập mã được.

Thông tin dự án

Xem trạng thái, gói, lượng OTP đã dùng và số dư ví của tài khoản sở hữu dự án. Hữu ích để theo dõi hạn mức hoặc kiểm khoá khi triển khai.

curl https://eotp.com.vn/api/v1/project \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET"

{
  "ok": true,
  "project": {
    "id": 12,
    "name": "Shop Hoa Mai",
    "type": "web",
    "status": "approved",
    "tier": 2,
    "default_channel": "zalo_then_sms",
    "otp_ttl": 300,
    "month_used": 37,
    "month_quota": 10000,
    "today_used": 4,
    "currency": "VND",
    "balance_minor": 120000,
    "balance_main_minor": 100000,
    "balance_bonus_minor": 20000,
    "balance_vnd": 120000,
    "balance_main_vnd": 100000,
    "balance_bonus_vnd": 20000
  }
}

Kích hoạt DEVELOPER

Website có hai cách tích hợp: Popup xác thực (mặc định) và Nút hiện sẵn. Nút hiện sẵn đặt nút "Xác thực eOTP" lên trang của bạn; người dùng bấm nút là popup xác thực mở, phiên vẫn do máy chủ của bạn tạo như kiểu popup (xem Bấm nút mở popup). Chọn cách ở trang dự án ▸ tab API key & tích hợp.

Dự án mới được duyệt ở gói FREE (Cấp 1). Để lên DEVELOPER (Cấp 2) không cần chờ duyệt tay: bạn chứng minh dự án đã tích hợp eOTP thật, hệ thống tự mở cấp.

• Website, popup xác thực: trong 30 ngày gần nhất có ít nhất một lần người dùng xác minh thành công trong popup mở từ đúng tên miền của dự án (mã gửi thật, không tính chế độ thử), và trang công khai của bạn có nạp https://eotp.com.vn/sdk/eotp-1.js. Bot của eOTP tải trang, thấy SDK thì mở DEVELOPER.
• Website, nút hiện sẵn: nhúng nút eOTP (iframe /embed/<api_key>) lên trang thật chạy HTTPS trên tên miền đã khai báo hoặc tên miền con. Lượt tải iframe đúng tên miền chỉ ghi nhận ứng viên; bot của eOTP sau đó tải trang công khai của bạn, thấy đường dẫn /embed/<api_key> trên trang thì mở DEVELOPER.
• Ứng dụng: thêm SDK kiểm license (EotpLicense.kt cho Android, EotpLicense.swift cho iOS) và gọi check() một lần mỗi khi app mở. DEVELOPER tự mở khi đủ hai điều kiện: lượt kiểm license đúng app id từ ít nhất 2 mạng khác nhau (ví dụ Wi‑Fi rồi 4G; hai máy cùng một Wi‑Fi chỉ tính là một mạng), và ít nhất 1 mã OTP thật được máy chủ của bạn gửi và kiểm qua API (/otp/send rồi /otp/verify). Mã gửi ở Chế độ thử không được tính.

<iframe src="https://eotp.com.vn/embed/eo_live_xxxxxxxxxxxxxxxx?lang=vi&style=logo-text&theme=dark&size=32" width="153" height="32" style="border:0" loading="lazy" referrerpolicy="no-referrer-when-downgrade" title="Xác thực eOTP"></iframe>

<!-- 1. Nút -->
<iframe src="https://eotp.com.vn/embed/eo_live_xxxxxxxxxxxxxxxx?lang=vi&style=logo-text&theme=dark&size=32" width="153" height="32" style="border:0" loading="lazy" referrerpolicy="no-referrer-when-downgrade" title="Xác thực eOTP"></iframe>
<!-- 2. Bấm nút → mở popup -->
<script src="https://eotp.com.vn/sdk/eotp-1.js"></script>
<script>
eOTP.onButton(function () {
  var phone = document.querySelector('#phone').value;            // số người dùng nhập trên trang của bạn
  fetch('/your-server/eotp-session', { method: 'POST', body: new URLSearchParams({ phone: phone }) })
    .then(function (r) { return r.json(); })
    .then(function (d) {
      eOTP.open({ session: d.session, onVerified: function (r) { /* gửi r.result về máy chủ để xác nhận */ } });
    });
});
</script>

EotpLicense.check(context, "eo_live_xxxxxxxxxxxxxxxx") { r ->
    if (r.licensed) Log.i("eOTP", "DEVELOPER: ${r.project}") else Log.w("eOTP", "license: ${r.error}")
}

EotpLicense.check(apiKey: "eo_live_xxxxxxxxxxxxxxxx") { r in
    print(r.licensed ? "DEVELOPER: \(r.project ?? "")" : "license: \(r.error ?? "")")
}

SDK gọi GET https://eotp.com.vn/api/v1/license?app=<package|bundle> kèm header X-Api-Key. Thành công trả về:

{
  "ok": true,
  "licensed": true,
  "project": "PRJ-XXXXXX",
  "tier": 2,
  "unlocked_now": true,
  "evidence": {
    "pings_ok": 3,
    "subnets": 2,
    "otp_verified": 1,
    "required": { "subnets": 2, "otp_verified": 1 }
  }
}

unlocked_now: true nghĩa là dự án vừa được mở DEVELOPER ở chính lần gọi này. evidence cho biết bằng chứng đã có so với mức cần (required); otp_verified chỉ đếm mã thật, không đếm mã gửi ở Chế độ thử. SDK trả hai trường này trong Result: unlockedNow và evidence (pingsOk, subnets, otpVerified, requiredSubnets, requiredOtpVerified); lần gọi lỗi thì cả hai là null/nil. Chỉ gửi API key, không gửi Secret key từ app.

Kênh, giá và hạn mức

4 chế độ gửi

Giá như nhau ở mọi gói trả phí; gói FREE không trừ ví. Lần gửi thất bại được hoàn tiền ngay, coi như không trừ. Ví chỉ đủ cho Zalo thì zalo_then_sms tự hạ về zalo. Gói FREE chỉ gửi một kênh: both và zalo_then_sms tự chuyển về kênh mặc định của dự án (zalo hoặc sms, chọn ở Cài đặt gửi), không báo lỗi.

Quốc gia người nhận

Mỗi nước có cờ kênh riêng (xem countries trong GET /pricing). Khi gửi, eOTP đọc mã nước của số nhận: nước chưa có Zalo thì gửi sms, nước chưa có SMS thì gửi zalo (phản hồi có channel_note); nước không có kênh nào trả channel_not_supported_in_country; nước chưa mở trả country_not_supported.

Các gói và hạn mức

Hạn mức tính theo TÀI KHOẢN: mọi dự án của bạn dùng chung một bể, theo gói cao nhất trong các dự án.

Tháng và ngày tính theo giờ UTC, làm mới lúc 00:00 UTC. Một OTP được tính hạn mức khi có ít nhất một lần gửi không thất bại. Hết hạn mức tháng, send trả quota_exceeded; hết hạn mức ngày trả daily_quota_exceeded (HTTP 429).

Giá và quốc gia

Bảng giá, hạn mức các gói, gói nạp và danh sách nước hỗ trợ. Công khai: không cần khoá, mở CORS (Access-Control-Allow-Origin: *) nên gọi được cả từ trình duyệt. Phản hồi được cache 300 giây (Cache-Control: public, max-age=300) và có ETag: gửi If-None-Match để nhận 304 khi chưa đổi.

curl https://eotp.com.vn/api/v1/pricing

{
  "ok": true,
  "currency": "VND",
  "price_zalo_vnd": 1550,
  "price_sms_vnd": 2000,
  "tiers": {
    "1": { "name": "FREE", "monthly_quota": 100, "daily_quota": 20 },
    "2": { "name": "DEVELOPER", "monthly_quota": 100000, "daily_quota": 10000 },
    "3": { "name": "UNLIMITED", "monthly_quota": null, "daily_quota": null }
  },
  "topup_packages": [{ "amount": 100000, "bonus_pct": 0 }],
  "countries": [
    { "iso": "VN", "name_en": "Vietnam", "name_vi": "Việt Nam", "dial": "84", "sms": true, "zalo": true, "enabled": true }
  ],
  "updated_at": 1794268800
}

monthly_quota/daily_quota bằng null là không giới hạn. Nước có enabled: false chưa nhận gửi OTP. dial là giá trị dùng cho country_code.

Ví và tiền tệ

• Mỗi loại tiền một ví riêng. Tài khoản có ví VND (tính bằng đồng) và ví USD (tính bằng cent). Chỉ một ví đang dùng (currency trong project); ví kia được giữ nguyên, không quy đổi. Mọi số tiền trong API ở đơn vị nhỏ nhất của ví đang dùng.
• Ví gốc và ví tặng. Mỗi ví gồm phần gốc (tiền bạn nạp) và phần tặng (khuyến mãi của gói nạp, mã khuyến mãi). Khi gửi OTP, eOTP trừ ví tặng trước, hết mới trừ ví gốc; hoàn tiền trả về đúng ví đã trừ.
• Trừ ngay khi nhận yêu cầu, hoàn khi thất bại. Tiền được trừ cùng lúc kiểm số dư, nên gọi song song không làm âm ví. Gửi thất bại được hoàn ngay; zalo_then_sms hoàn phần SMS khi Zalo tới máy.
• Nạp tiền theo gói ở trang Ví của cổng developer. Chuyển khoản VietQR nạp vào ví VND, mã QR có hạn 30 phút. Gói nạp hiện hành có trong topup_packages của GET /pricing.
• Mã khuyến mãi nhập khi tạo yêu cầu nạp; mỗi tài khoản dùng mỗi mã một lần, tiền khuyến mãi vào ví tặng khi khoản nạp được xác nhận.

Gói FREE không trừ ví. Số dư không đủ cho một tin thì send trả 402 insufficient_balance kèm currency, balance, cost.

Mã lỗi

Toàn bộ mã lỗi của API v1. Cột "Ý nghĩa và nên làm" là cách xử lý khuyến nghị trên máy chủ của bạn.

Hạn mức gói và thông số mã

Mỗi gói có hạn mức OTP theo tháng và theo ngày, tính chung cho mọi dự án của tài khoản (xem Kênh, giá và hạn mức và GET /pricing). Vượt hạn mức, send trả HTTP 429:

Cần hạn mức cao hơn gói hiện có, gọi hotline +84 901 888 484.

Ví dụ code

Mọi ví dụ chạy trên máy chủ, đọc khoá từ biến môi trường EASYOTP_API_KEY và EASYOTP_API_SECRET, gửi đủ 2 header X-Api-Key + X-Api-Secret. Mỗi ví dụ gửi mã rồi kiểm mã; chạy được với cả phản hồi hàng đợi lẫn đồng bộ của send.

# 1. Gửi mã
curl -X POST https://eotp.com.vn/api/v1/otp/send \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0912345678","country_code":"84"}'

# 2. (Tuỳ chọn) Tra trạng thái gửi
curl "https://eotp.com.vn/api/v1/otp/status?request_id=3f9a1c0e8b7d4a26b5e0c9d18f2a7b64" \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET"

# 3. Kiểm mã (thay request_id và code)
curl -X POST https://eotp.com.vn/api/v1/otp/verify \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"3f9a1c0e8b7d4a26b5e0c9d18f2a7b64","code":"123456"}'

# 4. Xem hạn mức và số dư
curl https://eotp.com.vn/api/v1/project \
  -H "X-Api-Key: $EASYOTP_API_KEY" \
  -H "X-Api-Secret: $EASYOTP_API_SECRET"

const BASE = "https://eotp.com.vn/api/v1";
const API_KEY = process.env.EASYOTP_API_KEY;
const API_SECRET = process.env.EASYOTP_API_SECRET;

async function easyOtp(path, body) {
  const res = await fetch(BASE + path, {
    method: "POST",
    headers: { "X-Api-Key": API_KEY, "X-Api-Secret": API_SECRET, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(35000),
  });
  const data = await res.json();
  return { status: res.status, ...data };
}

// 1. Gửi mã
const sent = await easyOtp("/otp/send", { phone: "0912345678" });
if (!sent.ok) {
  throw new Error(`${sent.error}: ${sent.message}`);
}
// Lưu sent.request_id vào phiên của người dùng (session), không lưu mã.

// 2. Kiểm mã người dùng nhập
const check = await easyOtp("/otp/verify", {
  request_id: sent.request_id,
  code: "123456",
});
if (check.ok && check.verified) {
  // Đăng nhập / xác nhận thành công
} else {
  console.log(check.error, check.attempts_left);
}

<?php
function easy_otp_call(string $path, array $body): array
{
    $ch = curl_init('https://eotp.com.vn/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            'X-Api-Key: ' . getenv('EASYOTP_API_KEY'),
            'X-Api-Secret: ' . getenv('EASYOTP_API_SECRET'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode($body),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 35,
    ]);
    $raw    = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $data = json_decode((string) $raw, true);
    if (!is_array($data)) {
        $data = ['ok' => false, 'error' => 'network_error', 'message' => 'Không kết nối được eOTP.'];
    }
    $data['status'] = $status;
    return $data;
}

// 1. Gửi mã
$sent = easy_otp_call('/otp/send', ['phone' => '0912345678']);
if (!$sent['ok']) {
    exit($sent['error'] . ': ' . $sent['message']);
}
$_SESSION['otp_request_id'] = $sent['request_id'];

// 2. Kiểm mã người dùng nhập
$check = easy_otp_call('/otp/verify', [
    'request_id' => $_SESSION['otp_request_id'],
    'code'       => (string) ($_POST['code'] ?? ''),
]);
if ($check['ok'] && $check['verified']) {
    // Đăng nhập / xác nhận thành công
}

import os
import requests

BASE = "https://eotp.com.vn/api/v1"
HEADERS = {
    "X-Api-Key": os.environ["EASYOTP_API_KEY"],
    "X-Api-Secret": os.environ["EASYOTP_API_SECRET"],
}


def easy_otp(path, body):
    r = requests.post(BASE + path, json=body, headers=HEADERS, timeout=35)
    data = r.json()
    data["status"] = r.status_code
    return data


# 1. Gửi mã
sent = easy_otp("/otp/send", {"phone": "0912345678"})
if not sent["ok"]:
    raise RuntimeError(f"{sent['error']}: {sent['message']}")
request_id = sent["request_id"]  # lưu vào phiên của người dùng

# 2. Kiểm mã người dùng nhập
check = easy_otp("/otp/verify", {"request_id": request_id, "code": "123456"})
if check["ok"] and check.get("verified"):
    print("Xác minh thành công")
else:
    print(check["error"], check.get("attempts_left"))

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject
import java.util.concurrent.TimeUnit

private const val BASE = "https://eotp.com.vn/api/v1"
private val apiKey = System.getenv("EASYOTP_API_KEY")
private val apiSecret = System.getenv("EASYOTP_API_SECRET")
private val jsonType = "application/json".toMediaType()
private val client = OkHttpClient.Builder()
    .callTimeout(35, TimeUnit.SECONDS)
    .build()

fun easyOtp(path: String, body: JSONObject): JSONObject {
    val request = Request.Builder()
        .url(BASE + path)
        .header("X-Api-Key", apiKey)
        .header("X-Api-Secret", apiSecret)
        .post(body.toString().toRequestBody(jsonType))
        .build()
    client.newCall(request).execute().use { res ->
        return JSONObject(res.body!!.string()).put("status", res.code)
    }
}

fun main() {
    // 1. Gửi mã
    val sent = easyOtp("/otp/send", JSONObject().put("phone", "0912345678"))
    if (!sent.getBoolean("ok")) {
        println(sent.getString("error") + ": " + sent.getString("message"))
        return
    }
    val requestId = sent.getString("request_id") // lưu vào phiên của người dùng

    // 2. Kiểm mã người dùng nhập
    val check = easyOtp(
        "/otp/verify",
        JSONObject().put("request_id", requestId).put("code", "123456"),
    )
    println(if (check.optBoolean("verified")) "Xác minh thành công" else check.getString("error"))
}

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

let base = "https://eotp.com.vn/api/v1"
let apiKey = ProcessInfo.processInfo.environment["EASYOTP_API_KEY"] ?? ""
let apiSecret = ProcessInfo.processInfo.environment["EASYOTP_API_SECRET"] ?? ""

func easyOtp(_ path: String, _ body: [String: Any]) async throws -> [String: Any] {
    var req = URLRequest(url: URL(string: base + path)!)
    req.httpMethod = "POST"
    req.timeoutInterval = 35
    req.setValue(apiKey, forHTTPHeaderField: "X-Api-Key")
    req.setValue(apiSecret, forHTTPHeaderField: "X-Api-Secret")
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    req.httpBody = try JSONSerialization.data(withJSONObject: body)
    let (data, response) = try await URLSession.shared.data(for: req)
    var json = (try JSONSerialization.jsonObject(with: data)) as? [String: Any] ?? [:]
    json["status"] = (response as? HTTPURLResponse)?.statusCode ?? 0
    return json
}

// 1. Gửi mã
let sent = try await easyOtp("/otp/send", ["phone": "0912345678"])
guard sent["ok"] as? Bool == true, let requestId = sent["request_id"] as? String else {
    print(sent["error"] as? String ?? "", sent["message"] as? String ?? "")
    exit(1)
}

// 2. Kiểm mã người dùng nhập
let check = try await easyOtp("/otp/verify", ["request_id": requestId, "code": "123456"])
print(check["verified"] as? Bool == true ? "Xác minh thành công" : (check["error"] as? String ?? ""))

Luồng khuyến nghị

1. Người dùng nhập số điện thoại

   Ứng dụng hoặc trang web gửi số lên máy chủ của bạn (không gọi thẳng eOTP).

2. Máy chủ gọi send

   Trước khi gọi, máy chủ tự chặn lạm dụng theo IP/thiết bị của người dùng (ví dụ captcha, giới hạn số lần). Lưu request_id và phone_e164 vào phiên của người dùng. Dùng code_type để mở bàn phím số hay chữ cho ô nhập.

3. Người dùng nhập mã

   Hiện ô nhập mã và đếm ngược theo expires_in. Muốn báo "đã gửi" chính xác, tra otp/status; gặp failed thì gợi ý gửi lại qua kênh khác. Nút "Gửi lại" nên mở sau một khoảng chờ để người dùng kịp nhận tin.

4. Máy chủ gọi verify

   Lấy request_id từ phiên (không tin giá trị do ứng dụng gửi lên), gửi kèm mã người dùng nhập.

5. Xử lý kết quả

   verified: true thì đăng nhập/xác nhận và xoá request_id khỏi phiên. wrong_code cho nhập lại; expired hoặc too_many_attempts thì gửi mã mới.

Trên website, bạn không cần tự dựng bước 3–5: dùng Popup xác thực, eOTP hiện ô nhập mã, gửi lại và báo lỗi, máy chủ của bạn chỉ gọi popup/session rồi popup/result.

Bảo mật

• Giữ Secret key trên máy chủ, trong biến môi trường hoặc kho bí mật. Không đưa vào app, JavaScript phía trình duyệt, ảnh chụp màn hình hay kho mã. API key một mình chỉ là định danh, nhúng iframe/SDK được.
• Không ghi mã OTP vào log. eOTP không bao giờ trả mã qua API; bạn cũng không ghi mã người dùng nhập vào log hay công cụ theo dõi lỗi.
• Không ghi Secret key vào log. Che khoá khi in cấu hình hoặc lỗi.
• Để thời gian sống ngắn. 5 phút là đủ cho đa số luồng; chỉnh 1–15 phút trong cài đặt dự án.
• Chặn lạm dụng ở phía bạn. Giới hạn của eOTP tính theo dự án và theo IP máy chủ của bạn, không theo người dùng cuối: bạn nên giới hạn thêm theo IP, thiết bị, tài khoản để kẻ xấu không dùng hết hạn mức.
• Đổi secret khi nghi lộ. Tạo secret mới trong tab Tích hợp, secret cũ mất hiệu lực ngay. Cập nhật máy chủ trước để không dính auth_rate_limited.

Cần hỗ trợ tích hợp? Gọi hotline +84 901 888 484.

Thay đổi

11/11/2026

• Callback về máy chủ của bạn có thêm header X-Eotp-Timestamp; X-Eotp-Signature nay là HMAC-SHA256 của timestamp + "." + thân thô (chữ ký chỉ trên thân không còn dùng). Bạn cập nhật đoạn kiểm theo Xác minh chữ ký và từ chối lời gọi lệch quá 300 giây.

10/11/2026

• Nút hiện sẵn gọi được popup: nạp /sdk/eotp-1.js và đăng ký eOTP.onButton(handler), người dùng bấm nút eOTP là hàm của bạn chạy để tạo phiên và mở eOTP.open. Trang không đăng ký thì nút mở trang eOTP như cũ. Xem Bấm nút mở popup.
• Thêm Popup xác thực cho website, cách tích hợp mặc định: máy chủ gọi POST /popup/session, trang nạp /sdk/eotp-1.js và gọi eOTP.open, máy chủ xác nhận bằng POST /popup/result. Số lần gửi lại trong popup đặt ở Cài đặt gửi của dự án. Lỗi mới popup_not_supported, invalid_result.
• Nút nhúng /embed/<api_key> có 6 kiểu, giao diện tối/sáng và cỡ 28/32/36: chọn ở tab API key & tích hợp của dự án, hoặc truyền style, theme, size trên đường dẫn iframe. Mã cũ 180 × 40 vẫn hoạt động; bạn nên thay bằng mã mới để nút khít khung.
• otp/send có chế độ hàng đợi: trả ngay "status": "queued" và eta_ms; lúc đông vẫn nhận yêu cầu, chỉ tăng eta_ms.
• Thêm GET /otp/status để tra trạng thái gửi (queued, sending, sent, failed, expired).
• otp/send nhận callback_url (tuỳ chọn): eOTP POST kết quả gửi về máy chủ của bạn, ký bằng X-Eotp-Signature, gửi lại tối đa 3 lần. Lỗi mới invalid_callback_url.

9/11/2026

• Xác thực bằng 2 khoá: X-Api-Key + X-Api-Secret (hoặc Bearer key:secret). Khoá cũ một khoá còn dùng 30 ngày kèm header Deprecation, sau đó 401 legacy_auth_expired.
• Chặn IP tạm thời khi xác thực sai nhiều lần liên tiếp: 429 auth_rate_limited.
• Số điện thoại nhiều nước: phone dạng E.164 hoặc nội địa + country_code; phản hồi có phone_e164. Lỗi mới country_not_supported, channel_not_supported_in_country; kênh đổi theo nước có channel_note.
• Kiểu mã alnum (chữ + số, so không phân biệt hoa/thường) và độ dài 4–10 đặt trong Cài đặt gửi của dự án.
• Hạn mức tháng và ngày tính theo bể tài khoản (mọi dự án dùng chung); thêm daily_quota_exceeded. Gói FREE gửi một kênh.
• Ví theo loại tiền (VND, USD) và ví tặng: thêm currency, cost, balance ở send và balance_minor ở project; các trường *_vnd giữ cho tương thích.
• license trả evidence; DEVELOPER mở khi đủ bằng chứng tích hợp thật.