> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cardholders (Card Issuing)

> The merchant dashboard Cards > Cardholders page — view, search, and filter all cardholders on the account, their verification status, and card count, and create, edit, or export cardholders from here.

## What this is

This is the **Cardholders** page under the **Cards** module in the merchant dashboard (left nav **Cards** -> top tab **Cardholders**, page subtitle "Onboard and manage your cardholders"). A cardholder is a person who can be assigned a card (e.g. an employee or team member); use this page to see all cardholders on the account, their **verification status** and **card count**, and to create a new cardholder, edit cardholder details, or export the cardholder list. Set up a person here before issuing them a card, or use this page to look up a cardholder's information or see who has passed verification.

## Steps

Open the cardholder list:

1. In the left nav, click **Cards**.
2. Select the **Cardholders** tab at the top (siblings: Overview, Cards, Transactions, Low balance).
3. Use the **Status / Name / Email / Date range** filters at the top to narrow the list.

Add a cardholder:

1. Click **Create cardholder** in the top right (requires cardholder write permission — otherwise this button is not shown).
2. Fill in **Legal first name**, **Legal last name**, **Business email**, **Phone number** (with country code); **Date of birth** is optional.
3. Select **Identification type** (ID Card / Passport / Driver's License) and fill in **Identification number**.
4. Fill in **Residential address** (Country, State, City, Postal code, Address line1, Address line2).
5. Fill in **Delivery address** (where the physical card will be shipped); check **Use residential address as delivery address** to reuse it directly.
6. If an **Employer declaration** is required, download the template, fill it in, and upload it.
7. Click **Confirm** to submit; success shows "Create cardholder success!"

Edit a cardholder: click the row's trailing **...** menu -> **Edit cardholder** (requires write permission), update the details, then **Update**.

Export: click **Export** in the toolbar to export the list; or select rows and click **Export selected** to export the selection (up to 100 rows per export).

## Fields and statuses

**List columns:**

| Column     | Meaning (merchant view)                                                               |
| ---------- | ------------------------------------------------------------------------------------- |
| Cardholder | Cardholder name + cardholder ID (ID copyable inline; truncated in the middle if long) |
| Email      | The cardholder's business email                                                       |
| Phone      | The cardholder's phone number (shows `---` if none)                                   |
| Cards      | The number of cards assigned to this cardholder (shows `---` if none)                 |
| Status     | Verification status, see below                                                        |
| Created    | Date and time the cardholder was created                                              |

**Top stats**: Total, Verified, Pending, Failed (the total cardholder count and counts for each verification status).

**Verification status:**

| Status     | Meaning                                                                                 |
| ---------- | --------------------------------------------------------------------------------------- |
| Verified   | The cardholder's identity has passed verification                                       |
| Pending    | Verification is being processed                                                         |
| Failed     | Verification failed                                                                     |
| Invited    | An invitation has been sent; the person has not yet completed registration/verification |
| Incomplete | Verification information has not been fully filled in                                   |

> If a "Failed" status has a review remark, hovering the status badge shows the failure reason.

**Create cardholder form fields:** Legal first name, Legal last name, Business email, Phone number (+ country code), Date of birth (optional), Identification type (ID Card/Passport/Driver's License), Identification number, Residential address (Country/State/City/Postal code/Address line1/Address line2), Delivery address (for physical card shipping; can reuse residential address), Employer declaration (template downloadable).

## Edge cases and troubleshooting

* **List shows "No cardholders yet"**: no cardholders exist yet; the hint reads "Add your first cardholder to get started" — click **Create cardholder** to add one.
* **Filtered to "No cardholders match your filters"**: the current filters have no match; the hint reads "Try adjusting your filter criteria" — clear filters and check again.
* **Can't see the "Create cardholder" button or the row's "..." menu**: this account lacks cardholder write permission; read-only accounts don't show these actions.
* **Phone / card count shows `---`**: no data available for that field yet.
* **When creating, it prompts "employer declaration replacement is required before submitting"**: download the employer declaration template, fill it in, and upload it before submitting.
* **Uploading a file errors "file size should not exceed 2MB"**: the attachment (e.g. employer declaration) exceeds the 2MB limit — compress and re-upload.
* **Export selection shows a cap reached message**: up to 100 rows per export; export in batches if you exceed this.

## Common questions (Q\&A)

* **Q: Where do I see cardholders? / How do I check all cardholders?** A: Left nav **Cards** -> top **Cardholders** tab; the list shows all cardholders on the account.
* **Q: How do I add a cardholder? / How do I invite a team member to get a card?** A: Click **Create cardholder** in the top right of the Cardholders page, fill in name, business email, phone, ID document, and address, then confirm.
* **Q: What information does adding a cardholder require?** A: Legal name, business email, phone, identification type and number, residential address, and delivery address; date of birth is optional, and a delivery address is needed for physical cards.
* **Q: What verification statuses exist and what do they mean?** A: Verified, Pending, Failed, Invited, Incomplete — each corresponds to a cardholder's KYC/verification progress.
* **Q: A cardholder's status shows "Failed" — what now?** A: Verification failed; if there's a review remark, hover the status badge to see the reason, then resupply the required information and retry.
* **Q: How do I edit a cardholder's details?** A: Select **Edit cardholder** from that row's **...** menu (requires write permission).
* **Q: How do I export the cardholder list?** A: Click **Export** in the toolbar to export all, or select rows and click **Export selected** (up to 100 rows).
* **Q: Why don't I have a "Create cardholder" button?** A: This account lacks cardholder write permission; read-only accounts don't see create/edit entry points.
* **Q: Where do I see how many cards a cardholder has?** A: The **Cards** column in the list shows that cardholder's card count.
* **Q: How do I find a cardholder by name or email?** A: Use the **Name / Email** search box at the top.