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 record
GET /api/v2/cardholder/latest

Step 3. Read one provider-specific cardholder when needed
GET /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 id and uuid
  • first_name, last_name, document_type, number_id
  • date_of_birth, issue_date, expire_date
  • status and card_status
  • country name/code when linked
  • transformed photo_urls and idCard_urls
  • count_card for cards already linked to that cardholder
  • card_holder_kyc_id

Notes

  • is_expire is calculated by comparing expire_date to 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

  • provider is 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", latest is the simpler route
Copyright © 2026