Tạo giao dịch

Mở một giao dịch FaceAuthen và trả về JWT token mà Mobile SDK dùng để xác thực. Nó cũng cố định level challenge, các sanity option mà bước xác minh sẽ chạy, và liệu flash liveness có bắt buộc hay không.

Endpoint

POST /v1/create_transaction
Content-Type: application/json

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "level": 0,
  "sanity_options": {
    "mask_check": true,
    "glasses_check": false
  },
  "enable_flash_liveness": false
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
user_id	string	Có	—	User ID.
ref_id	string	Có	—	ID tham chiếu giao dịch.
level	integer	Không	0	Cấp độ challenge. Được kiểm tra theo cấu hình challenge của tenant — không được lớn hơn số cấp độ verdict đã cấu hình. Cấp độ càng cao yêu cầu xác minh khuôn mặt càng nghiêm ngặt.
sanity_options	object	Không	—	Các tùy chọn bật/tắt theo từng lệnh gọi, chọn những sanity check nào bước xác minh sẽ chạy. Các key được lọc theo allow-list của server; key không có trong danh sách sẽ bị bỏ qua.
enable_flash_liveness	boolean	Không	false	Khi là true và tenant đã cấu hình các màu flash-liveness, server tạo một chuỗi màu xáo trộn và lưu nó vào giao dịch cho bước xác minh. Bị bỏ qua âm thầm khi tenant chưa cấu hình màu nào.

Các key của sanity_options

Các key được cho phép, mỗi key là một boolean:

Trường	Kiểu	Mô tả
image_type	bool	Kiểm tra ảnh đầu vào có đúng loại cho luồng này không.
occlusion_check	bool	Kiểm tra khuôn mặt không bị che khuất.
eyes_check	bool	Kiểm tra mắt đang mở và có thể nhìn thấy.
mask_check	bool	Kiểm tra khẩu trang trên mặt.
glasses_check	bool	Kiểm tra kính đeo mắt.
light_quality	bool	Kiểm tra chất lượng ánh sáng.
deepfake_check	bool	Kiểm tra khuôn mặt tổng hợp hoặc được tạo ra.
supported_selfie	bool	Kiểm tra việc chụp selfie qua một bề mặt khác.
naked	bool	Kiểm tra nội dung khỏa thân.
tattoo	bool	Kiểm tra hình xăm.

Header:

Header	Bắt buộc	Mô tả
App-Id	Không	App-Id mà giao dịch được giới hạn phạm vi theo đó; chọn cấu hình riêng của app cho challenge và flash liveness. Mặc định là default nếu bỏ qua.

Trả về: CreateTransactionResponse

INFO

Các key sanity_options không được nhận diện sẽ bị bỏ qua âm thầm thay vì bị từ chối. Một lỗi gõ sai nghĩa là kiểm tra bạn muốn chạy đơn giản là không bao giờ chạy — hãy đối chiếu với allow-list ở trên thay vì giả định một key gõ sai sẽ báo lỗi.

Ví dụ request

curl --location '<BASE_URL>/v1/create_transaction' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'App-Id: <APP_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "user_00000001",
    "ref_id": "ref_00000001",
    "level": 0,
    "sanity_options": {
      "mask_check": true,
      "glasses_check": false
    },
    "enable_flash_liveness": false
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "Success",
  "data": {
    "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1",
    "transaction": {
      "id": "85712834-558f-4d9b-81bd-a2ab3b9a3aad",
      "ref_id": "ref_00000001",
      "user_id": "user_00000001",
      "status": "NOT_VERIFIED",
      "token": "<JWT_TOKEN>",
      "level": 0
    }
  },
  "errors": []
}

Trường	Kiểu	Mô tả
success	boolean	Cuộc gọi API có thành công hay không.
code	integer	Response code — 0 khi thành công.
message	string	Thông báo response.
data.request_id	string	Request ID (UUID) để theo dõi.
data.transaction.id	string	Transaction ID (UUID).
data.transaction.ref_id	string	ID tham chiếu được cung cấp trong request.
data.transaction.user_id	string	User ID được cung cấp trong request.
data.transaction.status	string	Trạng thái giao dịch, ví dụ NOT_VERIFIED.
data.transaction.token	string	JWT token cho giao dịch.
data.transaction.level	integer	Cấp độ challenge của giao dịch.
errors[].code	string	Định danh mã lỗi.
errors[].message	string	Thông báo lỗi.
errors[].detail	object	Chi tiết lỗi bổ sung, có thể bao gồm tên trường.

HTTP status luôn là 200 bất cứ khi nào request được xử lý, dù thành công hay không.

Lưu ý giao dịch nằm lồng trong data.transaction ở đây, khác với các endpoint create của eKYC và NFC vốn trả về nó phẳng ngay trong data.

Response lỗi

{
  "success": false,
  "code": 4001000,
  "message": "Input parameter violates a constraint.",
  "data": {
    "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1"
  },
  "errors": [
    {
      "code": "invalid_parameter_exception",
      "message": "Input parameter violates a constraint.",
      "detail": {
        "reason": "Invalid challenge level."
      }
    }
  ]
}

Lỗi

Mã	Thông báo
2001010	Không tìm thấy Access ID trong hệ thống.
2001020	Lock giao dịch thất bại.
2001021	Request giao dịch không hợp lệ.
2002206	Hồ sơ người dùng đã bị khóa.
401100	Hành động không được phép. Bạn không có quyền thực hiện hành động này.
4001000	Tham số đầu vào vi phạm một ràng buộc.
4001001	Header X-TV-Timestamp đã hết hạn. Vui lòng cung cấp một timestamp mới hơn.
4041002	Không tìm thấy hồ sơ của người dùng.
5001000	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã	Mô tả
access_id_not_found	Không tìm thấy Access ID trong hệ thống.
transaction_lock_failed	Lock giao dịch thất bại.
transaction_invalid_request	Request giao dịch không hợp lệ.
access_denied_exception	Hành động không được phép. Bạn không có quyền thực hiện hành động này.
user_profile_not_found_exception	Không tìm thấy hồ sơ của người dùng.
user_profile_locked	Hồ sơ người dùng đã bị khóa.
invalid_parameter_exception	Tham số đầu vào vi phạm một ràng buộc.
request_time_too_skewed	Header X-TV-Timestamp đã hết hạn. Vui lòng cung cấp một timestamp mới hơn.
internal_server_error	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Một 4041002 nghĩa là chưa có hồ sơ nào tồn tại — hãy gọi Đăng ký khuôn mặt trước. Một 2002206 nghĩa là hồ sơ đã bị khóa; xem Mở khóa hồ sơ.

Bước tiếp theo

• Ký request — cách SDK ký với token được trả về ở đây
• Xác minh Face Authen — lệnh gọi tiếp theo của SDK