Mobile User

KYC

Validate identity documents, submit cardholder KYC, and read the latest KYC status.

Flow Summary

The current KYC flow is:

Step 1. Upload KYC files
POST /api/v2/media/file

Step 2. Validate document number
POST /api/v2/cardholder-kyc/validate

Step 3. Submit KYC request
POST /api/v2/cardholder-kyc

Step 4. Read latest KYC result
GET /api/v2/cardholder-kyc/latest

Step 5. Resubmit a provider-specific KYC when required
POST /api/v2/cardholder-kyc/resubmit

Step 6. Confirm cardholder creation
GET /api/v2/cardholder/latest

All KYC routes below should be treated as protected routes and sent with:

Authorization: Bearer <access_token>

The two POST endpoints also support either plain JSON or the encrypted wrapper described in Overview.

1. Upload KYC Files First

The KYC create request expects file references, not raw file bytes.

Upload the document images first with File Upload, then pass the returned object path or internal URL into the KYC payload.

Typical files:

  • front document image
  • back document image for id_number
  • optional selfie or supporting photo

2. Validate Document Number

POST /api/v2/cardholder-kyc/validate

This checks whether the same document number is already in use or already pending verification for another account.

Request

{
  "document_type": "passport",
  "number_id": "P12345678"
}

Success response

{
  "status_code": 200,
  "message": "Document is valid",
  "data": null
}

Rules

  • document_type must be one of passport, visa, or id_number
  • number_id is trimmed before duplicate checks
  • Duplicate checks ignore old records in FAILED, DECLINED, and NOT_VERIFY

Common failures

  • 409: the document is already pending on another account
  • 409: the document is already verified on another account

3. Submit KYC Request

POST /api/v2/cardholder-kyc

This creates a new v2 cardholder KYC request for the authenticated mobile user.

Unlike v1, the v2 create route is provider-aware and can fan out to multiple active card providers automatically.

Request

{
  "document_type": "passport",
  "number_id": "P12345678",
  "front_kyc_url": "media/private/kyc/front-passport.jpg",
  "photo_urls": "media/private/kyc/selfie.jpg",
  "first_name": "Wei",
  "last_name": "Chen",
  "nationality": "SINGAPOREAN",
  "country_code": "SG",
  "date_of_birth": "1995-04-18",
  "issue_date": "2022-01-01",
  "expire_date": "2032-01-01",
  "gender": "MALE",
  "file_type": "jpg",
  "address_line": "1 Raffles Place",
  "address_line_en": "1 Raffles Place",
  "city": "Singapore",
  "state": "Singapore",
  "postal_code": "048616"
}

If document_type is id_number, back_kyc_url is also required.

Request fields

FieldTypeRequiredDescription
document_typestringYespassport, visa, id_number
number_idstringYesDocument number
front_kyc_urlstringYesObject key of the uploaded document front image
back_kyc_urlstringConditionalObject key of the document back image. Required when document_type is id_number
photo_urlsstringNoObject key of the selfie / holder photo
first_namestringYesLetters only
last_namestringYesLetters only
nationalitystringNoNationality, for example SINGAPOREAN
country_codestringNoCountry code, for example SG
date_of_birthstringNoYYYY-MM-DD. If sent, the user must be at least 18
issue_datestringNoDocument issue date, YYYY-MM-DD
expire_datestringNoDocument expiry date, YYYY-MM-DD
genderstringNoGender, for example MALE
file_typestringYesjpg, png, pdf, jpeg
address_linestringYesAddress line
address_line_enstringConditionalAddress in English. Required when UQPay is a target provider; checked by the service, not by request validation
citystringNoCity
statestringYesState / province
postal_codestringYesPostal code
proof_of_address_urlstringConditionalObject key of the uploaded proof-of-address document. See Proof of address
proof_of_address_issue_datestringConditionalIssue date of the proof-of-address document, YYYY-MM-DD
proof_of_address_issuing_countrystringConditionalCountry that issued the proof-of-address document, ISO 3166-1 alpha-2 (for example SG)

