What is Finger Trader?

Finger Trader is a SaaS trading platform for brokers and market makers, offering real-time data, multi-asset trading, community, and referral tools.

Who can use Finger Trader?

Finger Trader is designed for brokers, institutions, market makers, and individual traders seeking a seamless trading ecosystem.

KYC API Docs

KYC Service REST API 文檔

根據 workspace/service 下 kycService 的實際 REST 控制器整理，涵蓋前台接入、活體檢測與後台審核接口。

返回 AML 頁面聯絡接入

主路徑/api/web/kycService

返回封裝ApiResponse { code, message, data }

上傳格式multipart/form-data

後台命名空間/admin/kyc

Scanned Source

基於真實控制器整理的接入概覽

本頁不是手寫宣傳文案，而是從 `ApiKycController`、`ApiKycLivenessController` 與 `AdminKycController` 的實際路由整理出來的站內文檔頁。

建立 KYC 檔案

先呼叫 `/submit` 建立 `profileId`，後續證件、活體與狀態查詢都圍繞這個主鍵進行。

提交證件資料

已有文件系統可走 `/document`，標準接入建議直接使用 `/document/upload` 完成圖片上傳、OCR 與質量校驗。

確認並送審

用 `/document/confirm` 讓使用者核對欄位，再由 `/document/submit` 決定自動通過或轉人工審核。

活體與最終狀態

活體流程由 `/liveness/start` 和 `/liveness/verify` 組成，整體結果最終可透過 `/status/` 拉取。

掃描來源： /workspace/service/service/kycService/src/main/java/com/sargia/finger/kycService/rest

控制器中同時存在一組 `/api/web/kycService/list`、`/detail/`、`/status/update` 的後台鏡像接口；正式後台命名空間則是 `/admin/kyc`。

Envelope

統一返回結構

掃描到的控制器都使用 `ApiResponse` 包裝返回，實際業務資料放在 `data` 節點內。

字段	類型	示例
`code`	number	0 代表成功，非 0 代表失敗或業務異常
`message`	string	success、查詢成功、Document uploaded successfully 等訊息
`data`	object	具體業務資料，例如 profileId、status、detail 或 list

Core Web API

前台接入接口

對應 `ApiKycController`，覆蓋建立檔案、證件上傳、欄位確認、送審與狀態查詢。

POST

前台推薦

Create profile

/api/web/kycService/submit

Create a KYC profile and return the profileId used by all downstream calls. 建立 KYC 档案并返回后续接口共用的 profileId。

字段	類型	必填	位置	示例
`userId`	string	是	body	user_10001
`country`	string	是	body	SG

返回重點

profileId

補充說明

Returns `ApiResponse.ok().data("profileId", profileId)` on success.

POST

前台

Upload document metadata

/api/web/kycService/document

Submit document metadata with image URLs or base64 references. 提交证件元数据，适合已有文件托管链路的接入方。

字段	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`docType`	string	是	body	PASSPORT
`docNumber`	string	否	body	E12345678
`frontImageUrl`	string	是	body	https://cdn.example/front.jpg
`backImageUrl`	string	否	body	https://cdn.example/back.jpg
`expiryDate`	date	否	body	2030-12-31
`issueCountry`	string	否	body	SG

返回重點

codemessage

補充說明

The controller stores document metadata through `kycService.uploadDocument(...)`.

POST

前台推薦

Upload and verify document

/api/web/kycService/document/upload

Upload front/back images, run OCR and quality checks, and return extracted identity fields. 上传证件图片并同步返回 OCR 与质量校验结果。

字段	類型	必填	位置	示例
`profileId`	string	是	multipart	profile_123456
`docType`	string	是	multipart	ID_CARD
`country`	string	是	multipart	SG
`frontImage`	file	是	multipart	id-front.jpg
`backImage`	file	否	multipart	id-back.jpg

返回重點

documentIdverifiednameidNumberbirthDateexpiryDatefrontQualityScorebackQualityScoreerrors

補充說明

When OCR succeeds, the response includes extracted identity fields for user confirmation.
When verification fails, the controller returns `errorCode`, quality scores, and `errors`.

POST

前台

Confirm extracted fields

/api/web/kycService/document/confirm

Let the user confirm or edit OCR results before the final review step. 用户确认或修正 OCR 字段，必要时触发人工审核。

字段	類型	必填	位置	示例
`documentId`	number	是	query	123456789
`name`	string	否	body	Alex Tan
`idNumber`	string	否	body	S1234567A
`birthDate`	date	否	body	1990-01-01
`expiryDate`	date	否	body	2030-12-31
`issuer`	string	否	body	ICA Singapore
`nationality`	string	否	body	SGP
`userModified`	boolean	否	body	true

