Skip to content

Get KYC Supplement Information ​

GET /openapi/v1/users/kyc/supplement/context

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

FieldTypeRequiredDescription
emailstringYesEmail of an existing user in the current tenant. It cannot be changed through supplementation.
cardTypeIdstringYesActual 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.

http
GET /openapi/v1/users/kyc/supplement/context?email=user%40example.com&cardTypeId=HK_USD

Response data ​

FieldTypeDescription
allowedbooleanWhether a supplement is currently allowed. Only proceed when true.
reasonstring/nullReason supplementation is unavailable; normally empty when allowed. Use it for display, not as a fixed enum.
originalRecordNostring/nullLatest platform material-record number. Return it unchanged when submitting a supplement. It is not the provider's kycRecordId.
expectedVersioninteger(int64)/nullNon-negative supplement business version. Return it unchanged together with originalRecordNo; never generate or increment it yourself.
applicationNostring/nullRoot platform application associated with the original fee. Several material records may share it. It is not a submit parameter and cannot replace originalRecordNo.
lockedFieldsstring[]Fields the product does not allow changing. Preserve their original values. An empty array does not permit changing the email or bypassing normal validation.
submissionobject/nullOriginal 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.

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

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

EventEffect
A normal sync with unchanged review basis, a timestamp/message update, or a failed queryDoes 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 changesMay advance the business version; fetch supplement information again.
Another submission creates a new material recordThe old originalRecordNo is stale, even if the numeric versions happen to match.
  1. Check allowed; if false, display reason and wait for the required state recovery or use the appropriate new-application flow.
  2. Edit permitted fields while preserving locked values.
  3. Submit the complete KYC payload, a new requestNo, and the returned originalRecordNo and expectedVersion to Submit User KYC.
  4. Handle acceptance, conflicts, and unknown results using that page's retry rules. Querying this endpoint alone never submits a supplement.