REST API v1

Tài liệu API MangoOTP dành cho nhà phát triển

Tự động hóa quy trình nhận SMS một lần qua Partner API. Yêu cầu phải dùng X-API-Key và tuân thủ danh sách IP, mã đơn đối tác, giới hạn tốc độ và tần suất truy vấn.

codeXem tài liệu API keyTạo khóa API

Quy trình bắt đầu nhanh

Một tích hợp điển hình gồm bốn bước từ thông tin xác thực đến khi nhận SMS.

Tạo khóa API

Sau khi đăng nhập, hãy tạo khóa có tiền tố mago_live_ trên trang Khóa API. Khóa gốc chỉ được hiển thị một lần.

Mỗi tài khoản chỉ giữ một khóa đối tác đang hoạt động. Hãy cấu hình danh sách IP đầu ra cố định và URL Webhook trước khi dùng trong môi trường sản xuất.

Lấy giá theo dịch vụ và quốc gia

Lấy danh sách dịch vụ, lấy các quốc gia khả dụng cho dịch vụ, sau đó yêu cầu giá nền tảng duy nhất và lượng tồn ước tính cho cặp dịch vụ-quốc gia.

Phản hồi chỉ chứa báo giá và dữ liệu tồn kho của nền tảng mà ứng dụng cần.

Tạo đơn nhận OTP

Gửi service, country, sellPrice và maxSellPrice tùy chọn cùng partnerOrderNo để tránh đóng băng số dư nhiều lần khi thử lại.

Nếu không gửi maxSellPrice, giá hiện tại phải bằng sellPrice; nếu có trần, giá hiện tại không được vượt trần.

Truy vấn trạng thái đơn

Truy vấn bằng mã đơn để lấy số điện thoại, mã SMS và trạng thái vòng đời.

Chỉ thử lại sau khi có kết quả thất bại rõ ràng, hết hàng hoặc giá bị từ chối.

shield

Xác thực

Mọi yêu cầu API Đối tác dùng X-API-Key. Hệ thống chỉ lưu giá trị băm SHA-256 và IP kết nối phải nằm trong danh sách cho phép không rỗng. X-Forwarded-For không được dùng cho quyết định này.

X-API-Key: mago_live_xxxxxxxxxxxxxxxx

bolt

Mã đơn hàng đối tác và bảo vệ giá

POST /api/v1/activation/createOrder dùng partnerOrderNo, sellPrice bắt buộc và maxSellPrice tùy chọn. Yêu cầu thử lại giống hệt không tạo đơn trùng; giá và khả năng bán hiện tại được kiểm tra trước khi đóng băng tiền.

{"partnerOrderNo":"partner-order-20260707-001"}

Tài liệu điểm cuối

Tài liệu theo từng điểm cuối, theo thứ tự tích hợp phổ biến: URL, tham số, mẫu yêu cầu, phản hồi thành công và lỗi thường gặp.

API Đối tác

API nhận OTP và đọc số dư MAIN dùng xác thực X-API-Key độc lập. Quản lý khóa API vẫn thuộc giao diện User đã đăng nhập.

GET/api/v1/activation/getServices

Lấy danh sách dịch vụ

X-API-Key

Trả về các dịch vụ OTP đang bật để tạo bộ chọn và định kỳ làm mới cache danh mục của đối tác.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	array	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data[]	array	có	Danh sách dịch vụ theo thứ tự hiển thị của nền tảng.
data[].serviceCode	string	có	Mã dịch vụ nền tảng dùng để lấy quốc gia, báo giá và tạo đơn.
data[].serviceName	string	có	Tên hiển thị của dịch vụ.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/activation/getServices
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "serviceCode": "telegram",
      "serviceName": "Telegram"
    }
  ]
}

Lỗi thường gặp

AUTH-E001: thiếu khóa API.
AUTH-E002: khóa API không hợp lệ, đã thu hồi, hết hạn hoặc IP không khớp.

