Get KYC Supplement Information
GET/openapi/v2/users/kyc/supplement/contextReturns the current tenant's saved supplement eligibility, material-record number, business version, and original KYC details. This is a read-only query: it does not submit documents, freeze a fee, or force a service-provider status refresh. The request and response use the existing signing rules.
The response is a snapshot, not a reservation. The platform checks eligibility again when a supplement is submitted.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email of an existing user in the current tenant. It cannot be changed through supplementation. |
cardTypeId | string | Yes | Actual platform card product ID; the product determines the KYC channel. |
Request Example
HK_USD is a placeholder for an actual platform card product ID.
GET /openapi/v2/users/kyc/supplement/context?email=user%40example.com&cardTypeId=HK_USDResponse data
| Field | Type | Description |
|---|---|---|
allowed | boolean | Whether a supplement is currently allowed. Only proceed when true. |
reason | string/null | Reason supplementation is unavailable; normally empty when allowed. Use it for display, not as a fixed enum. |
originalRecordNo | string/null | Latest platform material-record number. Return it unchanged when submitting a supplement. It is not the provider's kycRecordId. |
expectedVersion | integer(int64)/null | Non-negative supplement business version. Return it unchanged together with originalRecordNo; never generate or increment it yourself. |
applicationNo | string/null | Root platform application associated with the original fee. Several material records may share it. It is not a submit parameter and cannot replace originalRecordNo. |
lockedFields | string[] | Fields the product does not allow changing. Preserve their original values. An empty array does not permit changing the email or bypassing normal validation. |
submission | object/null | Original KYC details for editing, returned when allowed. When denied it is null or omitted; there is no material record before the first application. |
KYC material fields follow Submit User KYC. firstName and lastName are accepted submission fields: when present, preserve and submit the pair, which takes precedence over legacy name. Legacy details containing only name remain supported. Preserve contactAddress as the detailed address and return any residential* fields separately; do not manually concatenate them. Build the submission from fields accepted by that endpoint, and supply the user's memberId and the selected cardTypeId. Do not POST the entire query response. Empty optional fields may be null or omitted.
Eligible Response Example
All example values are synthetic. This example uses a Mastercard Hong Kong USD card.
{
"code": 200,
"msg": "操作成功",
"data": {
"allowed": true,
"reason": null,
"originalRecordNo": "KYC_RECORD_002",
"expectedVersion": 3,
"applicationNo": "KYC_RECORD_001",
"lockedFields": [],
"submission": {
"email": "user@example.com",
"name": "Test User",
"birthday": "1990-01-01",
"documentType": "passport",
"documentNumber": "SYNTHETIC_ONLY",
"frontImageUrl": "https://files.example.com/kyc/front.jpg",
"backImageUrl": null,
"documentCountry": "HK",
"documentExpiryDate": "2030-12-31",
"documentPermanentlyValid": false,
"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": "Original contact address",
"supportingDocuments": [],
"firstName": "Test",
"lastName": "User",
"residentialCity": null,
"residentialCountryCode": null,
"residentialPostalCode": null,
"residentialState": null
}
}
}Ineligible Response Example
code=200 means the query succeeded. It does not mean supplementation is allowed. The example below represents an already approved application; actual reason text depends on the denial.
{
"code": 200,
"msg": "操作成功",
"data": {
"allowed": false,
"reason": "认证已成功,不能补件",
"originalRecordNo": "KYC_RECORD_003",
"expectedVersion": 4,
"applicationNo": "KYC_RECORD_001",
"lockedFields": [],
"submission": null
}
}Eligibility and locked fields
| Product | Supplement conditions |
|---|---|
| Mastercard Hong Kong USD card | KYC has not succeeded and the original application remains eligible. A confirmed failed application must be resubmitted as a new application after the original fee is released. |
| Mastercard Global USD card | The raw review status must be modify. Other statuses, including pending review, do not allow supplementation. |
Both products also require platform supplementation to be enabled, a known application state, and an eligible original fee. Processing or unknown submissions must be synchronized or recovered by the platform before proceeding.
For the Mastercard Global USD card, the current locked fields are selfieImageUrl, gender, annualIncome, occupation, position, supportingDocuments, documentExpiryDate, and documentPermanentlyValid. Always use the returned lockedFields list. The original email cannot be changed for either product.
Business version and next step
| Event | Effect |
|---|---|
| A normal sync with unchanged review basis, a timestamp/message update, or a failed query | Does not itself advance the supplement business version. Unknown state can still deny supplementation. |
| Review becomes approved/failed, review eligibility changes, or the associated identity/application changes | May advance the business version; fetch supplement information again. |
| Another submission creates a new material record | The old originalRecordNo is stale, even if the numeric versions happen to match. |
- Check
allowed; if false, displayreasonand wait for the required state recovery or use the appropriate new-application flow. - Edit permitted fields while preserving locked values.
- Submit the complete KYC payload, a new
requestNo, and the returnedoriginalRecordNoandexpectedVersionto Submit User KYC. - Handle acceptance, conflicts, and unknown results using that page's retry rules. Querying this endpoint alone never submits a supplement.
