Skip to content

Get KYC Supplement Information ​

GET /openapi/v2/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; the product determines the KYC channel.

Request Example ​

HK_USD is a placeholder for an actual platform card product ID.

http
GET /openapi/v2/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. 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.

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 ​

ProductSupplement conditions
Mastercard Hong Kong USD cardKYC 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 cardThe 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 ​

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.