Cardholder

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/v1/cardholder/latest

This route should be treated as a protected route and sent with:

Authorization: Bearer <access_token>

1. Get Latest Cardholder

GET /api/v1/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