GET/api/v1/activation/getCountries

Lấy quốc gia được hỗ trợ

X-API-Key

Trả về tất cả quốc gia đang bật mà hệ thống hỗ trợ, không cần tham số nghiệp vụ.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	array	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data[]	array	có	Tất cả quốc gia đang bật mà hệ thống hỗ trợ.
data[].countryCode	string	có	Mã quốc gia ISO dùng để báo giá và tạo đơn.
data[].countryName	string	có	Tên quốc gia hiển thị theo ngôn ngữ hiện tại.
data[].flagEmoji	string / null	không	Emoji cờ quốc gia.
data[].phonePrefix	string / null	không	Mã gọi quốc gia.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/activation/getCountries
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "countryCode": "US",
      "countryName": "United States",
      "flagEmoji": "🇺🇸",
      "phonePrefix": "+1"
    }
  ]
}

Lỗi thường gặp

AUTH-E001: thiếu khóa API.
AUTH-E002: khóa API không hợp lệ, đã thu hồi, hết hạn hoặc IP không khớp.

GET/api/v1/activation/getPrice

Lấy giá dịch vụ-quốc gia

X-API-Key

Trả về giá bán nền tảng hiện tại và tồn kho ước tính, không phát hành mã báo giá.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.
service	Query	string	có	Mã dịch vụ nền tảng.
country	Query	string	có	Mã quốc gia ISO, ví dụ US hoặc GB.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.service	string	có	Mã dịch vụ được yêu cầu.
data.country	string	có	Mã quốc gia được yêu cầu.
data.sellPrice	decimal number	có	Giá bán đơn vị từ dòng Catalog hiện tại.
data.currency	string	có	Mã tiền tệ giá hiện do API trả về là USD.
data.availableCount	integer	có	Ước tính tồn kho Catalog hiện tại; số này không phải lượng được giữ chỗ cho bên gọi.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/activation/getPrice?service=telegram&country=US
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": {
    "service": "telegram",
    "country": "US",
    "sellPrice": 1.050000,
    "currency": "USD",
    "availableCount": 42
  }
}

Lỗi thường gặp

OTP-E006: cặp dịch vụ-quốc gia này hết hàng.
COMMON-E002: định dạng service hoặc country không hợp lệ.
AUTH-E002: khóa API bị từ chối.

POST/api/v1/activation/createOrder

Tạo đơn nhận OTP

X-API-Key

Tạo đơn OTP và đóng băng giá Catalog hiện tại; partnerOrderNo bảo đảm lũy đẳng và maxSellPrice tùy chọn giới hạn biến động giá.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.
partnerOrderNo	Body	string	có	Mã đơn do hệ thống đối tác tạo. Mã phải duy nhất trong cùng tài khoản đối tác và nghiệp vụ OTP, đồng thời giữ nguyên khi thử lại cùng một yêu cầu.
service	Body	string	có	Mã dịch vụ nền tảng.
country	Body	string	có	Mã quốc gia ISO.
sellPrice	Body	decimal number	có	Giá bán nền tảng mà đối tác vừa đọc; phải lớn hơn 0 và có tối đa sáu chữ số thập phân.
maxSellPrice	Body	decimal number	không	Trần giá tùy chọn, không được nhỏ hơn sellPrice. Nếu bỏ qua thì không chấp nhận thay đổi giá.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.orderNo	string	có	Mã đơn OTP MangoOTP.
data.partnerOrderNo	string	có	Mã đơn của đối tác.
data.status	string	có	Trạng thái hiện tại của đơn OTP.
data.phone	string / null	không	Số điện thoại được cấp; là null trước khi cấp số.
data.smsCode	string / null	không	OTP được trích xuất; là null trước khi nhận SMS.
data.payAmount	decimal number	có	Số tiền người dùng phải trả, được đóng băng và quyết toán cuối cùng cho đơn.
data.currency	string	có	Đơn vị tiền tệ của đơn, hiện luôn là USD.

