Skip to content

Submit User KYC ​

POST /openapi/v1/users/kyc
ItemValue
HTTP methodPOST
Request path/openapi/v1/users/kyc
Request typeapplication/json

Request parameters ​

FieldTypeRequiredDescription
requestNostringConditionalRequired for supplements; optional for new applications. 1–64 letters, digits, underscores or hyphens, unique within the tenant's KYC requests. Use the same number for unchanged retries; a new submission uses a new number.
originalRecordNostringConditionalRequired for supplements: latest platform material-record number returned by Get KYC Supplement Information. Omit for a first or new application after failure.
expectedVersioninteger(int64)ConditionalRequired for supplements: non-negative business version returned by the query. Return unchanged with originalRecordNo; omit for a new application. Normal unchanged-state synchronization does not expire it.
emailstringYesUser email address, used according to the existing API contract.
namestringYesFull name.
birthdaystringYesDate of birth, in the format yyyy-MM-dd.
documentTypestringYesDocument type: passport, id_card, or driver_license.
documentNumberstringYesDocument number.
documentCountrystringYesDocument issuing country or region, as a two-letter code such as HK.
documentExpiryDatestringConditionalDocument expiry date, in the format yyyy-MM-dd; provide either this or documentPermanentlyValid.
documentPermanentlyValidbooleanConditionalPass true for a permanently valid document; provide either this or documentExpiryDate. An expiry date is required when passing false.
frontImageUrlstringYesURL returned after uploading the front image of the document.
backImageUrlstringConditionalURL returned after uploading the back image of the document; required for id_card and driver_license, optional for passport.
selfieImageUrlstringYesURL returned after uploading the identity selfie image.
phoneCountryCodestringYesPhone country calling code, such as +852.
phoneNumberstringYesDigits only, 4 to 20 digits.
genderstringYesGender: male or female.
annualIncomestringYesAnnual income range: <20000, 20000-50000, 50000-200000, 200000-500000, or >500000.
occupationstringYesOccupation.
positionstringYesPosition.
nationalitystringYesNationality, as a two-letter country or region code.
contactAddressstringYesContact address.
supportingDocumentsarrayConditionalRequired for non-HK users, with 1 to 10 items; optional for HK users. See the table below.
memberIdstringYesPlatform member ID, used only to identify the user on the platform; not sent to the service provider.

supportingDocuments items ​

FieldTypeRequiredDescription
documentTypestringYesUse a supporting-proof type from Upload KYC Images, consistent with the upload's supportingDocumentType. Provide PDF or images as required by that type. Material categories do not guarantee acceptance by every card product.
fileUrlstringYesStable url returned by the supporting-proof upload; do not use the temporary previewUrl.

Upload supporting proof with purpose=SUPPORTING_DOCUMENT and the matching supportingDocumentType. Upload travel-permit sides separately, then include both TRAVEL_PERMIT_FRONT and TRAVEL_PERMIT_BACK in this array. Each side accepts images or PDF.

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.

An expiry date together with documentPermanentlyValid: true, or neither, is rejected. Passing false with an expiry date satisfies this selection check.

Upload primary documents, selfies, and supporting proof through Upload KYC Images and obtain their url values before submitting KYC. Primary documents and selfies accept JPG/JPEG/PNG only; supporting-proof formats depend on the material type.

Request example ​

json
{
  "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"
}

Supplement Submission ​

A supplement uses this same POST endpoint; there is no separate supplement POST route.

  1. Call Get KYC Supplement Information with email and cardTypeId.
  2. Continue only if allowed=true. Use the original details to prepare the complete KYC payload, preserving lockedFields and the original email.
  3. Include originalRecordNo and expectedVersion exactly as returned, plus a new requestNo.
  4. Check both the outer code and data.submissionStatus; successful request processing is not approval.

A first application or a new application after confirmed failure omits originalRecordNo and expectedVersion. A requestNo is recommended for safe retry. New applications after failure require the original fee to be fully released and are charged at the current applicable KYC price. Supplements within the same application reuse the original fee and do not charge again.

Complete Supplement Request Example ​

This example uses a Mastercard Hong Kong USD card. All values are synthetic. Replace the user ID, file URLs, and supplement basis with actual values. V1 retains its existing routing for this product.

http
POST /openapi/v1/users/kyc
Content-Type: application/json
json
{
  "email": "user@example.com",
  "memberId": "member-123",
  "requestNo": "KYC_SUPPLEMENT_20261104_001",
  "originalRecordNo": "KYC_RECORD_002",
  "expectedVersion": 3,
  "name": "Test User",
  "birthday": "1990-01-01",
  "documentType": "passport",
  "documentNumber": "SYNTHETIC_ONLY",
  "documentCountry": "HK",
  "documentExpiryDate": "2030-12-31",
  "frontImageUrl": "https://files.example.com/kyc/front.jpg",
  "selfieImageUrl": "https://files.example.com/kyc/selfie.jpg",
  "phoneCountryCode": "+852",
  "phoneNumber": "00000000",
  "gender": "male",
  "annualIncome": "50000-200000",
  "occupation": "Engineer",
  "position": "Company Owner",
  "nationality": "HK",
  "contactAddress": "Updated contact address",
  "supportingDocuments": []
}

