Tài liệu API Free Passive OTP

Passive OTP đảo chiều SMS OTP: người dùng của bạn tự nhắn một tin chứa mã tới số chung, hệ thống xác nhận SĐT gửi đúng là SĐT cần xác thực. Không cần gửi tin đi, không lo tin bị chặn hay đến chậm.

Bắt đầu nhanh

1. Đăng ký bằng Google, xác thực SĐT và nhận 600.000đ (2.000 lượt) dùng trong 6 tháng.
2. Lấy API key, syntax và số chung ở dashboard → Tích hợp. Khai báo webhook URL nếu muốn nhận kết quả đẩy về.
3. Server của bạn gọi POST /otp/requests với SĐT người dùng; app hiển thị “Soạn SYNTAX MÃ gửi số chung”.
4. Nhận otp.verified qua webhook, hoặc hỏi GET /otp/requests/{id}.

Base URL: http://localhost:3000/api/v1. Mọi response là JSON, thời gian theo ISO 8601 UTC, tiền là số nguyên VNĐ.

Xác thực

Gửi API key trong header Authorization: Bearer pk_live_…. Key chỉ dùng ở server: không đặt trong app di động, trình duyệt hay repo. Mỗi tài khoản có tối đa 3 key đang hoạt động; thu hồi key ở dashboard → Cài đặt.

Hai cách tích hợp

Mã khớp khi đứng đầu phần sau syntax; chữ phía sau mã được bỏ qua (SHOP 482913 cam on vẫn khớp, SHOP X482913 thì không). Hạn được tính theo thời điểm nhà mạng nhận tin.

Tạo request OTP

POST /otp/requests — trừ 300đ khi tạo thành công. Request cũ còn chờ của cùng SĐT chuyển superseded (không hoàn tiền).

curl -X POST http://localhost:3000/api/v1/otp/requests \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{"phone":"0912345678","reference":"order-1001"}'

201 Created
{
  "id": "otp_01JABCXYZ",
  "status": "pending",
  "phone": "84912345678",
  "sms_to": "<số chung>",
  "sms_content": "SHOPABC 482913",
  "sms_uri": "sms:<số chung>?&body=SHOPABC%20482913",
  "expires_at": "2026-10-07T03:03:00Z",
  "max_attempts": 3,
  "charged": 300,
  "balance": 599700,
  "reference": "order-1001"
}

Trên điện thoại, mở sms_uri để ứng dụng tin nhắn điền sẵn nội dung và số nhận.

Xem request

GET /otp/requests/{id} trả các trường như trên cộng attempts, verified_at, created_at và message (tin đã khớp: {id, content, received_at}).

curl http://localhost:3000/api/v1/otp/requests/otp_01JABCXYZ \
  -H "Authorization: Bearer $API_KEY"

Danh sách, tin đến, tài khoản

Phân trang: limit mặc định 20, tối đa 100; dùng next_cursor của trang trước làm cursor. Response: {"data": [...], "next_cursor": "..." | null}.

Webhook

Hệ thống gửi POST JSON tới webhook URL (bắt buộc https://) với các header X-Event-Id, X-Event-Type, X-Timestamp, X-Signature. Trả HTTP 2xx trong 5 giây là thành công; nếu không, hệ thống thử lại sau 10 giây, 1 phút, 5 phút (tổng 4 lần). Webhook lỗi không hoàn tiền; kết quả vẫn lấy được qua API, và bạn có thể gửi lại từ dashboard.

{
  "id": "evt_01JABD...",
  "type": "otp.verified",
  "created_at": "2026-10-07T03:01:12Z",
  "data": {
    "request_id": "otp_01JABCXYZ",
    "reference": "order-1001",
    "phone": "84912345678",
    "status": "verified",
    "attempts": 1,
    "message_id": "msg_01JABD...",
    "content": "SHOPABC 482913",
    "received_at": "2026-10-07T03:01:10Z"
  }
}

message.received có data gồm message_id, phone, syntax, payload, content, received_at; otp.expired có request_id, reference, phone, status, attempts, expires_at; ping có data rỗng. Dùng id (= X-Event-Id) để bỏ qua sự kiện đã xử lý.

Kiểm tra chữ ký

X-Signature: sha256=<hex HMAC-SHA256(webhook_secret, X-Timestamp + "." + body)>. Tính trên body nguyên bản (trước khi parse JSON), so sánh bằng phép so thời gian hằng, và từ chối nếu X-Timestamp lệch quá 5 phút. Webhook secret xem ở dashboard → Tích hợp.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: chuỗi body nguyên bản (chưa parse JSON)
export function verifyWebhook(rawBody, headers, secret) {
  const ts = headers["x-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // lệch quá 5 phút
  const expected = "sha256=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const given = String(headers["x-signature"] ?? "");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Mã lỗi

Dạng chung: {"error": {"code": "insufficient_balance", "message": "...", "request_id": "req_..."}}. Gửi kèm request_id khi cần hỗ trợ.

Giới hạn và idempotency

• 10 request/giây cho mỗi API key.
• Mỗi SĐT: 1 request mỗi 30 giây và 20 request mỗi 24 giờ.
• Header Idempotency-Key (≤ 100 ký tự) cho POST: gửi lại cùng key và cùng body trong 24 giờ sẽ nhận đúng response cũ (header Idempotent-Replayed: true) và không bị trừ tiền lần hai.

Câu hỏi thường gặp

Người dùng có mất phí nhắn tin không?

Có, cước một tin nhắn thường theo gói của họ. Bù lại họ không phải chờ tin OTP đến.

Người dùng nhắn sai mã thì sao?

Request tăng attempts; đạt max_attempts thì failed và bạn nhận otp.failed. Tạo request mới để thử lại.

Tin nhắn đến sau khi request hết hạn?

Không còn request để khớp nên được tính như tin chỉ syntax (300đ) và gửi message.received.

Hết tiền thì sao?

API trả 402, tin chỉ syntax bị chặn (vẫn xem được trong log). Liên hệ để dùng gói trả phí.

Đổi syntax được không?

1 lần mỗi 30 ngày ở dashboard → Cài đặt. Syntax cũ vẫn về tài khoản bạn trong 30 ngày.