Get KYC Supplement Information
GET/openapi/v1/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, required by the V1 query contract. V1 retains its existing Mastercard Hong Kong USD card routing. |
Request Example
HK_USD is a placeholder for an actual platform card product ID.
GET /openapi/v1/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. The snapshot may also include firstName and lastName for display. Build the submission from fields accepted by that endpoint, and supply the user's memberId. 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
V1 retains its existing Mastercard Hong Kong USD card routing. Supplementation requires KYC not to have succeeded and the original application to remain eligible. A confirmed failed application must be resubmitted as a new application after the original fee is released.
The platform must also have supplementation enabled, a known application state, and an eligible original fee. Processing or unknown submissions must be synchronized or recovered by the platform before proceeding.
This product currently returns an empty lockedFields array. Always follow the actual response, and never change the original email through supplementation. For the Mastercard Global USD card, use V2 Get KYC Supplement Information.
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.
