Submit User KYC

POST /openapi/v1/users/kyc

Item	Value
HTTP method	POST
Request path	/openapi/v1/users/kyc
Request type	application/json

Request parameters

Field	Type	Required	Description
email	string	Yes	User email address, used according to the existing API contract.
name	string	Yes	Full name.
birthday	string	Yes	Date of birth, in the format yyyy-MM-dd.
documentType	string	Yes	Document type: passport, id_card, or driver_license.
documentNumber	string	Yes	Document number.
documentCountry	string	Yes	Document issuing country or region, as a two-letter code such as HK.
documentExpiryDate	string	Conditional	Document expiry date, in the format yyyy-MM-dd; provide either this or documentPermanentlyValid.
documentPermanentlyValid	boolean	Conditional	Pass true for a permanently valid document; provide either this or documentExpiryDate. Passing false is not equivalent to omitting the field.
frontImageUrl	string	Yes	URL returned after uploading the front image of the document.
backImageUrl	string	Conditional	URL returned after uploading the back image of the document; required for id_card and driver_license, optional for passport.
selfieImageUrl	string	Yes	URL returned after uploading the identity selfie image.
phoneCountryCode	string	Yes	Phone country calling code, such as +852.
phoneNumber	string	Yes	Digits only, 4 to 20 digits.
gender	string	Yes	Gender: male or female.
annualIncome	string	Yes	Annual income range: <20000, 20000-50000, 50000-200000, 200000-500000, or >500000.
occupation	string	Yes	Occupation.
position	string	Yes	Position.
nationality	string	Yes	Nationality, as a two-letter country or region code.
contactAddress	string	Yes	Contact address.
supportingDocuments	array	Conditional	Required for non-HK users, with 1 to 10 items; optional for HK users. See the table below.
memberId	string	Yes	Platform member ID, used only to identify the user on the platform; not sent to CPlus.

supportingDocuments items

Field	Type	Required	Description
documentType	string	Yes	UTILITY_BILL, TENANCY_AGREEMENT, ADDRESS_PROOF, BANK_STATEMENT, TRAVEL_PERMIT_FRONT, TRAVEL_PERMIT_BACK, or PROOF_OF_VISIT.
fileUrl	string	Yes	URL returned after uploading a supporting document.

Provide exactly one of the expiry fields:

• For a document with an expiry date, pass documentExpiryDate and omit documentPermanentlyValid.
• For a permanently valid document, pass documentPermanentlyValid: true and omit documentExpiryDate.

Requests that provide both fields, omit both fields, or pass documentPermanentlyValid: false are rejected.

Upload images through the existing KYC image upload endpoint to obtain their URLs before submitting KYC.

Request example

{
  "email": "user@example.com",
  "name": "Test User",
  "birthday": "1990-01-01",
  "documentType": "passport",
  "documentNumber": "P1234567",
  "documentCountry": "HK",
  "documentExpiryDate": "2030-12-31",
  "frontImageUrl": "https://example.com/front.jpg",
  "selfieImageUrl": "https://example.com/selfie.jpg",
  "phoneCountryCode": "+852",
  "phoneNumber": "91234567",
  "gender": "male",
  "annualIncome": "50000-200000",
  "occupation": "Engineer",
  "position": "Senior Engineer",
  "nationality": "HK",
  "contactAddress": "Hong Kong",
  "memberId": "member-123"
}

Response data

Field	Type	Description
success	boolean	Whether processing succeeded.
code	string	Platform response code.
message	string	Platform response message.
externalUserId	string	External user ID.
kycRecordId	string	KYC record ID.
status	string/null	FuturePay unified primary KYC status: PENDING, PENDING_APPROVAL, APPROVED, or REJECTED.
subStatus	string/null	Raw KYC sub-status from the external provider; additional values may be introduced. Currently known values are not_submitted, pending_approval, approved, rejected.
cardAccountId	string/null	External provider card account ID; null when not returned by the provider.