Tạo giao dịch

Mở một giao dịch eKYC cho một người dùng và trả về JWT token mà Mobile SDK dùng để xác thực. Đây là lệnh gọi đầu tiên trong một phiên eKYC do SDK điều khiển.

Endpoint

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

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "level": 0
}

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 do bạn tạo và quản lý.
level	int	Không	0	Cấp độ challenge. Cấp độ càng cao yêu cầu kiểm tra càng nghiêm ngặt.

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 đó. Mặc định là default nếu bỏ qua.

Trả về: CreateTransactionResponse

Ví dụ request

curl --location '<BASE_URL>/v1/create_ekyc_transaction' \
  --header '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
  }'

Response

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

Trường	Kiểu	Mô tả
data.id	string	ID duy nhất của giao dịch.
data.ref_id	string	ID tham chiếu giao dịch bạn đã cung cấp.
data.user_id	string	User ID.
data.status	string	NOT_VERIFIED, VERIFIED hoặc EXPIRED.
data.token	string	JWT token mà Mobile SDK dùng để xác thực với server.
errors	array	Chi tiết từng lỗi. Rỗng khi thành công.
success	bool	Cuộc gọi có thành công hay không.
code	int	status code dạng số — 0 khi thành công.

INFO

Response trả về user_id, khớp với request. Hãy liên hệ đội CAKE nếu bạn thấy document_id ở vị trí đó.

WARNING

token chỉ có hiệu lực trong phạm vi một giao dịch và sẽ hết hạn. Hãy chuyển nó cho SDK qua kênh xác thực riêng của bạn và không bao giờ ghi log — Access Key phải luôn ở lại phía backend của bạn.

Lỗi

Mã	Thông báo
2001010	Không tìm thấy Access ID.
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	Bạn không được phép 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, cần một cái mới hơn.
5001000	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã	Mô tả
access_id_not_found	API key không đú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	Bạn không được phép 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.
internal_server_error	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Tải ảnh lên — lệnh gọi tiếp theo ngay khi SDK đang giữ một token
• Lấy giao dịch — poll trạng thái giao dịch
• Xác minh khóa xác thực giao dịch — đóng giao dịch