Proof of address

  • proof_of_address_url, proof_of_address_issue_date and proof_of_address_issuing_country are required when the user's nationality is in the Red or Yellow group and UQPay is a target provider
  • This is checked by the service, not by request validation, so a missing value is rejected after the request is accepted for processing
  • Call GET /api/v2/cardholder-kyc/required-documents to find out which documents are required before you submit
  • Upload the proof-of-address file the same way as the other KYC files, then send its object key in proof_of_address_url

Red and Yellow nationality groups

If the user's nationality is in one of these groups and UQPay is a target provider, send all three proof-of-address fields on POST /api/v2/cardholder-kyc and POST /api/v2/cardholder-kyc/resubmit. For any other nationality, the proof-of-address fields are not required.

GroupCountry codesCountries
RedBD, BY, CN, CU, IN, ID, IR, IQ, KP, LK, MA, NP, RU, SY, TR, UA, USBangladesh, Belarus, China, Cuba, India, Indonesia, Iran, Iraq, North Korea, Sri Lanka, Morocco, Nepal, Russia, Syria, Türkiye, Ukraine, United States
YellowDZ, BT, CA, EG, ET, HK, IL, JO, MV, MX, NZ, OM, PK, PR, SA, TN, VEAlgeria, Bhutan, Canada, Egypt, Ethiopia, Hong Kong, Israel, Jordan, Maldives, Mexico, New Zealand, Oman, Pakistan, Puerto Rico, Saudi Arabia, Tunisia, Venezuela

For example, a user with Indian nationality (IN, Red group) adds these fields to the normal create or resubmit body:

{
  "proof_of_address_url": "media/private/kyc/proof-of-address.pdf",
  "proof_of_address_issue_date": "2026-09-01",
  "proof_of_address_issuing_country": "IN"
}

Important backend rules

  • The mobile user must have both is_phone_verified = true and is_email_verified = true
  • first_name and last_name must contain letters only
  • If date_of_birth is provided, the user must be at least 18 years old
  • The same user cannot submit another KYC while they already have PENDING or APPROVED
  • The same document number cannot be reused if another active KYC already owns it
  • Incoming internal file URLs are sanitized before storage
  • The server checks which card providers are currently active from card-schema configuration
  • One v2 create request can target multiple providers at once
  • If no provider is active, the API returns an error instead of creating the KYC row

Success response

{
  "status_code": 201,
  "message": "Success",
  "data": {
    "id": 87,
    "uuid": "0d65f58d-47f6-43d7-84b2-4bdc8d44e391",
    "first_name": "Wei",
    "last_name": "Chen",
    "document_type": "passport",
    "number_id": "P12345678",
    "status": "PENDING",
    "file_type": "jpg",
    "address_line": "1 Raffles Place",
    "city": "Singapore",
    "state": "Singapore",
    "postal_code": "048616",
    "nationality": "SINGAPOREAN",
    "country_code": "SG",
    "kyc_urls": {
      "front_kyc_url": "https://...",
      "back_kyc_url": ""
    },
    "photo_urls": "https://..."
  }
}

Notes

  • The response returns transformed file URLs, not just the raw stored object keys
  • v2 stores address and country-identification fields directly on the KYC request
  • v2 create no longer centers on country_id like the older flow

4. Read Latest KYC

GET /api/v2/cardholder-kyc/latest

This returns the latest KYC record for the current user, with transformed URLs and translated reject reasons.

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "uuid": "0d65f58d-47f6-43d7-84b2-4bdc8d44e391",
    "status": "PENDING",
    "card_status": "PENDING",
    "is_kyc_expire": false,
    "reject_reason": "",
    "kyc_urls": {
      "front_kyc_url": "https://...",
      "back_kyc_url": ""
    },
    "mobile_user": {
      "phone": "91234567",
      "email": "user@example.com"
    }
  }
}

