Skip to content

Submit User KYC ​

POST /openapi/v2/users/kyc
ItemValue
HTTP methodPOST
Request path/openapi/v2/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.
cardTypeIdstringYesCard product ID used to determine the KYC material requirements.
emailstringYesMust match the email of the user identified by memberId; comparison is case-insensitive.
memberIdstringYesFuturePay platform member ID returned by user creation; must belong to the current tenant and identify the same user as email.
firstNamestringConditionalGiven name for this KYC submission; provide together with lastName. Takes precedence over legacy name.
lastNamestringConditionalFamily name for this KYC submission; provide together with firstName.
namestringConditionalDeprecated compatibility field for a full name. Required only when neither separate name is supplied. New integrations should use firstName and lastName.
birthdaystringYesDate of birth, in the format yyyy-MM-dd.
documentTypestringYesDocument type: passport, id_card, driver_license, or resident_permit; supported types vary by product as shown below.
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 and omit documentExpiryDate. false does not indicate permanent validity; an expiry date is still required.
frontImageUrlstringYesURL returned after uploading the front image of the document.
backImageUrlstringConditionalURL returned after uploading the back image of the document; required depending on the card product and document type, as shown below.
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 accepted by the selected product, for example Company Owner; do not substitute a free-form job title.
nationalitystringYesNationality, as a two-letter country or region code.
contactAddressstringYesDetailed 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.
residentialCitystringConditionalResidential city; required for the Mastercard Global USD card.
residentialCountryCodestringConditionalTwo-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.
residentialPostalCodestringConditionalResidential postal code; required for the Mastercard Global USD card.
residentialStatestringConditionalResidential state or province; required for the Mastercard Global USD card.
supportingDocumentsarrayConditionalAt 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 / fieldMastercard Hong Kong USD cardMastercard Global USD card
documentTypepassport, id_card, driver_licensepassport, id_card, resident_permit
backImageUrlOptional for passports; required for identity cards and driving licencesRequired for all supported document types
All four residential* fieldsNot required; may be omittedAll required
supportingDocumentsRequired for non-HK nationals; optional for HK nationalsNot required
Chinese nationality (nationality: CN)Follow the document and supporting-proof requirements aboveMust 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 ​

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 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 ​

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

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

  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, card product ID, and supplement basis with actual values. Other products retain their product-specific requirements.

http
POST /openapi/v2/users/kyc
Content-Type: application/json
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 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/nullAggregate user KYC status. Values and meanings are listed below; it does not imply approval for every channel.
channelStatusstring/nullLast confirmed unified KYC status for the selected product's channel. An unaccepted or unknown submission does not overwrite it. See the values below.
subStatusstring/nullRaw service-provider KYC sub-status; additional values may be introduced.
submissionStatusstring/nullSubmission 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 ​

ValueMeaning
NOT_SUBMITTEDNot submitted
PENDINGLegacy pending value
PENDING_APPROVALPending review
APPROVEDApproved
REJECTEDReview rejected
MODIFYAdditional or corrected material required
CERT_REQUIREDCertification still required
FAILEDPlatform 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.