Mẫu yêu cầu

POST https://api.mangootp.com/api/v1/activation/createOrder
X-API-Key: mago_live_xxx
Accept: application/json
Content-Type: application/json

{
  "partnerOrderNo": "partner-order-20260707-001",
  "service": "telegram",
  "country": "US",
  "sellPrice": 1.05,
  "maxSellPrice": 1.10
}

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

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "PENDING",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Lỗi thường gặp

ACC-E004: số dư khả dụng không đủ.
ORD-E004: mã báo giá hoặc giới hạn giá chấp nhận không hợp lệ.
OTP-E006: Catalog hiện không còn hàng.
COMMON-E003: định dạng hoặc độ chính xác của giới hạn giá không hợp lệ.

GET/api/v1/activation/getOrders

Lấy danh sách đơn OTP

X-API-Key

Phân trang các đơn OTP thuộc người dùng sở hữu khóa API, dùng để đồng bộ lịch sử và đối soát trạng thái phía đối tác.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.
page	Query	number	không	Số trang; mặc định là 1.
size	Query	number	không	Kích thước trang; mặc định là 20 và bị giới hạn bởi nền tảng.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.total	number	có	Tổng số đơn khớp điều kiện.
data.records[]	array	có	Danh sách đơn trong trang hiện tại.
data.records[].orderNo	string	có	Mã đơn OTP MangoOTP.
data.records[].partnerOrderNo	string	có	Mã đơn của đối tác.
data.records[].status	string	có	Trạng thái hiện tại của đơn OTP.
data.records[].serviceCode	string	có	Mã dịch vụ.
data.records[].countryCode	string	có	Mã quốc gia ISO.
data.records[].phone	string / null	không	Số điện thoại được cấp; là null trước khi cấp số.
data.records[].smsCode	string / null	không	OTP được trích xuất; là null trước khi nhận SMS.
data.records[].payAmount	decimal number	có	Số tiền người dùng phải trả, được đóng băng và quyết toán cuối cùng cho đơn.
data.records[].refundAmount	decimal number	có	Số tiền đã hoàn cho người dùng.
data.records[].createdAt	datetime string	có	Thời điểm tạo đơn.
data.records[].completedAt	datetime string / null	không	Thời điểm hoàn tất hoặc null trước khi hoàn tất.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/activation/getOrders?page=1&size=20
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": {
    "total": 1,
    "records": [
      {
        "orderNo": "AO202607070000000001",
        "partnerOrderNo": "partner-order-20260707-001",
        "status": "ACTIVE",
        "serviceCode": "telegram",
        "countryCode": "US",
        "phone": "+12025550123",
        "smsCode": null,
        "payAmount": 1.050000,
        "refundAmount": 0.000000,
        "createdAt": "2026-06-22T18:07:22",
        "completedAt": null
      }
    ]
  }
}

Lỗi thường gặp

AUTH-E002: khóa API bị từ chối.
COMMON-E003: page hoặc size nằm ngoài phạm vi.

GET/api/v1/activation/getOrder?orderNo={orderNo}

Lấy chi tiết đơn OTP

X-API-Key

Đọc trạng thái, số điện thoại và mã SMS của một đơn. Hãy kiểm tra mã nghiệp vụ và data.status, không chỉ dựa vào trạng thái HTTP.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.
orderNo	Query	string	có	Mã đơn OTP MangoOTP.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.orderNo	string	có	Mã đơn OTP MangoOTP.
data.partnerOrderNo	string	có	Mã đơn của đối tác.
data.status	string	có	Trạng thái hiện tại của đơn OTP.
data.phone	string / null	không	Số điện thoại được cấp; là null trước khi cấp số.
data.smsCode	string / null	không	OTP được trích xuất; là null trước khi nhận SMS.
data.payAmount	decimal number	có	Số tiền người dùng phải trả, được đóng băng và quyết toán cuối cùng cho đơn.
data.currency	string	có	Đơn vị tiền tệ của đơn, hiện luôn là USD.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/activation/getOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "SUCCESS",
    "phone": "+12025550123",
    "smsCode": "834921",
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Lỗi thường gặp

