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 |
|---|---|---|---|
requestNo | string | Conditional | Required 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. |
originalRecordNo | string | Conditional | Required for supplements: latest platform material-record number returned by Get KYC Supplement Information. Omit for a first or new application after failure. |
expectedVersion | integer(int64) | Conditional | Required 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. |
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. An expiry date is required when passing false. |
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 the service provider. |
supportingDocuments items
| Field | Type | Required | Description |
|---|---|---|---|
documentType | string | Yes | Use 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. |
fileUrl | string | Yes | Stable 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
documentExpiryDateand omitdocumentPermanentlyValid. - For a permanently valid document, pass
documentPermanentlyValid: trueand omitdocumentExpiryDate.
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
{
"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.
- Call Get KYC Supplement Information with
emailandcardTypeId. - Continue only if
allowed=true. Use the original details to prepare the complete KYC payload, preservinglockedFieldsand the original email. - Include
originalRecordNoandexpectedVersionexactly as returned, plus a newrequestNo. - Check both the outer
codeanddata.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.
POST /openapi/v1/users/kyc
Content-Type: application/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 code | msg prefix | Action |
|---|---|---|
| 400 | KYC_SUPPLEMENT_INVALID | Include all required supplement fields; expectedVersion must be non-negative and cannot appear without originalRecordNo. |
| 400 | KYC_REQUEST_INVALID | Correct the request-number format. |
| 400 | KYC_SUPPLEMENT_FIELD_DENIED | Restore locked fields and preserve the original email. An email-change rejection can use descriptive text without this prefix. |
| 409 | KYC_REQUEST_CONFLICT | A 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. |
| 409 | KYC_VERSION_CONFLICT | Fetch supplement information again; the original material record or business version is stale. |
| 409 | KYC_SUPPLEMENT_DENIED | Supplementation is currently ineligible; read the returned reason and resolve the state or fee condition first. |
| 409 | KYC_SUPPLEMENT_STATUS_UNKNOWN | Current provider state could not be confirmed. Wait for platform synchronization/recovery before trying again. |
| 409 | KYC_SUPPLEMENT_STATE_CHANGED | Current provider state no longer allows supplementation. Resolve the state and fetch supplement information again. |
| 422 | KYC_SUPPLEMENT_DISABLED | The platform has disabled supplementation. Do not automatically retry. |
Example of a stale supplement basis:
{"code":409,"msg":"KYC_VERSION_CONFLICT: 申请已更新,请刷新补件资格后重试","data":null}Acceptance and Retry
| Result | Next action |
|---|---|
submissionStatus=ACCEPTED | The material was accepted. Query review status; do not generate another request number to submit it again. |
submissionStatus=REJECTED | The 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=UNKNOWN | Preserve 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 result | Use 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 conflict | Retain 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 disabled | Stop 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
| Field | Type | Description |
|---|---|---|
success | boolean/null | Submission acceptance: true for ACCEPTED, false for REJECTED, and null when UNKNOWN. This is not KYC approval. |
code | string/null | Business response code; may be absent when no definite result was received. Independent of the outer response code. |
message | string/null | Business response message; read together with submissionStatus. |
externalUserId | string/null | External user ID; may be absent when the service provider has not returned it. |
kycRecordId | string/null | KYC query identifier returned by the service provider; may be absent. Not the platform supplement material-record number originalRecordNo. |
status | string/null | FuturePay unified primary KYC status: NOT_SUBMITTED, PENDING (legacy), 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. |
submissionStatus | string/null | Submission outcome: ACCEPTED, REJECTED, UNKNOWN; may be null for queries. Independent of approval. |
channelStatus | string/null | Last 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.