返回重點

documentIdstatusverifiedextractedInfo

補充說明

If `userModified` is true, the service message indicates the record will enter manual review.

POST

前台

Submit document for review

/api/web/kycService/document/submit

Finalize the document step after user confirmation. 完成用户确认后，正式提交证件审核并返回最终状态。

字段	類型	必填	位置	示例
`documentId`	number	是	query	123456789

返回重點

documentIdstatusverifiederrors

補充說明

The controller maps status 1/2/3 to auto-approved, manual review, and user-modified review.

GET

前台推薦

Get verification status

/api/web/kycService/status/{profileId}

Fetch the current KYC status, liveness result, and face-match information by profileId. 查询整个 KYC 档案的当前状态。

字段	類型	必填	位置	示例
`profileId`	string	是	path	profile_123456

返回重點

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

補充說明

Returns `data.status` as a `KycStatusDto` object rather than a flat primitive field.

POST

回調

Liveness callback

/api/web/kycService/callback/liveness

Server-to-server callback used to persist liveness results. 这是服务侧回调入口，不是前端页面直接调用的接口。

字段	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`sessionId`	string	否	body	550e8400-e29b-41d4-a716-446655440000
`confidence`	number	否	body	96.2
`result`	string	否	body	success
`errorMessage`	string	否	body	timeout

返回重點

codemessage

補充說明

`LivenessCallback.toEntity()` is currently a placeholder conversion in the scanned service code.

Liveness API

活體檢測接口

對應 `ApiKycLivenessController`，負責建立動作會話、提交視頻驗證與會話查詢。

POST

前台推薦

Start liveness session

/api/web/kycService/liveness/start

Create a five-minute session and return three randomized challenge actions. 创建 5 分钟有效的活体动作会话。

字段	類型	必填	位置	示例
`profileId`	string	是	query	profile_123456

返回重點

sessionIdactionsexpireTimetimeout

補充說明

The controller shuffles `LivenessActionEnum` values and returns exactly three actions.

POST

前台推薦

Verify liveness videos

/api/web/kycService/liveness/verify

Upload three challenge videos and return the aggregated liveness result. 上传三个动作视频并返回活体验证结果。

字段	類型	必填	位置	示例
`sessionId`	string	是	multipart	550e8400-e29b-41d4-a716-446655440000
`profileId`	string	是	multipart	profile_123456
`video1`	file	是	multipart	blink.mp4
`video2`	file	是	multipart	smile.mp4
`video3`	file	是	multipart	turn-left.mp4

返回重點

verifiedconfidencecompletedActionsfailedActionsmessage

補充說明

Failure uses `ApiResponse.error().code(20001)` with the liveness result still returned in `data.list`.

GET

前台

Get liveness session

/api/web/kycService/liveness/session/{sessionId}

Read the current liveness session from cache and inspect its status. 查询缓存中的活体会话状态。

字段	類型	必填	位置	示例
`sessionId`	string	是	path	550e8400-e29b-41d4-a716-446655440000

返回重點

sessionIdprofileIdactionsexpireTimestatuscreateTime

補充說明

If the session is missing or expired, the controller returns an error message instead of null data.

Admin Review API

後台審核接口

對應 `AdminKycController`，提供後台列表、詳情與審核狀態更新。

POST

後台

List KYC records

/admin/kyc/list

Query paginated KYC records for operations teams. 后台分页查询 KYC 档案列表并支持按 profileIds 过滤。

字段	類型	必填	位置	示例
`profileIds`	array<string>	否	body	["profile_123","profile_456"]
`page`	number	否	body	1
`limit`	number	否	body	20

返回重點

totalpagescurrentsizerecords

補充說明

The same list capability is also mirrored in `ApiKycController` at `/api/web/kycService/list`.

GET

後台

Get KYC detail

/admin/kyc/detail/{profileId}

Fetch the full review payload for one profile, including document, liveness, and face-match data. 获取单个 KYC 档案的完整审核详情。

字段	類型	必填	位置	示例
`profileId`	string	是	path	profile_123456

返回重點

detail

補充說明

A mirrored detail endpoint also exists at `/api/web/kycService/detail/{profileId}`.

POST

後台

Update review status

/admin/kyc/update-status

Approve, reject, or reset the KYC review state from the admin namespace. 在后台审核链路中更新 KYC 状态。

字段	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`status`	string	是	body	2
`remark`	string	否	body	Manual review passed

返回重點

codemessage

補充說明

Allowed status values in the DTO are `-1`, `0`, and `2`.
The web-controller mirror path is `/api/web/kycService/status/update`.