Business Errors ​

The numbers below are response-body code values, not guaranteed HTTP statuses. The identifier appears as a prefix in msg; there is no separate errorCode field. Use the existing Common Responses envelope.

Body codemsg prefixAction
400KYC_SUPPLEMENT_INVALIDInclude all required supplement fields; expectedVersion must be non-negative and cannot appear without originalRecordNo.
400KYC_REQUEST_INVALIDCorrect the request-number format.
400KYC_SUPPLEMENT_FIELD_DENIEDRestore locked fields and preserve the original email. An email-change rejection can use descriptive text without this prefix.
409KYC_REQUEST_CONFLICTA request number was reused with different material/request content. Preserve the original request for retries; use a new number only for an intended new submission, subject to current eligibility.
409KYC_VERSION_CONFLICTFetch supplement information again; the original material record or business version is stale.
409KYC_SUPPLEMENT_DENIEDSupplementation is currently ineligible; read the returned reason and resolve the state or fee condition first.
409KYC_SUPPLEMENT_STATUS_UNKNOWNCurrent provider state could not be confirmed. Wait for platform synchronization/recovery before trying again.
409KYC_SUPPLEMENT_STATE_CHANGEDCurrent provider state no longer allows supplementation. Resolve the state and fetch supplement information again.
422KYC_SUPPLEMENT_DISABLEDThe platform has disabled supplementation. Do not automatically retry.

Example of a stale supplement basis:

json
{"code":409,"msg":"KYC_VERSION_CONFLICT: 申请已更新,请刷新补件资格后重试","data":null}

Acceptance and Retry ​

ResultNext action
submissionStatus=ACCEPTEDThe material was accepted. Query review status; do not generate another request number to submit it again.
submissionStatus=REJECTEDThe submission was explicitly not accepted. Fetch supplement information again because a new platform material record may already exist; correct details, confirm eligibility, and submit with a new request number.
Timeout, gateway/server error, or submissionStatus=UNKNOWNPreserve the original payload and requestNo. Replay unchanged content under the same number: if a result was already saved, it is returned without creating another material record or fee and may still be UNKNOWN. A replay does not force another provider submission.
Material needs editing after an unknown resultUse a new number for changed content and let the backend validate the current application. If the previous result remains unresolved, the new submission is rejected; changing numbers does not bypass that protection.
Record/version conflictRetain editable drafts, fetch current supplement information, restore locked values, and confirm allowed=true before submitting again. No need to discard the draft.
allowed=false or supplementation disabledStop submissions until the required condition is resolved. Repeated GET queries do not force provider synchronization.

Ordinary synchronization with unchanged review basis does not invalidate expectedVersion. Treat it as an opaque business version, not a sync counter. Every new material record has its own originalRecordNo; numeric versions alone are insufficient.

Response data ​

FieldTypeDescription
successboolean/nullSubmission acceptance: true for ACCEPTED, false for REJECTED, and null when UNKNOWN. This is not KYC approval.
codestring/nullBusiness response code; may be absent when no definite result was received. Independent of the outer response code.
messagestring/nullBusiness response message; read together with submissionStatus.
externalUserIdstring/nullExternal user ID; may be absent when the service provider has not returned it.
kycRecordIdstring/nullKYC query identifier returned by the service provider; may be absent. Not the platform supplement material-record number originalRecordNo.
statusstring/nullFuturePay unified primary KYC status: NOT_SUBMITTED, PENDING (legacy), PENDING_APPROVAL, APPROVED, or REJECTED.
subStatusstring/nullRaw KYC sub-status from the external provider; additional values may be introduced. Currently known values are not_submitted, pending_approval, approved, rejected.
cardAccountIdstring/nullExternal provider card account ID; null when not returned by the provider.
submissionStatusstring/nullSubmission outcome: ACCEPTED, REJECTED, UNKNOWN; may be null for queries. Independent of approval.
channelStatusstring/nullLast confirmed certification status for the current channel; an unaccepted attempt does not overwrite it.

success describes request processing, not KYC approval. submissionStatus describes submission acceptance; channelStatus describes certification for the selected channel. In V2, status is the aggregate user status and must not be used to infer approval of every channel.

Empty optional values may be null or omitted. When submissionStatus=UNKNOWN, success is null and identifiers may be absent; follow the retry rules above. Historical records may retain FAILED, which represents a processing failure and does not itself prove review rejection.