Mobile User
Cardholder
Read the latest approved cardholder record created after successful KYC processing.
Flow Summary
The current cardholder lookup flow is:
Step 1. Submit KYC and wait for approval
Start from KYC
Step 2. Read the linked cardholder recordGET /api/v2/cardholder/latest
Step 3. Read one provider-specific cardholder when neededGET /api/v2/cardholder/by-provider
This route should be treated as a protected route and sent with:
Authorization: Bearer <access_token>
1. Get Latest Cardholder
GET /api/v2/cardholder/latest
Returns the latest successful cardholder record for the current mobile user.
Important backend behavior
- The lookup is scoped to the authenticated mobile user
- The repository only returns records where
card_holders.card_status = SUCCESS - If no successful cardholder exists yet, the API returns not found
- The handler comment says pending or approved, but the current query is stricter and only returns successful cardholder rows
Response shape
The response is the cardholder record already linked to the approved KYC result, including:
- cardholder
idanduuid first_name,last_name,document_type,number_iddate_of_birth,issue_date,expire_datestatusandcard_statuscountryname/code when linked- transformed
photo_urlsandidCard_urls count_cardfor cards already linked to that cardholdercard_holder_kyc_id
Notes
is_expireis calculated by comparingexpire_dateto the current date- This endpoint is the cleanest way for the app to confirm that KYC has already produced an actual cardholder account
- Use this before card flows that require an existing successful cardholder
2. Get Cardholder By Provider
GET /api/v2/cardholder/by-provider
Returns the cardholder record for one selected provider.
Query parameter
provideris required- Current documented value is
UQPAY
Example
GET /api/v2/cardholder/by-provider?provider=UQPAY
Notes
- Use this route when the app needs to know the user’s provider-specific cardholder state
- This is a v2-only helper route and does not exist in the current v1 docs
- When the app only needs "the best current usable cardholder",
latestis the simpler route