ORD-E001: đơn không tồn tại hoặc không thuộc người dùng sở hữu khóa API.
COMMON-E002: định dạng orderNo không hợp lệ.

POST/api/v1/activation/cancelOrder?orderNo={orderNo}

Hủy đơn OTP

X-API-Key

Hủy đơn khi vẫn còn khả năng hủy. Đơn đang xử lý, đã nhận SMS hoặc đã kết thúc không bị hủy lần nữa.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.
orderNo	Query	string	có	Mã đơn OTP MangoOTP.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.orderNo	string	có	Mã đơn OTP MangoOTP.
data.partnerOrderNo	string	có	Mã đơn của đối tác.
data.status	string	có	Trạng thái hiện tại của đơn OTP.
data.phone	string / null	không	Số điện thoại được cấp; là null trước khi cấp số.
data.smsCode	string / null	không	OTP được trích xuất; là null trước khi nhận SMS.
data.payAmount	decimal number	có	Số tiền người dùng phải trả, được đóng băng và quyết toán cuối cùng cho đơn.
data.currency	string	có	Đơn vị tiền tệ của đơn, hiện luôn là USD.

Mẫu yêu cầu

POST https://api.mangootp.com/api/v1/activation/cancelOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "CANCELLED",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Lỗi thường gặp

ORD-E003 / ORD-E005: trạng thái hiện tại không cho phép hủy.
ORD-E001: đơn không tồn tại hoặc không thuộc người dùng sở hữu khóa API.

GET/api/v1/account/getBalance

Lấy số dư tài khoản

X-API-Key

Chỉ dựa vào khóa API để trả về số dư khả dụng MAIN của chủ sở hữu; không nhận email hoặc mã người dùng.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
X-API-Key	Header	string	có	Khóa API của đối tác. IP gọi phải khớp với danh sách IP cho phép của khóa.
X-Request-Id	Header	string	không	Mã liên kết tùy chọn của đối tác, gồm 1-64 chữ cái, chữ số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch nối; được ghi vào kiểm toán nhưng không thay thế X-Trace-Id.

Trường phản hồi	Kiểu	Bắt buộc	Mô tả
code	string	có	Mã nghiệp vụ và là căn cứ máy đọc duy nhất để quyết định nghiệp vụ. Thành công luôn là 0; lỗi tuân theo danh mục mã lỗi.
message	string	có	Chỉ là văn bản hỗ trợ cho nhật ký; không được phân tích hoặc dùng để quyết định nghiệp vụ. Backend chỉ duy trì tiếng Anh và tiếng Trung giản thể; yêu cầu tiếng Việt nhận message tiếng Anh.
data	object	có	Dữ liệu nghiệp vụ. Thường là null khi code khác 0.
data.accountType	string	có	Luôn là MAIN.
data.currency	string	có	Đơn vị tiền tệ của tài khoản chính, hiện là USD.
data.availableBalance	decimal number	có	Số dư khả dụng hiện tại của tài khoản chính.

Mẫu yêu cầu

GET https://api.mangootp.com/api/v1/account/getBalance
X-API-Key: mago_live_xxx
Accept: application/json

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

{
  "code": "0",
  "message": "success",
  "data": {
    "accountType": "MAIN",
    "currency": "USD",
    "availableBalance": 97.410000
  }
}

Lỗi thường gặp

AUTH-E002: khóa API không hợp lệ, đã thu hồi, hết hạn hoặc IP không khớp.
ACC-E001: không tồn tại tài khoản MAIN.

Sự kiện Webhook

