KYC
Flow Summary
The current KYC flow is:
Step 1. Upload KYC filesPOST /api/v2/media/file
Step 2. Validate document numberPOST /api/v2/cardholder-kyc/validate
Step 3. Submit KYC requestPOST /api/v2/cardholder-kyc
Step 4. Read latest KYC resultGET /api/v2/cardholder-kyc/latest
Step 5. Resubmit a provider-specific KYC when requiredPOST /api/v2/cardholder-kyc/resubmit
Step 6. Confirm cardholder creationGET /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_typemust be one ofpassport,visa, orid_numbernumber_idis trimmed before duplicate checks- Duplicate checks ignore old records in
FAILED,DECLINED, andNOT_VERIFY
Common failures
409: the document is already pending on another account409: 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
| Field | Type | Required | Description |
|---|---|---|---|
document_type | string | Yes | passport, visa, id_number |
number_id | string | Yes | Document number |
front_kyc_url | string | Yes | Object key of the uploaded document front image |
back_kyc_url | string | Conditional | Object key of the document back image. Required when document_type is id_number |
photo_urls | string | No | Object key of the selfie / holder photo |
first_name | string | Yes | Letters only |
last_name | string | Yes | Letters only |
nationality | string | No | Nationality, for example SINGAPOREAN |
country_code | string | No | Country code, for example SG |
date_of_birth | string | No | YYYY-MM-DD. If sent, the user must be at least 18 |
issue_date | string | No | Document issue date, YYYY-MM-DD |
expire_date | string | No | Document expiry date, YYYY-MM-DD |
gender | string | No | Gender, for example MALE |
file_type | string | Yes | jpg, png, pdf, jpeg |
address_line | string | Yes | Address line |
address_line_en | string | Conditional | Address in English. Required when UQPay is a target provider; checked by the service, not by request validation |
city | string | No | City |
state | string | Yes | State / province |
postal_code | string | Yes | Postal code |
proof_of_address_url | string | Conditional | Object key of the uploaded proof-of-address document. See Proof of address |
proof_of_address_issue_date | string | Conditional | Issue date of the proof-of-address document, YYYY-MM-DD |
proof_of_address_issuing_country | string | Conditional | Country 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_dateandproof_of_address_issuing_countryare 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-documentsto 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.
| Group | Country codes | Countries |
|---|---|---|
| Red | BD, BY, CN, CU, IN, ID, IR, IQ, KP, LK, MA, NP, RU, SY, TR, UA, US | Bangladesh, Belarus, China, Cuba, India, Indonesia, Iran, Iraq, North Korea, Sri Lanka, Morocco, Nepal, Russia, Syria, Türkiye, Ukraine, United States |
| Yellow | DZ, BT, CA, EG, ET, HK, IL, JO, MV, MX, NZ, OM, PK, PR, SA, TN, VE | Algeria, 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 = trueandis_email_verified = true first_nameandlast_namemust contain letters only- If
date_of_birthis provided, the user must be at least 18 years old - The same user cannot submit another KYC while they already have
PENDINGorAPPROVED - 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
v2create 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
v2stores address and country-identification fields directly on the KYC requestv2create no longer centers oncountry_idlike 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: zhif you want translatedreject_reasontext when available - The response returns the user's latest KYC record
- If the latest KYC is
DECLINEDand no card status exists yet, the API mapscard_statusto a failed state in the response - The latest response can include
address_line,city,state,postal_code,nationality,country_code,nationalityName, andcountryName
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
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Target provider. Supported value: UQPAY |
document_type | string | Yes | passport, visa, id_number |
number_id | string | Yes | Document number |
front_kyc_url | string | Yes | Object key of the uploaded document front image |
back_kyc_url | string | No | Object key of the document back image. Not required by request validation on resubmit |
photo_urls | string | No | Object key of the selfie / holder photo |
first_name | string | Yes | Letters only |
last_name | string | Yes | Letters only |
nationality | string | No | Nationality, for example SINGAPOREAN |
country_code | string | No | Country code, for example SG |
date_of_birth | string | No | Date of birth, YYYY-MM-DD |
issue_date | string | No | Document issue date, YYYY-MM-DD |
expire_date | string | No | Document expiry date, YYYY-MM-DD |
gender | string | No | Gender, for example MALE |
file_type | string | Yes | jpg, png, pdf, jpeg |
address_line | string | Yes | Address line |
address_line_en | string | Conditional | Address in English. Required when UQPay is a target provider; checked by the service, not by request validation |
city | string | Yes | City |
state | string | Yes | State / province |
postal_code | string | Yes | Postal code |
proof_of_address_url | string | Conditional | Object key of the uploaded proof-of-address document. See Proof of address |
proof_of_address_issue_date | string | Conditional | Issue date of the proof-of-address document, YYYY-MM-DD |
proof_of_address_issuing_country | string | Conditional | Country 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
DECLINEDorFAILED - 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
- Upload media first, then validate the document number before creating KYC.
- Treat
validateas a pre-check only; thecreateendpoint still performs the real conflict checks. - Treat
createas a multi-provider submission inv2, not just a single-provider KYC row. - Use
resubmitonly for one provider at a time and send the full identity payload again. - Poll or reload
latestafter submission to show status changes in the app. - After approval, use Cardholder to confirm the successful cardholder record exists before entering card flows.