KYC API Docs

Tài liệu KYC Service REST API

Được tổng hợp từ các REST controller thực tế trong `workspace/service/service/kycService`, bao gồm API người dùng, liveness và xét duyệt back-office.

Quay lại trang AMLLiên hệ tích hợp
Base path/api/web/kycService
Response envelopeApiResponse { code, message, data }
Định dạng uploadmultipart/form-data
Admin namespace/admin/kyc
Scanned Source

Tổng quan tích hợp từ controller thực tế

Trang này được dựng từ route thật của `ApiKycController`, `ApiKycLivenessController` và `AdminKycController`, không phải mô tả khái quát chung.

01

Tạo hồ sơ KYC

Bắt đầu bằng `/submit` để lấy `profileId`, sau đó dùng ID này cho upload tài liệu, liveness và truy vấn trạng thái.

02

Gửi dữ liệu giấy tờ

Nếu đã có hạ tầng lưu file thì dùng `/document`; luồng khuyến nghị là `/document/upload` để upload ảnh và chạy OCR cùng lúc.

03

Xác nhận và nộp duyệt

Dùng `/document/confirm` để người dùng xác nhận dữ liệu OCR, rồi `/document/submit` để chuyển sang auto-approve hoặc manual review.

04

Liveness và trạng thái cuối

Luồng liveness gồm `/liveness/start` và `/liveness/verify`, còn trạng thái tổng thể lấy qua `/status/`.

Nguồn quét: /workspace/service/service/kycService/src/main/java/com/sargia/finger/kycService/rest

Trong service còn có nhóm endpoint mirror tại `/api/web/kycService/list`, `/detail/`, `/status/update`, trong khi namespace back-office chính là `/admin/kyc`.

Envelope

Cấu trúc phản hồi dùng chung

Các controller được quét đều trả về `ApiResponse`, trong đó dữ liệu nghiệp vụ thực tế nằm trong `data`.

TrườngKiểuVí dụ
codenumber0 là thành công, giá trị khác 0 là lỗi hoặc business exception
messagestringThông điệp như success, query success, Document uploaded successfully
dataobjectPayload như profileId, status, detail hoặc list
Core Web API

API phía người dùng

Tương ứng với `ApiKycController`, bao gồm tạo hồ sơ, upload giấy tờ, xác nhận trường, nộp duyệt và truy vấn trạng thái.

POST
PublicRecommended

Create profile

/api/web/kycService/submit

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

TrườngKiểuBắt buộcVị tríVí dụ
userIdstringCóbodyuser_10001
countrystringCóbodySG

Phản hồi chính

profileId

Ghi chú

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

Upload document metadata

/api/web/kycService/document

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCóbodyprofile_123456
docTypestringCóbodyPASSPORT
docNumberstringKhôngbodyE12345678
frontImageUrlstringCóbodyhttps://cdn.example/front.jpg
backImageUrlstringKhôngbodyhttps://cdn.example/back.jpg
expiryDatedateKhôngbody2030-12-31
issueCountrystringKhôngbodySG

Phản hồi chính

codemessage

Ghi chú

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

Upload and verify document

/api/web/kycService/document/upload

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCómultipartprofile_123456
docTypestringCómultipartID_CARD
countrystringCómultipartSG
frontImagefileCómultipartid-front.jpg
backImagefileKhôngmultipartid-back.jpg

Phản hồi chính

documentIdverifiednameidNumberbirthDateexpiryDatefrontQualityScorebackQualityScoreerrors

Ghi chú

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

Confirm extracted fields

/api/web/kycService/document/confirm

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

TrườngKiểuBắt buộcVị tríVí dụ
documentIdnumberCóquery123456789
namestringKhôngbodyAlex Tan
idNumberstringKhôngbodyS1234567A
birthDatedateKhôngbody1990-01-01
expiryDatedateKhôngbody2030-12-31
issuerstringKhôngbodyICA Singapore
nationalitystringKhôngbodySGP
userModifiedbooleanKhôngbodytrue

Phản hồi chính

documentIdstatusverifiedextractedInfo

Ghi chú

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

Submit document for review

/api/web/kycService/document/submit

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

TrườngKiểuBắt buộcVị tríVí dụ
documentIdnumberCóquery123456789

Phản hồi chính