Webhook chỉ thông báo khi đơn nhận mã đã nhận được SMS. Cấu hình URL gọi lại trên trang Khóa API.

activation.sms_received

Đã nhận SMS cho đơn OTP

Gửi sau khi MangoOTP nhận SMS và trích xuất OTP. Phản hồi tạo đơn đã trả về số điện thoại nên không gửi sự kiện cấp số OTP riêng.

{
  "eventId": "evt_AO202607070000000001_activation_sms_received",
  "eventType": "activation.sms_received",
  "status": "SUCCESS",
  "orderNo": "AO202607070000000001",
  "occurredAt": "2026-06-22T18:09:01Z",
  "data": {
    "orderNo": "AO202607070000000001",
    "service": "telegram",
    "country": "US",
    "phone": "+12025550123",
    "payAmount": 1.050000,
    "smsCode": "834921",
    "smsText": "Telegram code: 834921"
  }
}

verified_user

Chữ ký Webhook và thử lại

Cấu hình: người dùng đã đăng nhập cấu hình một URL Webhook cho khóa API đang hoạt động trên trang Khóa API. Webhook và yêu cầu API dùng chung chủ sở hữu khóa.
Chữ ký: mỗi lần gửi có X-Webhook-Signature: sha256=<hex>. Trước tiên băm API Key hiện tại bằng SHA-256 thành chuỗi hex chữ thường 64 ký tự, sau đó dùng byte UTF-8 của chuỗi này làm khóa HMAC-SHA256 để ký trực tiếp byte của phần thân HTTP JSON nguyên bản. Webhook không tạo khóa ký riêng.
Header: X-Webhook-Event chứa loại sự kiện, X-Webhook-Delivery-Id giữ nguyên cho mọi thông báo của cùng một sự kiện, X-Webhook-Attempt chứa số lần thông báo và X-Webhook-Timestamp chứa Unix timestamp theo giây. Các header phụ này không tham gia chữ ký.
Chính sách thông báo: tối đa 5 lần. Lần đầu gửi ngay; nếu chưa được xác nhận, các lần tiếp theo gửi sau 1, 3, 5 và 15 phút, tương ứng phút 0, 1, 4, 9 và 24 kể từ sự kiện. Sau lần thứ năm kết quả là FAIL và thông báo thủ công không vượt giới hạn.
Xác nhận: chỉ dừng thông báo khi HTTP là 2xx và nội dung phản hồi sau khi trim chính xác là SUCCESS. Xác minh chữ ký và lưu idempotent theo eventId. Webhook không thay thế API truy vấn đơn hàng.

Trường Webhook	Kiểu	Bắt buộc	Mô tả
eventType	string	có	Loại sự kiện nghiệp vụ, giống X-Webhook-Event, ví dụ activation.sms_received.
eventId	string	có	ID sự kiện duy nhất. Bên nhận phải lưu idempotent theo trường này.
status	string	không	Trạng thái đơn sau sự kiện. Có trong các sự kiện đơn hàng.
orderNo	string	không	Mã đơn nghiệp vụ ở cấp cao nhất cho sự kiện đơn hàng, dùng để định tuyến log và cảnh báo.
occurredAt	datetime string	có	Thời điểm xảy ra sự kiện theo định dạng ISO-8601.
data.orderNo	string	có	Mã đơn OTP MangoOTP dùng tiền tố AO.
data.service	string	không	Mã dịch vụ. Có thể không có trong sự kiện thất bại.
data.country	string	không	Mã quốc gia. Có thể không có trong sự kiện thất bại.
data.phone	string	không	Số điện thoại đã cấp cho đơn OTP. Phản hồi tạo đơn đã trả về số này và Webhook SMS trả lại số đó.
data.smsCode	string	không	OTP được trích xuất từ sự kiện SMS đến.
data.smsText	string	không	Nội dung hoặc bản xem trước SMS dùng để hiển thị hay xử lý sự cố.
data.payAmount	decimal number	không	Số tiền người dùng đã trả trong sự kiện nhận SMS của đơn OTP.

