Xác minh OTP

Xác minh một OTP cơ bản (basic) hoặc nâng cao (advance). Cả hai dùng chung một endpoint, được phân biệt bằng otp_type — advance còn yêu cầu thêm transaction_id mà mã đã được gắn với.

Endpoint

http

POST /api/v1/saas-sotp/validate-sotp
Content-Type: application/json

OTP cơ bản

Xác minh một mã được tạo chỉ từ khóa bí mật của client và thời gian, không có ngữ cảnh giao dịch nào.

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`partner_id`	string	Có	—	Partner ID.
`partner_key`	string	Có	—	Partner key.
`token`	string	Có	—	Token đăng ký được tạo bởi Đăng ký.
`app_id`	string	Có	—	App ID, dùng để tracking.
`otp`	string	Có	—	OTP được SDK tạo từ `key` do Kích hoạt trả về.
`otp_type`	string	Có	—	`basic` khi xác minh một Soft OTP cơ bản.

bash

curl --location --request POST '<BASE_URL>/saas-sotp/validate-sotp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "token": "{{token}}",
    "app_id": "{{app_id}}",
    "otp": "123456",
    "otp_type": "basic"
  }'

OTP nâng cao

Xác minh một mã đã được gắn với một giao dịch thông qua khóa challenge của giao dịch đó.

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`partner_id`	string	Có	—	Partner ID.
`partner_key`	string	Có	—	Partner key.
`token`	string	Có	—	Token đăng ký được tạo bởi Đăng ký.
`app_id`	string	Có	—	App ID, dùng để tracking.
`otp`	string	Có	—	OTP được SDK tạo từ `key` do Kích hoạt trả về.
`otp_type`	string	Có	—	`advance` khi xác minh một Soft OTP nâng cao.
`transaction_id`	string	Có	—	ID giao dịch duy nhất phía partner.

bash

curl --location --request POST '<BASE_URL>/saas-sotp/validate-sotp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "token": "{{token}}",
    "app_id": "{{app_id}}",
    "transaction_id": "{{transaction_id}}",
    "otp": "123456",
    "otp_type": "advance"
  }'

WARNING

Hãy dùng advance cho bất kỳ điều gì liên quan đến việc chuyển tiền. Một OTP basic chỉ chứng minh rằng người dùng đang giữ thiết bị — nó không gắn với số tiền hay người nhận, nên một mã bị lấy được trong một hành động có thể dùng để xác thực cho một hành động khác.

Response

json

{
  "success": true,
  "code": 1,
  "message": "Success"
}

Trường	Kiểu	Mô tả
`success`	bool	Trạng thái của request.
`code`	int	status code — `1` nghĩa là OTP hợp lệ.
`message`	string	Thông báo trạng thái hoặc lỗi.

Hãy xác minh giá trị này ở backend của bạn và chuyển nó thành status code riêng của bạn trước khi trả bất kỳ thứ gì về cho ứng dụng.

Lỗi

Mã	Mô tả
`103`	Thông tin Partner không chính xác — Partner details are incorrect.
`121`	Yêu cầu vượt giới hạn. Vui lòng thử lại sau ít phút. — Request limit exceeded.
`123`	Yêu cầu vượt giới hạn. Vui lòng thử lại sau ít phút. — Request limit exceeded.
`124`	OTP không hợp lệ — Invalid OTP.
`126`	Có lỗi xảy ra vui lòng thử lại — An error occurred, please retry.
`129`	Token không hợp lệ — Invalid token.
`190108`	Tài khoản chưa hoạt động — Account not activated.
`190203`	Không tìm thấy transaction — Transaction not found. Chỉ áp dụng cho OTP nâng cao.

Nếu người dùng liên tục nhận 124 dù tin rằng mã của mình đúng, nguyên nhân thường là lệch đồng hồ, không phải mã sai — hãy gọi Đồng bộ thời gian.

Bước tiếp theo

Đồng bộ thời gian — chẩn đoán các lỗi OTP không hợp lệ lặp lại
Tạo giao dịch — cấp khóa challenge mà một OTP nâng cao cần

Xác minh OTP ​

Endpoint ​

OTP cơ bản ​

OTP nâng cao ​

Response ​

Lỗi ​