documentIdstatusverifiederrors

Ghi chú

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

Get verification status

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

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCópathprofile_123456

Phản hồi chính

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

Ghi chú

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

Liveness callback

/api/web/kycService/callback/liveness

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCóbodyprofile_123456
sessionIdstringKhôngbody550e8400-e29b-41d4-a716-446655440000
confidencenumberKhôngbody96.2
resultstringKhôngbodysuccess
errorMessagestringKhôngbodytimeout

Phản hồi chính

codemessage

Ghi chú

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

API xác minh liveness

Tương ứng với `ApiKycLivenessController`, gồm tạo session, xác minh video và truy vấn session.

POST
PublicRecommended

Start liveness session

/api/web/kycService/liveness/start

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCóqueryprofile_123456

Phản hồi chính

sessionIdactionsexpireTimetimeout

Ghi chú

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

Verify liveness videos

/api/web/kycService/liveness/verify

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

TrườngKiểuBắt buộcVị tríVí dụ
sessionIdstringCómultipart550e8400-e29b-41d4-a716-446655440000
profileIdstringCómultipartprofile_123456
video1fileCómultipartblink.mp4
video2fileCómultipartsmile.mp4
video3fileCómultipartturn-left.mp4

Phản hồi chính

verifiedconfidencecompletedActionsfailedActionsmessage

Ghi chú

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

Get liveness session

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

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

TrườngKiểuBắt buộcVị tríVí dụ
sessionIdstringCópath550e8400-e29b-41d4-a716-446655440000

Phản hồi chính

sessionIdprofileIdactionsexpireTimestatuscreateTime

Ghi chú

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

API xét duyệt back-office

Tương ứng với `AdminKycController`, gồm danh sách, chi tiết và cập nhật trạng thái xét duyệt.

POST
Admin

List KYC records

/admin/kyc/list

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdsarray<string>Khôngbody["profile_123","profile_456"]
pagenumberKhôngbody1
limitnumberKhôngbody20

Phản hồi chính

totalpagescurrentsizerecords

Ghi chú

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

Get KYC detail

/admin/kyc/detail/{profileId}

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCópathprofile_123456

Phản hồi chính

detail

Ghi chú

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

Update review status

/admin/kyc/update-status

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

TrườngKiểuBắt buộcVị tríVí dụ
profileIdstringCóbodyprofile_123456
statusstringCóbody2
remarkstringKhôngbodyManual review passed

Phản hồi chính

codemessage

Ghi chú

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

Tuyên bố miễn trừ trách nhiệm:

Finger Trader là một nền tảng phần mềm hạ tầng được thiết kế cho các tổ chức, cung cấp năng lực hỗ trợ kỹ thuật ở tầng hệ thống và dữ liệu, và không liên quan đến dịch vụ tài chính, tư vấn đầu tư, nghiệp vụ môi giới hay thực thi giao dịch.

Thông tin được công bố trên website chỉ nhằm mục đích tham khảo chung, không dành riêng cho bất kỳ trader nào và không cấu thành tư vấn tài chính.

Trước khi đưa ra bất kỳ quyết định đầu tư nào dựa trên các thông tin đó, bạn nên tìm kiếm lời khuyên từ các chuyên gia chứng khoán đủ điều kiện và được cấp phép, đồng thời thực hiện thẩm định đầy đủ.

Mọi thông tin do Finger Trader cung cấp không nên được xem là tư vấn đầu tư, lời mời mua hoặc bán, đề nghị, khuyến nghị, chứng thực hay tài trợ cho bất kỳ chứng khoán, công ty hoặc quỹ nào.

Finger Trader không chịu trách nhiệm đối với bất kỳ quyết định đầu tư nào mà bạn đưa ra dựa trên các thông tin đó.

Mọi quyết định đầu tư và nghiên cứu liên quan hoàn toàn thuộc trách nhiệm của bạn.

Finger là công ty phát triển phần mềm và không cung cấp bất kỳ hình thức đầu tư hay môi giới nào.

© 2026 Sargia Inc.

All rights reserved.

Address: 〒560-0011 Osaka, Toyonaka, Uenonishi, 3-chōme−2−50

Post code: 560-0011

Chính sách quyền riêng tư ‧ Chính sách Cookies