Vòng đời và truy vấn

Không chỉ dựa vào mã HTTP. Hãy đọc mã nghiệp vụ và trạng thái đơn; trạng thái kết thúc không thể đảo ngược.

PENDING

Đơn đã được tạo, đang cấp số hoặc chờ kết quả rõ ràng. Không thể hủy ở trạng thái này.

ACTIVE

Số điện thoại đã được cấp và đang chờ SMS. Hãy truy vấn chi tiết đơn để lấy smsCode.

SUCCESS

Đã nhận OTP và hoàn tất đơn. Đây là trạng thái kết thúc.

TIMEOUT / FAILED / CANCELLED / BANNED

Các trạng thái kết thúc đã hoàn tiền hoặc dừng; ý nghĩa cụ thể theo tên trạng thái.

Xử lý lỗi

Lỗi nghiệp vụ trả về mã thống nhất. Ứng dụng khách nên quyết định thử lại, đổi quốc gia, nạp tiền hoặc xử lý thủ công theo mã.

Mã lỗi	Ý nghĩa	Cách xử lý đề xuất
COMMON-E001 / E002 / E003	Tham số bị thiếu, không hợp lệ hoặc ngoài phạm vi.	Kiểm tra trường bắt buộc, độ dài, độ chính xác số tiền và định dạng code.
AUTH-E001 / AUTH-E002	Thiếu hoặc sai thông tin xác thực.	Kiểm tra X-API-Key, trạng thái thu hồi, hạn dùng và danh sách IP cho phép.
ACC-E004	Số dư khả dụng không đủ.	Nạp tiền, xác nhận số dư khả dụng đã cập nhật rồi thử lại.
OTP-E006 / SMS-E003	Lựa chọn này hiện không có hàng.	Thử quốc gia/dịch vụ khác hoặc thử lại sau.
ORD-E001 / ORD-E003 / ORD-E005	Không tìm thấy đơn hoặc trạng thái hiện tại không cho phép thao tác.	Làm mới trạng thái đơn trước khi quyết định bước tiếp theo.
ORD-E004	sellPrice hoặc giới hạn giá chấp nhận không hợp lệ.	Lấy giá mới và gửi sellPrice; chỉ gửi maxSellPrice khi chấp nhận biến động giá.
SMS-E001 / SMS-E004	Dịch vụ số tạm thời không khả dụng.	Trước tiên hãy tra cứu theo mã đơn nghiệp vụ. Chỉ thử lại sau khi có thất bại rõ ràng; liên hệ hỗ trợ nếu kết quả vẫn chưa xác định.

speed

Giới hạn tốc độ và tần suất truy vấn

Giới hạn theo khóa API: rateLimitQps được cấu hình khi tạo khóa. Giá trị mặc định là 5 QPS; giới hạn tối đa hiện tại được hiển thị trên trang tạo khóa API trong cổng USER.
Giới hạn cửa sổ nền tảng: nếu không có quy tắc riêng, GET mặc định 300 yêu cầu/phút và non-GET mặc định 30 yêu cầu/phút. Khi vượt giới hạn trả HTTP 429 và COMMON-E429.
Tiêu đề HTTP: phản hồi bị giới hạn có X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Ứng dụng khách nên giãn thời gian gửi lại theo các tiêu đề này.
Truy vấn giá trả về giá Catalog và tồn kho ước tính hiện tại mà không có thời hạn; khi tạo đơn hệ thống luôn đọc lại giá và khả năng bán hiện tại.
Truy vấn định kỳ đơn OTP: truy vấn cùng một đơn mỗi 5-10 giây. Truy vấn nhanh hơn khi ACTIVE không làm SMS đến sớm hơn và tăng nguy cơ bị giới hạn.