Submit User KYC
POST/openapi/v2/users/kyc| Item | Value |
|---|---|
| HTTP method | POST |
| Request path | /openapi/v2/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. |
cardTypeId | string | Yes | Card product ID used to determine the KYC material requirements. |
email | string | Yes | Must match the email of the user identified by memberId; comparison is case-insensitive. |
memberId | string | Yes | FuturePay platform member ID returned by user creation; must belong to the current tenant and identify the same user as email. |
firstName | string | Conditional | Given name for this KYC submission; provide together with lastName. Takes precedence over legacy name. |
lastName | string | Conditional | Family name for this KYC submission; provide together with firstName. |
name | string | Conditional | Deprecated compatibility field for a full name. Required only when neither separate name is supplied. New integrations should use firstName and lastName. |
birthday | string | Yes | Date of birth, in the format yyyy-MM-dd. |
documentType | string | Yes | Document type: passport, id_card, driver_license, or resident_permit; supported types vary by product as shown below. |
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 and omit documentExpiryDate. false does not indicate permanent validity; an expiry date is still required. |
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 depending on the card product and document type, as shown below. |
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 accepted by the selected product, for example Company Owner; do not substitute a free-form job title. |
nationality | string | Yes | Nationality, as a two-letter country or region code. |
contactAddress | string | Yes | Detailed residential address, such as street, building and unit. Keep this field name; do not pre-concatenate the separate residential fields. See the mapping rules below. |
residentialCity | string | Conditional | Residential city; required for the Mastercard Global USD card. |
residentialCountryCode | string | Conditional | Two-letter residential country or region code; required for the Mastercard Global USD card. If supplied for another product, it must still be a two-letter code. |
residentialPostalCode | string | Conditional | Residential postal code; required for the Mastercard Global USD card. |
residentialState | string | Conditional | Residential state or province; required for the Mastercard Global USD card. |
supportingDocuments | array | Conditional | At least one item is required for non-HK nationals using the Mastercard Hong Kong USD card; not required otherwise. If supplied, a maximum of 10 items is allowed. See the item format below. |
Names and residential address
Provide nonblank firstName and lastName together. The platform trims their outer whitespace and uses this pair before name: the Mastercard Global USD card receives the names separately; the Mastercard Hong Kong USD card receives firstName + " " + lastName. If only one new name is nonblank, the request is rejected even when name is present.
Legacy requests containing only name remain valid. For the Mastercard Global USD card, missing separate names continue to come from the registered user details; the platform does not guess how to split name.
Keep contactAddress as the detailed address. The Mastercard Global USD card receives it along with the separate residential* fields. For the Mastercard Hong Kong USD card, the platform joins nonblank fields in this order: residentialCountryCode, residentialState, residentialCity, contactAddress, residentialPostalCode, separated by , . When all four structured fields are absent, it passes contactAddress unchanged. For example, HK, Hong Kong, Kowloon, 12 Test Road, Unit 3, 999077 become HK, Hong Kong, Kowloon, 12 Test Road, Unit 3, 999077.
The platform retains the separate address values for supplement editing. Return the detailed address and the separate fields when supplementing; do not replace contactAddress with the joined address.
Requirements by card product
The product identified by cardTypeId determines these requirements. No additional product-category parameter is needed.
| Material / field | Mastercard Hong Kong USD card | Mastercard Global USD card |
|---|---|---|
documentType | passport, id_card, driver_license | passport, id_card, resident_permit |
backImageUrl | Optional for passports; required for identity cards and driving licences | Required for all supported document types |
All four residential* fields | Not required; may be omitted | All required |
supportingDocuments | Required for non-HK nationals; optional for HK nationals | Not required |
Chinese nationality (nationality: CN) | Follow the document and supporting-proof requirements above | Must use resident_permit as the primary document for this submission |
Other fields marked "Yes" remain required for every product. Missing product-required materials are rejected before creating a KYC record, charging fees, uploading materials, or submitting for review.
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 an expiry date nor a true permanent-validity flag, is rejected. For dated documents, omit the flag; false alone is insufficient.
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.
Create the user first, then submit KYC using the returned memberId. A missing, blank, unknown-in-this-tenant, or email-mismatched memberId is rejected; there is no fallback to email lookup. This requirement applies only to V2 KYC submission and does not change user identification rules for other endpoints.
Request example
Mastercard Global USD card
{
"cardTypeId": "VIRTUAL_USD",
"email": "user@example.com",
"memberId": "MEMBER_001",
"firstName": "Test",
"lastName": "User",
"birthday": "1990-01-01",
"documentType": "passport",
"documentNumber": "P1234567",
"documentCountry": "HK",
"documentExpiryDate": "2030-12-31",
"frontImageUrl": "https://example.com/front.jpg",
"backImageUrl": "https://example.com/back.jpg",
"selfieImageUrl": "https://example.com/selfie.jpg",
"phoneCountryCode": "+852",
"phoneNumber": "91234567",
"gender": "male",
"annualIncome": "50000-200000",
"occupation": "Engineer",
"position": "Company Owner",
"nationality": "HK",
"contactAddress": "12 Test Road, Unit 3",
"residentialCity": "Hong Kong",
"residentialCountryCode": "HK",
"residentialPostalCode": "999077",
"residentialState": "Hong Kong"
}Mastercard Hong Kong USD card (HK nationality, passport)
This scenario does not require the document back image, structured residential address, or supporting documents.
{
"cardTypeId": "HK_USD",
"email": "user@example.com",
"memberId": "MEMBER_001",
"firstName": "Test",
"lastName": "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": "Company Owner",
"nationality": "HK",
"contactAddress": "Hong Kong"
}Both cardTypeId values are placeholders; replace them with the actual IDs of the corresponding products. Replace MEMBER_001 with the actual memberId returned by user creation.
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, card product ID, and supplement basis with actual values. Other products retain their product-specific requirements.
POST /openapi/v2/users/kyc
Content-Type: application/json{
"cardTypeId": "HK_USD",
"email": "user@example.com",
"memberId": "member-123",
"requestNo": "KYC_SUPPLEMENT_20261104_001",
"originalRecordNo": "KYC_RECORD_002",
"expectedVersion": 3,
"firstName": "Test",
"lastName": "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. V2 binding and Bean Validation HTTP 400 responses are described in Common Responses.
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 | Aggregate user KYC status. Values and meanings are listed below; it does not imply approval for every channel. |
channelStatus | string/null | Last confirmed unified KYC status for the selected product's channel. An unaccepted or unknown submission does not overwrite it. See the values below. |
subStatus | string/null | Raw service-provider KYC sub-status; additional values may be introduced. |
submissionStatus | string/null | Submission outcome: ACCEPTED, REJECTED, UNKNOWN; may be null for queries. Independent of approval. |
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.
Unified KYC status values
| Value | Meaning |
|---|---|
NOT_SUBMITTED | Not submitted |
PENDING | Legacy pending value |
PENDING_APPROVAL | Pending review |
APPROVED | Approved |
REJECTED | Review rejected |
MODIFY | Additional or corrected material required |
CERT_REQUIRED | Certification still required |
FAILED | Platform processing failure or retained historical failure; does not itself prove review rejection |
Empty optional values may be null or omitted. When submissionStatus=UNKNOWN, success is null and identifiers may be absent. Preserve the request and follow the retry rules above; do not treat an outer code=200 as approval.
Input validation errors: V2 common responses.