Notes

  • Send Accept-Language: zh if you want translated reject_reason text when available
  • The response returns the user's latest KYC record
  • If the latest KYC is DECLINED and no card status exists yet, the API maps card_status to a failed state in the response
  • The latest response can include address_line, city, state, postal_code, nationality, country_code, nationalityName, and countryName

5. Resubmit Provider KYC

POST /api/v2/cardholder-kyc/resubmit

Submits or resubmits KYC for one specific provider using the full identity payload again.

Request

This is a full provider-specific KYC request, not a partial retry action. The client must send the identity fields again.

{
  "provider": "UQPAY",
  "document_type": "passport",
  "number_id": "P12345678",
  "front_kyc_url": "media/private/kyc/front-passport.jpg",
  "photo_urls": "media/private/kyc/selfie.jpg",
  "first_name": "Wei",
  "last_name": "Chen",
  "nationality": "SINGAPOREAN",
  "country_code": "SG",
  "date_of_birth": "1995-04-18",
  "issue_date": "2022-01-01",
  "expire_date": "2032-01-01",
  "gender": "MALE",
  "file_type": "jpg",
  "address_line": "1 Raffles Place",
  "address_line_en": "1 Raffles Place",
  "city": "Singapore",
  "state": "Singapore",
  "postal_code": "048616"
}

Request fields

FieldTypeRequiredDescription
providerstringYesTarget provider. Supported value: UQPAY
document_typestringYespassport, visa, id_number
number_idstringYesDocument number
front_kyc_urlstringYesObject key of the uploaded document front image
back_kyc_urlstringNoObject key of the document back image. Not required by request validation on resubmit
photo_urlsstringNoObject key of the selfie / holder photo
first_namestringYesLetters only
last_namestringYesLetters only
nationalitystringNoNationality, for example SINGAPOREAN
country_codestringNoCountry code, for example SG
date_of_birthstringNoDate of birth, YYYY-MM-DD
issue_datestringNoDocument issue date, YYYY-MM-DD
expire_datestringNoDocument expiry date, YYYY-MM-DD
genderstringNoGender, for example MALE
file_typestringYesjpg, png, pdf, jpeg
address_linestringYesAddress line
address_line_enstringConditionalAddress in English. Required when UQPay is a target provider; checked by the service, not by request validation
citystringYesCity
statestringYesState / province
postal_codestringYesPostal code
proof_of_address_urlstringConditionalObject key of the uploaded proof-of-address document. See Proof of address
proof_of_address_issue_datestringConditionalIssue date of the proof-of-address document, YYYY-MM-DD
proof_of_address_issuing_countrystringConditionalCountry that issued the proof-of-address document, ISO 3166-1 alpha-2 (for example SG)

Differences from create: provider is required, city is required, and back_kyc_url is not enforced by request validation. The proof-of-address fields follow the same rules as create, see Proof of address.

Important backend behavior

  • Use it when one provider requires a fresh submission or resubmission after an earlier result
  • The request is treated as a full provider KYC payload, not a tiny patch request
  • If the provider already has a previous cardholder row, resubmit is only allowed when that provider is in DECLINED or FAILED
  • If the requested provider does not have a row yet, the request can create the missing provider-specific record by using the latest available KYC context
  • If there is already a pending KYC for the same provider, the API returns a conflict
  • If the provider is inactive, the API returns an error

6. Confirm Cardholder Creation

GET /api/v2/cardholder/latest

Once KYC is approved, call this endpoint to confirm the backend has already created a successful cardholder record.

Use the dedicated Cardholder page for the full response shape and behavior details.

Integration Notes

  1. Upload media first, then validate the document number before creating KYC.
  2. Treat validate as a pre-check only; the create endpoint still performs the real conflict checks.
  3. Treat create as a multi-provider submission in v2, not just a single-provider KYC row.
  4. Use resubmit only for one provider at a time and send the full identity payload again.
  5. Poll or reload latest after submission to show status changes in the app.
  6. After approval, use Cardholder to confirm the successful cardholder record exists before entering card flows.
Copyright © 2026